Image to ASCII Converter

Convert static images and live webcam video into ASCII text directly in your terminal.

---

Features

Image to ASCII is a lightweight Python tool that transforms pictures and live video into text characters. It runs directly inside your command line interface.

• Static Image Conversion: Converts JPG, PNG, and other common formats into detailed ASCII representations.

• Real-Time Webcam Mode: Streams your webcam directly into the terminal with fast frame rendering using OpenCV.

• Aspect Ratio Correction: Applies a 0.55 vertical compensation factor so terminal character height does not distort the image.

• Standard Luminance Mapping: Calculates brightness with the ITU-R BT.601 formula for accurate tone values.

• Multiple Character Sets: Supports Unicode Braille blocks, standard ASCII ramps, and a 70-level dense character map.

• Automatic File Export: Saves converted images to timestamped text files inside the output/ folder.

• Adaptive Contrast: Uses CLAHE (Contrast Limited Adaptive Histogram Equalization) during webcam streaming to handle poor lighting.

---

Installation

Prerequisites

• Python 3.10 or higher
• A terminal with UTF-8 encoding and ANSI escape code support (Windows Terminal, PowerShell 7+, VS Code Terminal, or any modern Linux/macOS shell)
• A working webcam (optional, required only for --webcam mode)

---

Setup Steps

1. Clone the repository:

   git clone <REPOSITORY_URL>
   cd ImageToAscii

2. Create and activate a virtual environment:

   On Windows:

   python -m venv venv
   .\venv\Scripts\activate

   On Linux or macOS:

   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

   If you prefer manual installation:

   pip install pillow opencv-python numpy

---

Usage

Basic Workflow

1. Navigate to the ascii_image folder:

   cd ascii_image

2. Run the script with an image path or the webcam flag:

   • For an image:

     python main.py ../images/pikachu.jpg

   • For live webcam feed:

     python main.py --webcam

3. View the rendered text output in your terminal window.

4. Check the output/ directory for the saved text file (when processing static images).

---

Command Reference

Command	Description
python main.py <path_to_image>	Converts a single image to ASCII and saves the text output
python main.py --webcam	Starts a live webcam ASCII stream in your terminal
python main.py -h	Displays the help message and argument descriptions

Press Ctrl + C at any time to exit webcam mode.

---

Tips for Best Results

• Contrast: Images with strong separation between subject and background produce the clearest output.
• Terminal Size: Expand your terminal window or decrease your terminal font size (Ctrl + -) to display higher resolutions.
• Font Choice: Use a true monospace font such as JetBrains Mono, Fira Code, or Consolas.
• Lighting: For webcam mode, ensure your face or subject has steady frontal light.

---

Character Sets

The project includes multiple character ramps to match different visual styles.

Set Name	Characters	Best Used For
Unicode Braille (Default in constants.py)	⣿⣷⣶⣦⣤⣄⣀⠈	High-density block art and dark backgrounds
Classic ASCII (Alternative in constants.py)	@%#*+=-:.	Standard terminal rendering with vintage look
Dense 70-Level (Used in webcam.py)	.'",:;Il!i><~+_-?][}{1)(|/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$`	Maximum tonal detail during live video capture

To switch character ramps for static images, open ascii_image/constants.py and modify CHAR_RAMP:

# Classic ASCII:
CHAR_RAMP = "@%#*+=-:. "

# Unicode Braille:
CHAR_RAMP = "⣿⣷⣶⣦⣤⣄⣀⠈ "

---

How It Works

[ Input Image ]
       │
       ▼
[ Resize & Aspect Correction ] (Width = 200, Height = H * Ratio * 0.55)
       │
       ▼
[ Luminance Calculation ] (Y = 0.299*R + 0.587*G + 0.114*B)
       │
       ▼
[ Character Ramp Mapping ] (Index = Brightness * (Ramp_Length - 1) / 255)
       │
       ├──► [ Terminal Display ]
       └──► [ Save to output/result-<timestamp>.txt ]

1. Aspect Ratio Adjustment: Terminal characters are taller than they are wide (roughly a 2:1 ratio). Multiplying target height by 0.55 maintains the original image proportions.
2. Luminance Extraction: Every RGB pixel converts to brightness through standard ITU-R BT.601 weights: 0.299 * R + 0.587 * G + 0.114 * B.
3. Quantization: Brightness values (0 to 255) map directly to indices in the character string.
4. ANSI Terminal Redraw: In webcam mode, the app uses ANSI cursor control (\033[H) to rewrite lines without clearing the screen, preventing flicker.

---

Known Limitations

• Fixed Static Width: Static image processing currently targets a default width of 200 columns. On smaller terminal windows, lines will wrap and distort the image.
• Single Webcam Index: Webcam mode defaults to camera index 0. Systems with multiple cameras must update the index in webcam.py.
• Monospace Font Dependency: Proportional fonts will misalign rows. Terminal must use monospace characters.
• Color Output: Current pipeline outputs monochrome text only.

---

Project Structure

ImageToAscii/
│
├── ascii_image/                      # Core application source
│   ├── output/                       # Generated ASCII text files
│   ├── ascii_converter.py            # Brightness to character ramp mapping
│   ├── constants.py                  # Character ramp definitions
│   ├── image_loader.py               # PIL Image file loader
│   ├── image_processor.py            # Pixel parsing and luminance calculation
│   ├── main.py                       # CLI entry point and argument parser
│   ├── webcam.py                     # Real-time OpenCV capture and ANSI renderer
│   └── writer.py                     # Output file writer
│
├── images/                           # Sample test images
│   ├── chard.jpg
│   ├── ok.jpg
│   ├── pikachu.jpg
│   └── squidward.jpg
│
├── requirements.txt                  # Python dependencies
├── README.md                         # Project documentation
└── sample.md                         # Reference documentation

---

Troubleshooting

Issue	Cause	Solution
ModuleNotFoundError: No module named 'PIL'	Pillow package is not installed	Run pip install pillow in your virtual environment.
Error: Could not open webcam.	Camera is busy or index 0 is not found	Close other apps using the camera, or change cv2.VideoCapture(0) to 1 in webcam.py.
ASCII art appears stretched vertically	Terminal font dimensions differ from 0.55 ratio	Adjust aspect_ratio_correction in main.py (e.g. try 0.50 or 0.60).
Rows wrap and look broken	Terminal window is narrower than 200 columns	Maximize the terminal, zoom out (Ctrl + -), or lower target_width in main.py.
Characters display as boxes or question marks	Font does not support Unicode Braille characters	Switch to classic ASCII in constants.py or install a font with Unicode support.
Webcam output flickers heavily on Windows	Virtual terminal processing is not enabled	Run inside Windows Terminal or VS Code integrated terminal.

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-ramp)
3. Commit your changes (git commit -m 'Add new character ramp')
4. Push to the branch (git push origin feature/new-ramp)
5. Open a Pull Request

---

License & Attribution

Distributed under the MIT License. See LICENSE for details.

Dependencies:

• Pillow (PIL Fork): Image processing
• OpenCV: Computer vision and webcam capture
• NumPy: Vectorized numeric operations

---

References

• Pillow Documentation
• OpenCV Python Tutorials
• ITU-R BT.601 Standard
• ANSI Escape Codes Guide

---

Team & Acknowledgments

• Development: Python CLI, image processing, and terminal webcam streaming
• Testing: Monospace layout, aspect ratio calibration, and multi-format testing

---

© 2026 Image to ASCII. All Rights Reserved.