# True-colour ↔ ANSI terminal palette converter
[](https://crates.io/crates/ansi_colours)
[](https://docs.rs/ansi_colours)
[](https://github.com/mina86/ansi_colours/blob/master/LICENSE)
`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:
```toml
[dependencies]
ansi_colours = "1.2"
```
and then using one of functions that the library provides:
```rust
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 copy the
`ansi_colour.h` and `ansi256.c` files to your project, set up
compilation step for the `ansi256.c` file, add the header file to the
include path and once all that is done use the two provided functions:
```c
#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 a centralised package
distribution service so there currently is no more convenient
solution.