img2ascii

A Rust project that converts images to ASCII art in the terminal with optional support for custom dimensions and vibrant 24-bit true color output.

Examples

Example	Original	ASCII Output
Circle
Cat
Mona Lisa
Lain
Lain (Colored)

Installation

Install img2ascii using Cargo (Rust package manager):

cargo install img2ascii-cli

This installs the img2ascii command globally.

Usage

Basic usage

Convert an image to ASCII art in the terminal:

img2ascii image.jpg

Outputs ASCII art with a default width of 80 characters.

Set output width

Control the width (in characters) of the ASCII output:

img2ascii image.jpg --width 60

or shorthand:

img2ascii image.jpg -w 60

Tip: Detail & Width

For more detailed ASCII art output, increase the width! The larger the width value, the more characters are used to represent the image, which preserves more details and produces a more refined result.

• Small width (40-60): Simpler, bolder appearance
• Medium width (80-100): Balanced detail and visibility
• Large width (120+): Maximum detail and fine features

Example:

cargo run -- circle.jpg -w 40    # Simple version
cargo run -- circle.jpg -w 120   # Detailed version

Default (width=80, height auto-calculated with aspect ratio correction):

cargo run -- circle.jpg

Custom width:

cargo run -- circle.jpg --width 100

Custom width and height (no aspect ratio correction applied):

cargo run -- circle.jpg --width 100 --height 50

Short flags:

cargo run -- circle.jpg -w 100 -H 50

Colored ASCII art:

cargo run -- circle.jpg --color

Colored with custom dimensions:

cargo run -- circle.jpg -c -w 120 -H 40

---

## Command-line Flags

| Flag                    | Description                                                                   |
| ----------------------- | ----------------------------------------------------------------------------- |
| `-w, --width <WIDTH>`   | Width of ASCII output in characters _(default: 80)_                           |
| `-H, --height <HEIGHT>` | Height of ASCII output in characters _(optional, overrides auto-calculation)_ |
| `-c, --color`           | Enable colored ASCII art output using ANSI 24-bit true color                  |

---
more img2ascii image.jpg              # → terminal (default)
img2ascii image.jpg -o txt       # → image.txt {no color always}
img2ascii image.jpg -o html      # → image.html
img2ascii image.jpg -o ansi      # → image.ansi
img2ascii image.jpg --output txt

Prerequisites

Install Rust by running:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Verify installation:

rustc --version
cargo --version

Build

cargo build

Run

cargo run -- <image> [OPTIONS]

License

This project is for learning and development purposes.