How vietnh1009/ascii-generator works
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