24-bit True Colour ↔ 256-colour ANSI terminal palette conversion library

ansi_colours converts between 24-bit sRGB colours and 8-bit colour palette used by ANSI terminals such as xterm or rxvt-unicode in 256-colour mode. The most common use case is when using 24-bit colours in a terminal emulator which only support 8-bit colour palette. It allows true-colours to be approximated by values supported by the terminal.

When mapping true-colour into available 256-colour palette, it tries to balance accuracy and performance. It doesn’t implement the fastest algorithm nor is it the most accurate, instead it uses a formula which should be fast enough and accurate enough for most use-cases.

Usage

The algorithm has C and Rust implementations and can be easily used from C, C++ or Rust. The two implementations are equivalent and are provided for best performance. Since version 1.0.4 the Rust crate has sped up by 25% when doing True Colour → ANSI index conversion and 75% when doing conversion in the other direction.

Rust

Using this package with Cargo projects is as simple as adding a single dependency:

[dependencies]
ansi_colours = "1.2"

and then using one of functions that the library provides:

use ansi_colours::*;

fn main() {
    // Colour at given index:
    println!("{:-3}: {:?}", 50, rgb_from_ansi256(50));

    // Approximate true-colour by colour in the palette:
    let rgb = (100, 200, 150);
    let index = ansi256_from_rgb(rgb);
    println!("{:?} ~ {:-3} {:?}", rgb, index, rgb_from_ansi256(index));
}

To facilitate better interoperability the crate defines rgb (enabled by default), ansi_term, anstyle, and termcolor cargo features which add support for crates with the same name.

C and C++

The easiest way to use this library in C or C++ is to vendor it. Either by copying ansi_colours.h and ansi256.c files to your project or creating a submodule and pointing it at library’s git repository. Then, set up compilation step for the ansi256.c file and add the header file to the include path to have access to the two provided functions:

#include <stdio.h>

#include "ansi_colours.h"

int main() {
    // Colour at given index:
    printf("%-3u #%06x\n",  50, rgb_from_ansi256(50));

    // Approximate true-colour by colour in the palette:
    uint32_t rgb = 0x64C896;
    uint8_t index = ansi256_from_rgb(rgb);
    printf("#%06x ~ %-3u %06x\n", rgb, index, rgb_from_ansi256(index));

    return 0;
}

Unfortunately neither C nor C++ ecosystem has an official centralised package distribution service so there currently is no more convenient solution. For reference, the examples directory includes a simple C program and a simple Makefile that builds it.