Summary

This project introduces a novel machine learning approach to ASCII art generation, replacing traditional lookup tables with gradient descent optimization. It targets engineers and power users seeking higher-fidelity, adaptable text-based image representations. The core benefit lies in treating character selection as a differentiable problem, enabling global optimization for superior visual reconstruction.

How It Works

The system optimizes character placement by minimizing the difference between a rendered ASCII output and a target image using gradient descent (AdamW). Character selection is made differentiable via a temperature-scaled softmax, allowing gradients to adjust character weights. This differentiable rendering pipeline, combined with techniques like warping and psychovisual tuning (diversity/multiscale loss), enables adaptive, high-quality results that surpass static lookup methods.

Quick Start & Requirements

Installation involves pip install -r requirements.txt, requiring PyTorch and Pillow. Specific fonts must be placed in a fonts/ directory (e.g., bitArray-A2.ttf for printers, gg mono.ttf for Discord). Basic usage is python train.py test.png, defaulting to an "Epson" receipt printer preset. GPU acceleration is supported via CUDA or Apple Silicon (MPS). Setup is estimated at 3-5 minutes per 10,000 iterations on M1 Max hardware, with ~500MB GPU memory usage. A live demo is accessible via telnet/nc/ssh to bad.apple.zellic.io.

Highlighted Details

• Gradient Descent Optimization: Directly optimizes character placement for superior image reconstruction.
• Psychovisual Tuning: Features diversity loss (varied characters) and multiscale loss (dithering) for artistic control.
• Warping: Learns affine transformations to align input with character grids, improving edge clarity.
• Dynamic Contrast & RGB Mapping: Enables learnable contrast curves and MLP-based color-to-grayscale mapping for enhanced detail.
• CP437 Support: Full compatibility with IBM PC Code Page 437 for extended printer graphics.

Maintenance & Community

The project is sponsored by Zellic, which also actively recruits engineers. No specific community channels (Discord/Slack) or public roadmaps are detailed in the README.

Licensing & Compatibility

Licensed under AGPL. Incorporation into commercial products or SaaS offerings requires explicit negotiation with the licensor for a commercial license.

Limitations & Caveats

The project acknowledges its approach is "overkill" for standard ASCII art, implying a potential performance trade-off for enhanced quality. The AGPL license presents a significant adoption barrier for many commercial use cases without a separate licensing agreement.