hpjansson/chafa
Chafa
Chafa is a terminal graphics library that converts images and animated GIFs into character art for display in terminal emulators. It supports multiple output formats including ANSI escape sequences, Sixel graphics, and Unicode block characters, making it a versatile tool for rendering images directly within the terminal environment.
The library is built as a shared C library with official bindings for Python and JavaScript, allowing developers to integrate terminal image rendering capabilities into applications across different programming environments. Chafa handles the full pipeline from image loading and canvas-based pixel processing through to output generation, with support for animated GIF playback, hardware acceleration detection, and automatic terminal capability detection to select the most compatible rendering mode.
Beyond its core conversion functionality, Chafa provides fine-grained control over rendering quality through dithering adjustment, pixel format selection, and canvas geometry calculation. It also manages terminal integration details such as querying terminal capabilities, handling terminal-specific quirks, and controlling Sixel scrolling behavior, while offering direct cell-level read and write access to rendered canvases for custom manipulation.
Features
- ANSI Image Converters - Converts images and animated GIFs into ANSI, Sixel, or Unicode character art for terminal display.
- Terminal Graphics Library Integration - Converts images and animated GIFs into ANSI, Sixel, and Unicode character art for display in terminal emulators.
- Terminal Image Renderers - Displaying images and animated GIFs as ANSI, Sixel, or Unicode character art directly in terminal emulators.
- Terminal Graphics Converters - Provides a C library API for converting images into terminal character art programmatically.
- Sixel Renderers - Converts images into Sixel graphics for display in terminal emulators.
- Multi-Format Output Renderers - Generates ANSI, Sixel, and Unicode escape sequences from a unified rendering pipeline.
- Image File Loading - Loads one raster frame of image data into memory for processing and display.
- Quality Tuning - Adjusts dithering, color reduction, and other rendering parameters to control the visual fidelity of the generated character art.
- Symbol-to-Pixel Mappings - Maps pixel data to Unicode glyphs and block characters using configurable symbol maps and tags.
- Animated GIF Playback - Decodes and renders animated GIFs frame-by-frame as terminal-compatible character art.
- Canvas Rendering Configurations - Manages geometry, color space, and dithering on a pixel canvas before converting to character art.
- Unicode Art Renderers - Renders a pixel buffer as Unicode block characters and symbols for terminal display.
- Terminal Capability Queries - Query the terminal for its supported features, pixel modes, and canvas modes to determine optimal rendering settings.
- C-Shared Library Bindings - Exposes core rendering logic through a shared C library with Python and JavaScript bindings.
- Terminal Art Converters - Converts images into Unicode character art for display in terminal emulators.
- Terminal Capability Detectors - Detects terminal capabilities to select the most compatible rendering mode and escape sequences.
- Sixel Encoders - Encoding images into the Sixel format for high-color, high-resolution display in supporting terminal emulators.
- Rendering Mode Selectors - Select the most suitable pixel or canvas mode based on the terminal's reported capabilities and quirks.
- Terminal Graphics Protocols - Outputs image data using iTerm2 or Kitty terminal protocols for high-fidelity display.
- Control Sequence Emitters - Construct and send ANSI escape sequences for querying or setting terminal attributes like cell size and text area dimensions.
- Canvas Image Positioning - Defines how images are positioned, aligned, and tucked within a canvas for rendering.
- Canvas Rendering - Sets geometry, color space, and other drawing parameters on a canvas before rendering images.
- Dithering Level Controls - Adjusts the grain size, intensity, and algorithm used for dithering to control how colors are approximated in the output.
- Animation Frame Sequencers - Decodes and plays back multi-frame images as timed character-art sequences in the terminal.
- Image Output Configurations - Sets geometry, color space, and other output parameters before creating a canvas to control rendering.
- Pixel Format Definition - Chooses the byte layout for pixel data used by canvas and symbol-map operations.
- Terminal Canvas Geometry Tools - Calculates optimal character-cell dimensions for an image canvas based on source size, font ratio, and zoom or stretch preferences.
- Unicode Symbol Set Definitions - Filters the set of text symbols used for terminal art by adding or removing symbols matching specified tags.
- Python Bindings - Provides a shared C library and Python bindings for programmatic image-to-terminal-art conversion.
- Python Bindings - Offers Python bindings for converting images into terminal art within Python applications.
- Unicode Block Art Renderers - Renders pixel buffers as Unicode block characters and symbols for terminal display.
- Terminal Utilities - Terminal graphics and image conversion tool.
