How ethmarks/ascii-globe works
Project type and purpose
• ASCII-Globe is a standalone Python CLI tool (open-source utility) that renders a 3D globe in the terminal using ASCII characters.
• It has three main responsibilities:
a. Generating or acquiring “texture” data (ASCII maps of the Earth).
b. Rendering a rotating ASCII globe in real time and/or saving the per-frame data.
c. Converting saved frames into an animated GIF.
File structure
• Top-level scripts:
• generate_texture.py → texture‐generation pipeline that converts image files (e.g., NASA JPEGs) into ASCII “.txt” textures.
• render.py → core rendering engine: loads textures, computes per‐frame ASCII output, streams to console or saves to JSON.
• frames_to_gif.py → post‐processing: reads saved frame JSON, renders text frames to images, assembles into a GIF.
• frames_to_gif.py → same as above.
• frames_to_gif.py → (only listed once—typo in file tree).
• Support artifacts:
• images/ → sample outputs (e.g., animated ASCII globe preview).
• LICENSE, .gitignore, README.md.
• Runtime data directories (implied by README):
• textures/ → stores earth.txt, earth_night.txt.
• downloads/ → holds raw map images if running generate_texture.py.
README for additional insights
• Describes features (day/night textures, tilt, speed, scale).
• Walks through the three-stage pipeline: obtain/download textures, generate ASCII textures, render frames, generate GIF.
• Shows all CLI flags for tuning output.
Main components
a. User Interface (CLI)
• Input: user supplies flags (--scale, --speed, etc.)
• Entry points: generate_texture.py, render.py, frames_to_gif.py
b. Texture Generator Module
• Data In: raw satellite images (JPEG) from NASA or user-provided.
• Processor: generate_texture.py (image-to-ASCII converter).
• Data Out: ASCII texture files (textures/earth.txt, earth_night.txt).
c. Render Engine Module
• Data In: ASCII textures
• Processor: render.py
– Real-time console output
– Optional JSON frame dump (earth_frames.json)
• Data Out: JSON file of frames (if save-frames=True)
d. GIF Converter Module
• Data In: JSON frame file
• Processor: frames_to_gif.py (renders each ASCII frame to an image, stitches into GIF)
• Data Out: animated_globe.gif
e. External Services / Resources
• NASA image URLs (for downloads)
• GitHub raw URLs (original Earth textures)
Relationships & interactions
• User invokes one of the scripts via CLI.
• Texture Generator (optional if textures already exist) → writes ASCII textures.
• Render Engine reads ASCII textures → produces console animation and/or JSON frames.
• GIF Converter reads JSON frames → outputs final GIF.
Architectural patterns / design principles
• Pipeline pattern: clear, linear data flow through three stages.
• Separation of concerns: each script handles one discrete stage (modularity).
• Configurability via CLI flags.
• Data-driven: all intermediate artifacts are stored as files (ASCII textures, JSON, GIF).
Technologies / Frameworks
• Python 3.x
• Standard libraries: argparse, JSON, file I/O
• Imaging library (e.g., Pillow) used by generate_texture.py and frames_to_gif.py
• External HTTP client (curl or urllib) to fetch textures/images
Detail
• Default file paths.
• Optional branches (e.g., skip Texture Generator if textures folder exists).