artty is a command-line tool and Python library that converts images to Unicode braille ASCII art with 24-bit ANSI color support. It preserves image contrast and sharpness while producing detailed, scanable output that works in any modern terminal on macOS, Linux, or Windows.
Whether you're building a terminal-based dashboard, creating visual presentations, or just having fun with ASCII art, artty gives you professional results with minimal configuration.
Bring some art to your TTY with arTTY.
| Feature | Description |
|---|---|
| ⚡ Unicode Braille Output | Uses braille characters (U+2800–U+28FF) for efficient 2×4 pixel cell representation |
| 🎨 24-bit ANSI Color | Embedded color codes sample only from lit pixels, preventing dark edge contamination |
| 🖥️ Cross-Platform | Works on macOS, Linux, and Windows with VT support |
| 📐 Preserves Contrast | Advanced threshold and sharpness controls maintain image definition |
| ⚙️ Fully Configurable | Adjustable width, threshold, contrast, sharpness, and padding |
| 🔧 Python API | Import image_to_braille directly in your own code |
Prerequisites: Python 3.10+
# Using uv (recommended)
uv pip install artty
# or using pip
pip install arttygit clone https://github.com/divisionseven/artty.git
cd artty
# Using uv (recommended)
uv sync
uv run artty --version
# Or using pip
pip install -e .artty --version
# Output: artty, version <version># Convert an image to braille ASCII art with default settings (default 100-character width)
artty input.png# Convert an image to braille ASCII art with 80-character width (using defaults for all other settings)
artty input.png -w 80# Convert an image to plain text using default settings (no ANSI color codes embedded)
artty input.png --no-color# Convert with custom width, black background, contrast boost, and save to file with custom name/path
artty photo.jpg -w 120 --bg 0 0 0 --boost 1.4 -o output.txtExpected output: A detailed braille ASCII representation of your image, preview displayed in your terminal and saved to output.txt.
# Show help screen
artty -h
artty --help
Usage: artty [OPTIONS] INPUT
artty — Convert images to detailed braille ASCII art.
A CLI tool that converts images to detailed braille ASCII art with
accurate color embedding or plain text output.
Features:
- Unicode braille characters
- 24-bit ANSI color support
- Cross-platform (macOS, Windows, Linux)
- Configurable output options
Options:
-o, --output TEXT Where to save the .txt file. Accepts a full file path or a directory. If a directory is
given, the filename is derived from the input image name. Defaults to the same directory as
the input image.
--preview / --no-preview Print the result to the terminal after saving (default: on).
--no-save Do not write a .txt file — only print to stdout.
-w, --width INTEGER RANGE Output width in braille characters. Height is auto-calculated. (default: 100) [10<=x<=500]
-t, --threshold INTEGER RANGE Luminance threshold (0-255). Pixels brighter than this become braille dots. Lower = denser,
higher = sparser. (default: 50) [0<=x<=255]
--padding INTEGER Pixels of padding around auto-detected content. (default: 30)
--contrast FLOAT Contrast enhancement factor. 1.0 = unchanged. (default: 1.0)
--sharpness FLOAT Sharpness enhancement factor. 1.0 = unchanged. (default: 1.0)
--color / --no-color Enable/disable 24-bit ANSI color output. (default: on)
--boost FLOAT Color brightness multiplier. 1.0-1.4 typical. (default: 1.2)
--bg R G B Solid ANSI background color as three integers (0-255). [0<=x<=255]
--hide-paths Show only filenames in output (hide full paths).
--version Show the version and exit.
-h, --help Show this message and exit.
Examples:
artty logo.png
artty logo.png -o ~/Desktop/logo.txt -w 120
artty logo.png --no-color --width 80
artty logo.png --bg 0 0 0 --boost 1.4Note
All demo screenshots were captured using the Ghostty Terminal, which supports full TrueColor (24-bit) color output. Other terminal emulators that support TrueColor include iTerm2, Kitty, Alacritty, and WezTerm, and various others. arTTY has currently been tested with both the Ghostty and the Visual Studio Code integrated terminal.
If you use arTTY with another terminal emulator, please open an issue to report its performance.
# Convert a JPEG image to braille art using default settings
# with input/output paths hidden from the output message
artty nasa.jpeg --hide-paths| Input | arTTY Output |
|---|---|
 |
 |
