ASCII Encoder 🎨⌨️🤖

Prerequisites

🐍 This project needs Python installed on your system.

Installation

1. Clone the repository:

   git clone https://github.com/vngnc3/ascii-encoder
   cd ascii-encoder

2. Install the required dependencies: Make sure you are in the project directory and run:

   pip install -r requirements.txt

Usage

Basic Usage

Run the code, add images into input folder, then run it again.

python main.py

Performance Testing

Test the multithreading capabilities and compare performance:

python test_multithreading.py

Configuration

Render Settings

Edit main.py file and change # Render Settings to your liking. Experiment with the settings for different results. You can even add more ASCII character shading style in the main.py file.

Processing Configuration

• use_multithreading: Set to True for parallel processing (recommended), False for sequential
• max_workers: Number of CPU cores to use (None = use all available cores)
• output_mode: Choose between "text", "image", or "both"

Performance Notes

• Multithreaded processing can provide 4-8x speedup on modern multi-core systems
• Each image is processed in a separate process, utilizing all CPU cores
• Memory usage increases proportionally with the number of workers
• For best performance, ensure you have enough RAM for multiple PIL instances

Features

• 🚀 Multithreaded Processing: Process multiple images simultaneously using all available CPU cores
• Multiple Shading Styles: Choose from various predefined shading styles to customize the look of your ASCII art
• Adjustable Dimensions: Set the number of columns and line height to control the size and aspect ratio of the output
• Inversion and Normalization: Invert colors and normalize pixel values for different artistic effects
• Flexible Output: Generate ASCII text files, images, or both
• Batch Processing: Process entire folders of images automatically
• Performance Monitoring: Built-in timing and progress tracking

Advanced Usage

Custom Worker Count

# Use specific number of workers
batch_convert_images_to_ascii_multithreaded(
    column, shader, lineHeight, invert, normalize, overwrite, 
    max_workers=4
)

Sequential Processing

# Force sequential processing
use_multithreading = False

Single Image Processing

# Process a single image with custom settings
process_single_image('input/my_image.jpg', 
                    num_cols=96, 
                    shader_key='unicode_izzy', 
                    line_height=0.6)

Troubleshooting

• Memory Issues: Reduce max_workers if you encounter memory problems
• Windows Compatibility: The script automatically configures multiprocessing for Windows systems
• Fallback: If multithreading fails, the script automatically falls back to sequential processing

Feature requests, bug reports

Hit me up on Twitter/X: @vngnc