Convert images into Unicode Braille terminal art with optional ANSI color.
Dotify is tuned for neon line-art splash screens: it samples an image onto a Braille dot grid, thresholds visible pixels, and emits high-resolution terminal output. It can preserve source colors with truecolor ANSI, snap colors to small palettes, or emit plain Unicode for environments without color support.
- Unicode Braille rendering, where each terminal cell represents a 2x4 dot block.
- ANSI truecolor output for source-like hues.
- Palette output for compact, consistent terminal colors.
- Neon, luminance, and alpha mask modes.
- Output color boosting for brighter terminal art.
- Optional plain-text fallback and executable shell script output.
- Aspect-ratio aware
contain,cover, andstretchfitting.
- Python 3.10+
- A UTF-8 terminal
- A terminal font with Braille glyph support
- 24-bit color support for truecolor output
This project uses uv for Python workflows.
uv run python terminal_art_converter.py input.png \
--cols 80 \
--rows 40 \
--output splash.ans \
--plain splash.txt \
--shell-script splash.sh
cat splash.ansAfter installing the package, you can use the console script:
uv pip install .
dotify input.png --cols 80 --rows 40 --output splash.ansFor neon line art where you want bright colors and white highlights preserved:
uv run python terminal_art_converter.py input.png \
--cols 80 \
--rows 40 \
--fit contain \
--mask-mode neon \
--min-channel 52 \
--min-saturation 0 \
--color-mode truecolor \
--brightness 2.15 \
--saturation 1.45 \
--min-output-channel 170 \
--output splash.ans \
--plain splash.txt \
--shell-script splash.shUse --min-saturation 0 when the source has white highlights. White is bright
but not saturated, so higher saturation thresholds can filter it out.
For compact output snapped to the built-in neon palette:
uv run python terminal_art_converter.py input.png \
--cols 80 \
--rows 40 \
--fit contain \
--mask-mode neon \
--min-channel 52 \
--min-saturation 18 \
--color-mode palette \
--palette neon \
--output splash.ansBraille terminal art uses 2 dot columns by 4 dot rows per character. In a
typical monospace terminal, character cells are roughly twice as tall as they
are wide, so an 80x40 Braille canvas displays approximately square.
For square images, use a columns-to-rows ratio near 2:1:
uv run python terminal_art_converter.py logo.png --cols 80 --rows 40 -o logo.ans
uv run python terminal_art_converter.py logo.png --cols 100 --rows 50 -o logo.ans
uv run python terminal_art_converter.py logo.png --cols 120 --rows 60 -o logo.ansFor a wide image, increase columns or reduce rows. The displayed visual aspect is approximately:
visual_aspect ~= columns / (2 * rows)
The default --fit contain preserves aspect ratio and pads with empty space.
--fit cover preserves aspect ratio but crops edges. --fit stretch fills the
canvas and may distort the image.
--cols, --rows Terminal dimensions.
--fit contain|cover|stretch Resize behavior.
--background COLOR Background as #RRGGBB or r,g,b.
--mask-mode neon Keep bright saturated pixels.
--mask-mode luminance Keep bright pixels regardless of saturation.
--mask-mode alpha Keep non-transparent pixels.
--min-channel N Neon mode brightness threshold.
--min-saturation N Neon mode saturation threshold.
--min-alpha N Minimum alpha for all mask modes.
--luminance-threshold N Luminance mode brightness threshold.
--color-mode palette Snap colors to a small palette.
--color-mode truecolor Use averaged source RGB colors.
--color-mode none Plain Unicode only.
--palette neon Purple/cyan/green/magenta palette.
--palette terminal16 Classic terminal color palette.
--palette mono Single pale color.
--brightness N Multiply output color lightness.
--saturation N Multiply output color saturation.
--min-output-channel N Raise dim output colors to a minimum max channel.
--plain FILE Also write no-ANSI fallback.
--shell-script FILE Also write an executable shell script.
--trim Trim trailing blanks from each row.
uv sync
uv run python -m py_compile terminal_art_converter.py
uv run python terminal_art_converter.py --helpGenerated art, local images, virtual environments, and build metadata are ignored by git.
