chafa-rust

Rust bindings for chafa, a terminal graphics library:

With chafa, you can now view very, very reasonable approximations of pictures and animations in the comfort of your favorite terminal emulator. The power of ANSI X3.64 compels you!

Demo

Using the chafa API: examples/demo.rs

use chafa::{Canvas, Config, PixelType, SymbolMap, Symbols};

fn main() {
    // see https://hpjansson.org/chafa/ref/chafa-using.html
 
    const PIX_WIDTH : i32 = 3;
    const PIX_HEIGHT : i32 = 3;
    const N_CHANNELS : i32 = 4;
    let pixels : [u8; (PIX_WIDTH * PIX_HEIGHT * N_CHANNELS) as usize] = [
        0xff, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff,
        0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00, 0xff,
        0xff, 0x00, 0x00, 0xff, 0x00, 0x00, 0x00, 0xff, 0xff, 0x00, 0x00, 0xff
    ];

    let symbol_map = SymbolMap::new();
    symbol_map.add_by_tags(Symbols::ALL);

    let config = Config::new();
    config.set_geometry(23, 12);
    config.set_symbol_map(symbol_map);

    let canvas = Canvas::new(config);

    canvas.draw_all_pixels(PixelType::RGBA8_UNASSOCIATED,
                           &pixels,
                           PIX_WIDTH,
                           PIX_HEIGHT,
                           PIX_WIDTH * N_CHANNELS);

    let output : String = canvas.build_ansi();

    println!("{}", output);
}

Or using a convenience function: examples/image2ansi.rs

use chafa::extra::image2ansi;

fn main() {
    let output = image2ansi("examples/test.png", (33, 16)).unwrap();
    println!("{}", output);
}

Before	After

Installation & Usage

Install chafa with its dependency glib, either from your package manager or from source. Then put this crate in your Rust project.

Typical usage:

[dependencies]
chafa = { git = "https://github.com/wong-justin/chafa-rust.git", tag = "0.4.0", features = ["link-dynamic"] }

1) Give library locations if necessary

By default, pkg-config tries to find chafa and its dependencies. If libraries are not found, you can provide library names and directories with $RUSTFLAGS.

Example: RUSTFLAGS="-L /usr/lib -l chafa -l glib" cargo build

This may be useful when:

• libraries are located at non-standard locations
• libraries are not built with pkg-config metadata
• building in environments with unique linking needs, like when compiling with musl libc
• building on Windows? or environments that do not support pkg-config

2) Choose dynamic or static linking

This crate has two build features: ["link-dynamic"] or ["link-static"]. You must choose one.

Static builds have been trickier in my experience, mainly due to glib compilation errors. I was able to make a statically linked build in an Alpine Dockerfile. Other people have statically linked chafa & glib in other environments -- see vic issue #1 to explore those options.

Extra

You can enable the optional ["image"] feature to access chafa::extra::image2ansi, which might be helpful for casual usage.

Status

This crate does not:

• build chafa or glib from source (yet).
• test builds on Windows or macOS (yet).

If you need those things, I recommend modifying chafa-sys/build.rs or writing your own containerized build script. If you can vendor chafa and glib and build them from source in chafa-sys/build.rs, or if you have changes that make the build work on Windows or macOS, or if you have usability suggestions in general, your contribution would be appreciated.

src/lib.rs currently covers a minimal but usable amount of chafa functions. Parity with chafa's Python bindings is a stretch goal.

Docs

See the chafa C API and the supported subset of functions and structs in src/lib.rs.

Licenses

chafa uses LGPL-3.0-or-later.

glib uses LGPL-2.1-or-later.