Skip to content
regexboiPublic

About

Convert images into Unicode Braille terminal art with ANSI colors

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Dotify logo

Dotify

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.

Features

  • 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, and stretch fitting.

Requirements

  • 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.

Quick Start

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.ans

After installing the package, you can use the console script:

uv pip install .
dotify input.png --cols 80 --rows 40 --output splash.ans

Neon Truecolor Example

For 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.sh

Use --min-saturation 0 when the source has white highlights. White is bright but not saturated, so higher saturation thresholds can filter it out.

Palette Example

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.ans

Aspect Ratio

Braille 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.ans

For 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.

Options

--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.

Development

uv sync
uv run python -m py_compile terminal_art_converter.py
uv run python terminal_art_converter.py --help

Generated art, local images, virtual environments, and build metadata are ignored by git.

About

Convert images into Unicode Braille terminal art with ANSI colors

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages