# hpjansson/chafa

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/hpjansson-chafa).**

4,264 stars · 91 forks · C · lgpl-3.0

## Links

- GitHub: https://github.com/hpjansson/chafa
- Homepage: https://hpjansson.org/chafa/
- awesome-repositories: https://awesome-repositories.com/repository/hpjansson-chafa.md

## Topics

`ansi` `cli` `graphics` `graphics-library` `image-processing` `image-viewer` `images` `iterm2` `kitty` `powershell` `sixel` `terminal` `terminal-based` `terminal-graphics`

## Description

Chafa is a terminal graphics library and a set of tools designed to convert images and animated GIFs into ANSI, Sixel, and Unicode character art. It functions as both a command-line utility and a C library with Python bindings, enabling the rendering of visual imagery directly within terminal emulators.

The project distinguishes itself by supporting multiple output modes, ranging from glyph-based character art to high-resolution graphics via the Sixel protocol. It employs terminal capability detection to select the most compatible rendering mode and escape sequences based on the environment and emulator features.

The library provides comprehensive image processing and canvas management, including color approximation, gradient dithering, and contrast optimization. It manages symbol maps and Unicode glyphs to map pixel data to characters, while also handling terminal control sequences for state management, hyperlink embedding, and multiplexer passthrough.

The core rendering logic is exposed via a shared C library and provides specialized bindings for Python applications.

## Tags

### Data & Databases

