img2pix

Render images as pixel art in the terminal - half-block truecolor by default, optional ASCII gradient, optional palette quantization (PICO-8, GameBoy, DawnBringer-16, CGA, or median-cut from the image), optional Floyd-Steinberg dithering.

Single C11 binary, no runtime dependencies. Decodes PNG, JPEG, BMP, GIF, TGA, PSD, HDR via vendored stb_image.

---

Build

make            # builds ./img2pix
make install    # installs to $(PREFIX)/bin (default /usr/local)
make clean

Requires a C11 compiler (gcc or clang) and make. Nothing else.

Quickstart

./img2pix path/to/image.png                              # half-block truecolor at terminal width
./img2pix --width 80 image.png                           # pin output width
./img2pix --smooth --colors 16 image.jpg                 # posterized pixel-art look
./img2pix --smooth --palette pico8 image.jpg             # 16-color PICO-8 palette
./img2pix --dither --palette gameboy image.jpg           # 4 greens with Floyd-Steinberg
./img2pix --ascii image.png                              # colored ASCII gradient
./img2pix --ascii --mono image.png > art.txt             # plain ASCII to a file
./img2pix --braille image.png                            # Unicode Braille patterns

Flags

Short	Long	Description
-w	--width N	output columns; default = detected terminal width
-c	--colors N	quantize to N colors via median-cut on the image
-p	--palette NAME	use a built-in palette: pico8, gameboy, db16, cga
-S	--saturation F	scale saturation; 1.0 identity, 0 greyscale, try 1.4
-s	--smooth	3×3 median pre-filter (drops noise speckle before quantization)
-d	--dither	Floyd-Steinberg error diffusion (only meaningful when quantizing)
-a	--ascii	ASCII gradient characters instead of Unicode half-blocks
-B	--braille	Unicode Braille patterns instead of half-blocks
-m	--mono	drop ANSI color escapes (implies --ascii if no mode set)
-i	--invert	invert the ASCII ramp / Braille threshold for light terminals
-h	--help	print usage

--palette takes precedence over --colors. --dither applies to whichever palette is in effect.

Gallery

The images below are real img2pix output, baked from the synthetic source on the left. Each grid cell is one half-block; PNGs are upscaled with nearest-neighbor so the pixels stay crisp at any zoom level.

Source (480x300 PNG)

Half-block truecolor

Default	--smooth --colors 16

Retro palettes (with Floyd-Steinberg dithering)

--palette pico8 --dither	--palette gameboy --dither

--palette db16 --dither	--palette cga --dither

Braille patterns

Default (--braille)	Retro dithered (--braille --palette pico8 --dither)

ASCII (--ascii --mono)

_{Plain text, no escapes. Drop into any monospace block.}

********************************************************************************
********************************************************************************
********************************************************************************
********************************************************************************
********************************************************########****************
+++++++++++++++++++++++++++++++++++++++++++++++++++++*############*+++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++*#############+++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++*############*+++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++############++++++++++++++
++++++++++++++++++++++++++++++++++++++++===---===+++++++++**+++++++++++++++++++
============-:...:::--==============-::...............::--=======-----:::::.....
=======-:...................::::................................................
==-:............................................................................
................................................................................

Regenerating the gallery

./docs/gen-demos.sh

Requires magick (ImageMagick) and python3. The script builds a sample source image, runs ./img2pix in each mode, and pipes the ANSI output through docs/render_ansi_to_ppm.py and magick to bake pixel-exact PNGs back out. Drop your own image in as docs/gallery/source.png and re-run.

Architecture

                    +-----------+
                    |  main.c   |   parse opts -> load -> pipeline -> render -> free
                    +-----+-----+
                          |
        +-----------+-----+-----+-------------+
        |           |           |             |
        v           v           v             v
   options.c    image.c    pipeline.c     render.c
   (CLI)       (load/free) (resize +      (halfblock /
                            smooth +       ascii)
                            saturate +
                            quantize)
                                |
                +---------------+----------+
                v                          v
            palette.c                  filter.c
            (median-cut +              (3x3 median,
             named palettes +           saturation)
             FS dither)

Each module_action function returns int (0 / -1) and writes diagnostics to stderr. Only main.c decides exit codes. STB header implementations live in their own translation unit (third_party/stb_impl.c) compiled without warnings; every other TU compiles under -Wshadow -Wstrict-prototypes -Wmissing-prototypes -Wdouble-promotion -Wformat=2 -Wnull-dereference -Wvla warning-free.

Supported input formats

PNG, JPEG, BMP, GIF (first frame), TGA, PSD, HDR, PIC, PPM/PGM. See stb_image header docs for details and per-format caveats. Alpha is composited against black.

License

MIT - see LICENSE. Vendored stb headers retain their original MIT / Public Domain dual license.