Credit: NASA | Brand logos shown for demonstration purposes only. All trademarks are property of their respective owners.
# Convert a JPEG image to 150-character width braille art
# with input/output paths hidden from the output message
artty JB1.jpeg -w 150 --hide-paths| Input | arTTY Output |
|---|---|
 |
 |
Credit: © Division 7 | All trademarks are property of their respective owners.
# Convert a JPEG image to 175-character width braille art
# with input/output paths hidden from the output message
artty JB3.jpeg -w 175 --hide-paths| Input | arTTY Output |
|---|---|
 |
 |
Credit: © Division 7 | All trademarks are property of their respective owners.
# Convert the arTTY logo to 200-character width ASCII art
# with input/output paths hidden from the output message
artty logo.png -w 200 --hide-paths| Input | arTTY Output |
|---|---|
 |
 |
Credit: artty GitHub
# Convert the VS Code PNG image to braille art
# with input/output paths hidden from the output message
artty vscode.png --hide-paths| Input | arTTY Output |
|---|---|
 |
 |
Credit: Microsoft/VSCode | Brand logos shown for demonstration purposes only. All trademarks are property of their respective owners.
# Convert the Linux logo to braille art
# with input/output paths hidden from the output message
artty linux.png --hide-paths| Input | arTTY Output |
|---|---|
 |
 |
Credit: Linux | Brand logos shown for demonstration purposes only. All trademarks are property of their respective owners.
# Convert GitHub logo to 200-character width plain text (no color)
# with input/output paths hidden from the output message
artty github_full.png -w 200 --no-color --hide-paths| Input | arTTY Plain TXT Output |
|---|---|
 |
 |
Credit: GitHub | Brand logos shown for demonstration purposes only. All trademarks are property of their respective owners.
# Convert pkg-defender logo to 125-character width plain text
# with input/output paths hidden from the output message
artty pkg-defender.png -w 125 --no-color --hide-paths| Input | arTTY Plain TXT Output |
|---|---|
 |
 |
Credit: PKG-Defender GitHub | "Supply-Chain Attack Defense CLI"
# Convert Arch Linux logo to color-embedded output (200-char width)
# with input/output paths hidden from the output message
artty arch.png -w 200 --hide-paths
# Convert Arch Linux logo to plain text output (200-char width)
# with input/output paths hidden from the output message
artty arch.png -w 200 --no-color --hide-paths| Input | arTTY Color-Embedded Output | arTTY Plain TXT Output |
|---|---|---|
 |
 |
 |
Credit: Arch Linux | Brand logos shown for demonstration purposes only. All trademarks are property of their respective owners.
# Convert Apple logo to color-embedded output (80-char width)
# with input/output paths hidden from the output message
artty apple.png -w 80 --hide-paths
# Convert Apple logo to plain text output (80-char width)
# with input/output paths hidden from the output message
artty apple.png -w 80 --no-color --hide-paths| Input | arTTY Color-Embedded Output | arTTY Plain TXT Output |
|---|---|---|
 |
 |
 |