- [Pixel-to-Character Mapping](https://awesome-repositories.com/f/data-databases/image-preprocessing-utilities/pixel-normalizers/pixel-analyzers/pixel-to-character-mapping.md) — Transforms raw pixel data into ANSI or Unicode character strings for display within a terminal emulator. ([source](https://hpjansson.org/chafa/ref/chafa-using.html))
- [Character-Based Image Approximation](https://awesome-repositories.com/f/data-databases/image-preprocessing-utilities/pixel-normalizers/pixel-analyzers/pixel-to-character-mapping/character-based-image-approximation.md) — Converts image data into a character-based representation for terminal display using pixel mapping and dithering. ([source](https://hpjansson.org/chafa/ref/new-api-index-1.6.html))
- [Output Dimension Configuration](https://awesome-repositories.com/f/data-databases/image-preprocessing-utilities/pixel-normalizers/pixel-analyzers/pixel-to-character-mapping/output-dimension-configuration.md) — Allows defining the width and height of resulting character art using character cells and pixels. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaCanvasConfig.html))

### Graphics & Multimedia

- [ANSI Image Converters](https://awesome-repositories.com/f/graphics-multimedia/ansi-image-converters.md) — Transforms images and animated GIFs into ANSI and Unicode character art for terminal display.
- [ANSI Sequence Generators](https://awesome-repositories.com/f/graphics-multimedia/ansi-sequence-generators.md) — Produces formatted ANSI strings for cursor movement and text attributes based on terminal characteristics. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaTermInfo.html))
- [Character Symbol Maps](https://awesome-repositories.com/f/graphics-multimedia/character-symbol-maps.md) — Adds, removes, or toggles specific glyphs and character ranges used to represent image data. ([source](https://hpjansson.org/chafa/ref/new-api-index-1.4.html))
- [Dithering Techniques](https://awesome-repositories.com/f/graphics-multimedia/dithering-techniques.md) — Adjusts the mode, intensity, and grain size of dithering to control how colors blend in generated art. ([source](https://hpjansson.org/chafa/ref/new-api-index-1.2.html))
- [Terminal Graphics Rendering](https://awesome-repositories.com/f/graphics-multimedia/graphics-and-media/terminal-graphics-rendering.md) — Implements high-fidelity image rendering in terminals using specialized protocols like Sixel.
- [Cell-Based Grid Renderers](https://awesome-repositories.com/f/graphics-multimedia/graphics-and-media/terminal-graphics-rendering/cell-based-grid-renderers.md) — Implements a grid-based rendering system that maps image pixels to individual terminal character cells.
- [Sixel Renderers](https://awesome-repositories.com/f/graphics-multimedia/graphics-and-media/terminal-graphics-rendering/sixel-renderers.md) — Generates high-resolution terminal graphics using the Sixel protocol for compatible emulator displays.
- [Terminal Pixel Rendering](https://awesome-repositories.com/f/graphics-multimedia/image-graphics-rendering/terminal-pixel-rendering.md) — Draws every pixel of an image onto the canvas using specialized terminal protocols like Sixel to preserve maximum detail. ([source](https://hpjansson.org/chafa/ref/new-api-index-1.2.html))
- [Symbol-to-Pixel Mappings](https://awesome-repositories.com/f/graphics-multimedia/symbol-to-pixel-mappings.md) — Assigns specific symbol maps and transparency thresholds to control which characters represent image data. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaCanvasConfig.html))
- [Unicode Symbol Set Definitions](https://awesome-repositories.com/f/graphics-multimedia/unicode-symbol-set-definitions.md) — Specifies available Unicode characters by filtering symbols through tags, code point ranges, or selector strings. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaSymbolMap.html))
- [Terminal Color Dithering](https://awesome-repositories.com/f/graphics-multimedia/gpu-noise-generators/dithering-patterns/terminal-color-dithering.md) — Uses ordered and diffusion dithering patterns to simulate a wider color gamut on limited terminal palettes.
- [Contrast Enhancements](https://awesome-repositories.com/f/graphics-multimedia/image-editing-processing/image-processing/contrast-enhancements.md) — Boosts saturation and contrast automatically to improve legibility in reduced-color terminal modes. ([source](https://hpjansson.org/chafa/gallery/))
- [Visual Quality Optimizations](https://awesome-repositories.com/f/graphics-multimedia/visual-quality-optimizations.md) — Adjusts contrast, saturation, and dithering to improve legibility and detail through performance tradeoffs. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaCanvasConfig.html))

### Development Tools & Productivity

- [Terminal Graphics](https://awesome-repositories.com/f/development-tools-productivity/terminal-graphics.md) — Provides a comprehensive library and toolset for rendering images and multimedia directly within terminal emulators.
- [Terminal Multiplexer Integrations](https://awesome-repositories.com/f/development-tools-productivity/terminal-shell-cli/terminal-cli-enhancements/shell-terminal-utilities/automation-integration-tools/shell-integration/terminal-multiplexer-integrations.md) — Wraps and escapes control sequences to securely move graphics data through multiplexers like tmux or screen. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaTermInfo.html))
- [Multiplexer Sequence Passthrough](https://awesome-repositories.com/f/development-tools-productivity/terminal-shell-cli/terminal-cli-enhancements/shell-terminal-utilities/automation-integration-tools/shell-integration/terminal-multiplexer-integrations/multiplexer-sequence-passthrough.md) — Combines control sequences from nested environments to maintain compatibility across multiplexers like tmux. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaTermInfo.html))

### Networking & Communication

- [Terminal Capability Queries](https://awesome-repositories.com/f/networking-communication/terminal-capability-queries.md) — Queries terminal emulator features, including cell sizes and pixel modes, to select optimal rendering methods. ([source](https://hpjansson.org/chafa/ref/new-api-index-1.16.html))

### Operating Systems & Systems Programming

- [Shared Library Graphics APIs](https://awesome-repositories.com/f/operating-systems-systems-programming/shared-library-graphics-apis.md) — Exposes core rendering logic via a stable shared C library for integration into other applications. ([source](https://hpjansson.org/chafa/development/))
- [Terminal Environment Detection](https://awesome-repositories.com/f/operating-systems-systems-programming/terminal-command-line-environments/terminal-environment-detection.md) — Analyzes environment variables and fallback sequences to identify supported terminal features and encoding standards. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaTermDb.html))
- [ANSI Escape Sequence Renderers](https://awesome-repositories.com/f/operating-systems-systems-programming/terminal-command-line-environments/terminal-management/output-rendering-engines/ansi-escape-sequence-renderers.md) — Generates raw terminal control codes to manipulate text color and formatting for image display.
- [Terminal Graphics Library Integration](https://awesome-repositories.com/f/operating-systems-systems-programming/c-libraries/terminal-graphics-library-integration.md) — Allows C applications to embed the library for complex terminal display control and image conversion.

### Programming Languages & Runtimes

- [Language Bindings](https://awesome-repositories.com/f/programming-languages-runtimes/language-bindings.md) — Provides specialized Python bindings to generate terminal character art from images. ([source](https://hpjansson.org/chafa/development/))
- [C Shared Libraries](https://awesome-repositories.com/f/programming-languages-runtimes/c-shared-libraries.md) — Provides a stable C shared library allowing the core rendering logic to be integrated into other languages.
- [Parallel Image Conversion](https://awesome-repositories.com/f/programming-languages-runtimes/language-features-paradigms/concurrency-models/concurrency/thread-local-contexts/graphics-context-threading/parallel-image-conversion.md) — Distributes image conversion tasks across multiple CPU cores to improve rendering performance.
- [Terminal Art](https://awesome-repositories.com/f/programming-languages-runtimes/language-interoperability/interoperability/python-bindings/terminal-art.md) — Provides specialized Python bindings for creating character-based visual representations of images.

### System Administration & Monitoring

- [Terminal Capability Detectors](https://awesome-repositories.com/f/system-administration-monitoring/terminal-capability-detectors.md) — Detects supported terminal emulator features and environment variables to select the most compatible rendering mode.

### User Interface & Experience

- [Terminal Image Renderers](https://awesome-repositories.com/f/user-interface-experience/file-previewers/terminal-image-renderers.md) — Transforms image data and animated GIFs into specialized graphics protocols like Sixel for terminal display. ([source](https://hpjansson.org/chafa/ref/ch01.html))
- [Inline Image Renderers](https://awesome-repositories.com/f/user-interface-experience/terminal-user-interfaces/terminal-ui-enhancements/inline-image-renderers.md) — Generates escape sequences to display high-resolution images using specialized protocols like Sixel. ([source](https://hpjansson.org/chafa/ref/new-api-index-1.8.html))
- [Accurate Color Renderers](https://awesome-repositories.com/f/user-interface-experience/ui-architecture/design-utilities/design-systems/color-system-utilities/color-palette-management/terminal-color-palettes/accurate-color-renderers.md) — Determines how colors are approximated and mapped to terminal palettes for foreground and background cells. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaCanvasConfig.html))
- [Color Rendering Adjustments](https://awesome-repositories.com/f/user-interface-experience/color-systems/color-rendering-adjustments.md) — Applies specific color modes and spaces to improve color picking and transparency during rendering. ([source](https://hpjansson.org/chafa/))
- [Command Line Interface Design](https://awesome-repositories.com/f/user-interface-experience/command-line-interface-design.md) — Provides tools for adding visual elements and image-based art to improve the user experience of terminal applications.
- [Terminal Cursor Controllers](https://awesome-repositories.com/f/user-interface-experience/cursor-management/pane-cursor-controllers/terminal-cursor-controllers.md) — Sends escape sequences to manage the cursor, colors, and screen modes for updating the visual state. ([source](https://hpjansson.org/chafa/ref/new-api-index-1.6.html))
- [Terminal Compatibility Layers](https://awesome-repositories.com/f/user-interface-experience/terminal-compatibility-layers.md) — Configures optimization flags and passthrough modes to ensure escape codes are correctly interpreted across environments. ([source](https://hpjansson.org/chafa/ref/chafa-ChafaCanvasConfig.html))

### Scientific & Mathematical Computing

- [Image Conversion Threading](https://awesome-repositories.com/f/scientific-mathematical-computing/high-performance-execution-environments/high-performance-and-parallel-computing/parallel-processing/image-conversion-threading.md) — Controls the number of worker threads used for image conversion to optimize performance based on hardware capacity. ([source](https://hpjansson.org/chafa/ref/chafa-Features.html))

### Part of an Awesome List

- [Terminal Utilities](https://awesome-repositories.com/f/awesome-lists/devtools/terminal-utilities.md) — Terminal graphics and image conversion tool.