pixel2ascii
| Crates.io | pixel2ascii |
| lib.rs | pixel2ascii |
| version | 0.1.1 |
| created_at | 2026-01-05 23:06:03.769118+00 |
| updated_at | 2026-01-06 17:40:00.157278+00 |
| description | Convert images into ASCII art with color and grayscale support, including block-based sampling, ANSI color output, and CLI. |
| homepage | https://github.com/SameerVers3/pixel2ascii |
| repository | https://github.com/SameerVers3/pixel2ascii |
| max_upload_size | |
| id | 2024729 |
| size | 49,780 |
Sameer (SameerVers3)
documentation
https://docs.rs/pixel2ascii
README
pixel2ascii
Convert images into ASCII art with optional ANSI truecolor support.
Features
- Image to ASCII conversion - transforms any image into ASCII art
- ANSI truecolor support - colorized output for terminals that support 24-bit color
- Multiple charset presets -
default,dense, and Unicodeblocks - Custom charsets - define your own dark-to-light character gradient
- Aspect ratio correction - accounts for non-square terminal characters
- Luminance inversion - invert for light-on-dark or dark-on-light output
- Flexible output - print to stdout or write to a file
Installation
From source
git clone https://github.com/SameerVers3/pixel2ascii.git
cd pixel2ascii
cargo build --release
The binary will be at target/release/pixel2ascii.
From crates.io (coming soon)
cargo install pixel2ascii
Usage
pixel2ascii <INPUT> [OPTIONS]
Examples
Basic usage (grayscale, 100 characters wide):
pixel2ascii image.png
Colorized output at 120 characters wide:
pixel2ascii image.png --color --width 120
Use block characters for a bolder look:
pixel2ascii image.png --charset-preset blocks
Invert luminance (useful for light terminals):
pixel2ascii image.png --invert
Save output to a file:
pixel2ascii image.png -o output.txt
Custom charset (dark → light):
pixel2ascii image.png --charset "@#%*+=-:. "
CLI Reference
| Flag / Option | Short | Default | Description |
|---|---|---|---|
<INPUT> |
required | Path to input image file | |
--width |
-w |
100 |
Maximum ASCII character width |
--aspect |
0.5 |
Character height/width ratio for aspect correction | |
--no-aspect |
Disable aspect correction (square blocks) | ||
--invert |
Invert luminance mapping | ||
--color |
-c |
Enable ANSI truecolor foreground | |
--bg |
Use background color mode (requires --color) |
||
--no-color |
Force grayscale output (overrides --color) |
||
--charset |
Custom charset ordered dark → light (≥2 chars) | ||
--charset-preset |
default |
Preset: default, dense, or blocks |
|
--output |
-o |
Write output to file instead of stdout | |
--quiet |
Suppress non-error messages | ||
--help |
-h |
Show help | |
--version |
-V |
Show version |
Charset Presets
| Preset | Characters |
|---|---|
default |
@%#*+=-:. |
dense |
@M#W$9876543210?!abc;:+=-,._ |
blocks |
█▓▒░ (Unicode block elements) |
How It Works
- Load image - uses the
imagecrate to decode PNG, JPEG, GIF, BMP, etc. - Compute block size - divides the image into blocks based on target width and aspect ratio.
- Sample blocks - computes average RGB and luminance for each block.
- Match characters - maps luminance to the appropriate character from the charset.
- Render - outputs plain text or ANSI-colored text depending on flags.
Luminance Formula
L = 0.2126 × R + 0.7152 × G + 0.0722 × B
This is the standard Rec. 709 luminance formula.
Project Structure
pixel2ascii/
├── Cargo.toml
├── README.md
└── src/
├── main.rs # CLI entry point
├── lib.rs # Library exports
├── cli.rs # Clap-based argument parsing
├── image.rs # Image loading and block sampling
├── font.rs # Charset bitmap generation (font8x8)
└── ascii.rs # ASCII rendering logic
Dependencies
| Crate | Purpose |
|---|---|
clap |
Command-line argument parsing |
image |
Image decoding (PNG, JPEG, etc.) |
font8x8 |
8×8 bitmap font for charset intensity calculation |
License
MIT © Sameer
Contributing
Contributions are welcome! Please open an issue or submit a pull request.
Made with ❤️ in Rust