Credit: Apple | Brand logos shown for demonstration purposes only. All trademarks are property of their respective owners.
For detailed technical information, see the Documentation Index, which provides:
- Algorithm — How Unicode Braille rendering works
- CLI & API Reference — Complete command-line options and Python library examples
- Examples — Practical usage examples
| Category | Option | Type | Default | Description |
|---|---|---|---|---|
| Input | input |
path |
(required) | Path to the input image file |
| Image Processing | -w, --width |
int |
100 |
Output width in braille characters (10-500) |
| Image Processing | -t, --threshold |
int |
50 |
Luminance cutoff for braille dots (0-255) |
| Image Processing | --padding |
int |
30 |
Pixels of padding around auto-detected content |
| Image Processing | --contrast |
float |
1.0 |
Contrast enhancement factor. 1.0 = unchanged |
| Image Processing | --sharpness |
float |
1.0 |
Sharpness enhancement factor. 1.0 = unchanged |
| Image Processing | --color / --no-color |
bool |
True |
Enable/disable ANSI color output |
| Image Processing | --boost |
float |
1.2 |
Color brightness multiplier. Typical range: 1.0-1.4 |
| Image Processing | --bg |
tuple |
None |
Background color as three integers (R G B) |
| Output/Terminal | -o, --output |
str |
Input name w/ conversion attributes | Save output to file with custom name/path. Accepts full path or directory. Defaults to same directory as input. |
| Output/Terminal | --preview / --no-preview |
bool |
True |
Show preview in terminal |
| Output/Terminal | --no-save |
flag |
False |
Print to stdout only, don't save to file |
| Output/Terminal | --hide-paths |
flag |
False |
Show only filenames in output (hide full paths) |
| Output/Terminal | --version |
flag |
False |
Show version number and exit |
| Output/Terminal | --help |
flag |
False |
Show help message and exit |
arTTY can be used directly as a Python library for more control over the conversion process. Import the image_to_braille function and pass various parameters to customize the output.
The simplest way to convert an image is to provide just the path. This uses all default settings (100-character width, color enabled, automatic background detection):
from artty import image_to_braille
# Simple conversion with just the image path - uses all defaults
result = image_to_braille(path="logo.png")
print(result)Control the output width to fit your needs. Smaller widths work better for narrow terminals, while larger widths capture more detail:
from artty import image_to_braille
# Convert to narrower 60-character width (good for sidebars or compact displays)
result = image_to_braille(
path="photo.jpg",
width=60, # Output width in braille characters (default is 100)
)
print(result)
# Or use a larger width for more detail (good for wide terminals)
result = image_to_braille(
path="photo.jpg",
width=150, # Capture more image detail with wider output
)
print(result)Here's a demonstration of every available parameter with explanations:
from artty import image_to_braille
# Full example showing all parameters
result = image_to_braille(
path="logo.png", # Path to the input image file (supports PNG, JPEG, etc.)
width=100, # Output width in braille characters (10-500, default: 100)
threshold=50, # Brightness cutoff (0-255, default: 50) - lower = more dots
contrast=1.0, # Contrast multiplier (1.0 = unchanged, >1 = more contrast)
sharpness=1.0, # Sharpness multiplier (1.0 = unchanged, >1 = sharper edges)
crop_padding=30, # Padding pixels around image content before processing
color=True, # Enable 24-bit ANSI color output (True = color, False = plain text)
bg_color=None, # Background color as (R, G, B) tuple, or None for auto-detection
color_boost=1.2, # Color brightness multiplier (default: 1.2)
)
print(result)Disable color output when you need plain text for logging, saving to files, or terminals without color support:
from artty import image_to_braille
# Convert to plain ASCII without ANSI color codes
result = image_to_braille(
path="logo.png",
color=False, # Disable color - output will be plain text with braille characters only
)
print(result)
# Useful for saving to plain text files
with open("output.txt", "w") as f:
f.write(result)Specify a background color when the image has transparency or you want to override the detected background:
from artty import image_to_braille
# Use a black background (good for light images)
result = image_to_braille(
path="logo.png",
bg_color=(0, 0, 0), # RGB tuple for black background
)
print(result)
# Use a white background (good for dark images)
result = image_to_braille(
path="photo.jpg",
bg_color=(255, 255, 255), # RGB tuple for white background
)
print(result)
# Use a custom color (e.g., dark blue for a themed terminal)
result = image_to_braille(
path="logo.png",
bg_color=(10, 20, 40), # RGB tuple for dark blue
)
print(result)Process images from memory without writing to disk - useful for web applications, APIs, or processing uploaded files:
from artty import image_to_braille
from io import BytesIO
# Convert from bytes in memory
image_bytes = b"\x89PNG\r\n\x1a\n..." # Your image bytes here
result = image_to_braille(path=image_bytes)
print(result)
# Or use BytesIO for more control
with open("photo.jpg", "rb") as f:
image_data = f.read()
result = image_to_braille(path=image_data)
print(result)
# For web frameworks (FastAPI, Flask, etc.)
async def process_upload(upload):
# upload.read() returns bytes
result = image_to_braille(path=upload.read())
return result# Using uv (recommended)
uv run pytest
# Or using pip
pytest tests/ -vContributions are welcome! Please review our contributing guidelines before getting started. If you'd like to contribute, please open an issue to discuss your proposed changes or feel free to submit a pull request directly.
Distributed under the MIT License. See LICENSE for more information.
Last updated: 2026-04-18