# ethmarks/ascii-globe architecture

> Architecture diagram of the GitHub repository ethmarks/ascii-globe, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ethmarks/ascii-globe
- Repository: https://github.com/ethmarks/ascii-globe

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
graph TD
    User["User / CLI"]:::cli
    GenTexture["Texture Generator\ngenerate_texture.py"]:::module
    Render["Render Engine\nrender.py"]:::module
    GIF["GIF Converter\nframes_to_gif.py"]:::module

    Downloads["downloads/"]:::data
    Textures["textures/"]:::data
    FramesJSON["earth_frames.json"]:::data
    GIFFile["animated_globe.gif"]:::data
    SampleImages["images/"]:::data

    NASA["NASA Image URLs"]:::external
    GitHub["GitHub Raw Textures"]:::external

    User -->|"python generate_texture.py"| GenTexture
    User -->|"python render.py"| Render
    User -->|"python frames_to_gif.py"| GIF

    NASA -->|"JPEG"| GenTexture
    GitHub -->|"JPEG"| GenTexture
    GenTexture -->|"ASCII → .txt"| Textures
    GenTexture -->|"raw → downloads"| Downloads

    Render -->|"reads ASCII"| Textures
    Render -->|"console output"| User
    Render -->|"--save-frames → JSON"| FramesJSON

    GIF -->|"reads JSON"| FramesJSON
    GIF -->|"renders → GIF"| GIFFile

    GIFFile -->|"stored in"| SampleImages
    SampleImages -.->|"view sample"| User

    click GenTexture "https://github.com/ethmarks/ascii-globe/blob/main/generate_texture.py"
    click Render "https://github.com/ethmarks/ascii-globe/blob/main/render.py"
    click GIF "https://github.com/ethmarks/ascii-globe/blob/main/frames_to_gif.py"
    click SampleImages "https://github.com/ethmarks/ascii-globe/tree/main/images/"

    classDef module fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef cli fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
