# vietnh1009/ascii-generator architecture

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

- Interactive diagram: https://gitdiagram.com/vietnh1009/ascii-generator
- Repository: https://github.com/vietnh1009/ascii-generator

## Overview

##### Project Type and Purpose
- This is an open-source, command-line Python tool for generating ASCII art from images and videos.

##### File-Structure Analysis
- Top-level scripts:
- img2txt.py – converts images to text.
- img2img.py / img2img_color.py – converts images to image-based ASCII art.
- video2video.py / video2video_color.py – converts videos to video-based ASCII art.
- Core modules:
- alphabets.py – defines character sets per language.
- utils.py – contains shared image/video I/O, resizing, mapping intensity to characters, rendering logic.
- Supporting directories:
- fonts/ – TrueType or TTC font files used when rendering ASCII onto images.
- data/ – sample input media.
- demo/ – pre-generated outputs.
- Config and meta: LICENSE, README.md.

##### Key Insights from README
- Illustrates supported modes (simple vs. complex character sets), background options (black vs. white), output types (txt, png/jpg, avi/mp4).
- Lists dependencies (cv2, PIL, numpy).

a. Main Components
1. CLI Entry Points (scripts)
2. Core Processing Library (utils.py, alphabets.py)
3. Media I/O Layer
– OpenCV (cv2) for frame extraction and video writing
– PIL/Pillow for image loading, drawing text
4. ASCII Renderer
– Intensity-to‐character mapping
– Font loader (fonts/)
– Text file writer (for img2txt)
– Image canvas drawer (for img2img)
– Video assembler (for video2video)
5. File System
– Input media (data/)
– Output media (demo/ or user-specified)
b. Relationships & Data Flow
- Core Library calls Media I/O Layer to read frames/images
- Data flows into ASCII Renderer, producing intermediate ASCII representations
- Renderer outputs to file system via text writers or PIL/OpenCV output functions
- alphabets.py is imported by Renderer to select character sets
c. Architectural Patterns & Principles
- Layered architecture: separation of CLI, processing logic, and I/O
- Single Responsibility: each script calls a single workflow (image-to-text, image-to-image, or video-to-video)
- Pluggability: alphabets.py can be extended to add new language sets, and fonts/ directory can be extended for custom typefaces
d. Technologies & Frameworks
- Python 3.6+
- OpenCV (cv2) for video frames and writing video outputs
- Pillow (PIL) for image loading and drawing text on images
- NumPy for pixel array manipulation

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Entry Points"
        direction TB
        IMG2TXT["img2txt.py"]:::cli
        IMG2IMG["img2img.py"]:::cli
        IMG2IMG_COLOR["img2img_color.py"]:::cli
        VID2VID["video2video.py"]:::cli
        VID2VID_COLOR["video2video_color.py"]:::cli
    end

    subgraph "Core Processing Library"
        direction TB
        UTILS["utils.py"]:::core
        ALPHABETS["alphabets.py"]:::core
    end

    subgraph "Media I/O Layer"
        direction TB
        OPENCV["OpenCV (cv2)"]:::io
        PIL["Pillow (PIL)"]:::io
        NUMPY["NumPy"]:::io
    end

    subgraph "ASCII Renderer"
        direction TB
        INTENSITY["Intensity-to-Character Mapping"]:::core
        FONT_LOADER["Font Loader"]:::core
        TEXT_WRITER["Text File Writer"]:::core
        IMG_DRAWER["Image Canvas Drawer"]:::core
        VID_ASSEMBLER["Video Assembler"]:::core
    end

    subgraph "File System"
        direction TB
        DATA["data/"]:::fs
        FONTS["fonts/"]:::fs
        DEMO["demo/"]:::fs
    end

    subgraph "Config & Metadata"
        direction TB
        LICENSE["LICENSE"]:::fs
        README["README.md"]:::fs
    end

    IMG2TXT -->|"uses"| UTILS
    IMG2IMG -->|"uses"| UTILS
    IMG2IMG_COLOR -->|"uses"| UTILS
    VID2VID -->|"uses"| UTILS
    VID2VID_COLOR -->|"uses"| UTILS

    UTILS -->|"reads frames/images"| OPENCV
    UTILS -->|"loads images"| PIL
    UTILS -->|"manipulates arrays"| NUMPY

    DATA -->|"input media"| OPENCV

    OPENCV -->|"frame array"| INTENSITY
    PIL -->|"pixel data"| INTENSITY
    NUMPY -->|"pixel array"| INTENSITY

    ALPHABETS -->|"provides charset"| INTENSITY

    INTENSITY -->|"char map"| TEXT_WRITER
    INTENSITY -->|"char map"| IMG_DRAWER
    INTENSITY -->|"char map"| VID_ASSEMBLER

    FONTS -.->|"font files"| FONT_LOADER
    FONT_LOADER -->|"loads fonts"| IMG_DRAWER

    TEXT_WRITER -->|"writes .txt"| DEMO
    IMG_DRAWER -->|"writes .png/.jpg"| DEMO
    VID_ASSEMBLER -->|"writes .avi/.mp4"| DEMO

    click IMG2TXT "https://github.com/vietnh1009/ascii-generator/blob/master/img2txt.py"
    click IMG2IMG "https://github.com/vietnh1009/ascii-generator/blob/master/img2img.py"
    click IMG2IMG_COLOR "https://github.com/vietnh1009/ascii-generator/blob/master/img2img_color.py"
    click VID2VID "https://github.com/vietnh1009/ascii-generator/blob/master/video2video.py"
    click VID2VID_COLOR "https://github.com/vietnh1009/ascii-generator/blob/master/video2video_color.py"
    click UTILS "https://github.com/vietnh1009/ascii-generator/blob/master/utils.py"
    click ALPHABETS "https://github.com/vietnh1009/ascii-generator/blob/master/alphabets.py"
    click DATA "https://github.com/vietnh1009/ascii-generator/tree/master/data/"
    click FONTS "https://github.com/vietnh1009/ascii-generator/tree/master/fonts/"
    click DEMO "https://github.com/vietnh1009/ascii-generator/tree/master/demo/"
    click LICENSE "https://github.com/vietnh1009/ascii-generator/tree/master/LICENSE"
    click README "https://github.com/vietnh1009/ascii-generator/blob/master/README.md"

    classDef cli fill:#ffe066,stroke:#333,stroke-width:1px
    classDef core fill:#74c0fc,stroke:#333,stroke-width:1px
    classDef io fill:#69db7c,stroke:#333,stroke-width:1px
    classDef fs fill:#ced4da,stroke:#333,stroke-width:1px
```
