chromoxide

Advanced color extraction and generation library

chromoxide is a Rust library for image-driven palette construction in OkLCh:

• extract color support/tone from an image,
• generate constrained color candidates,
• solve multi-slot palette assignments with hard/soft constraints.

What it does

• Builds a ColorSignature from an image (Support + tone preferences).
• Uses SliceSpec ranges (L/C/h) to generate candidate colors.
• Solves multi-slot palette problems (beam search) with constraints like contrast, lightness order, and chroma preferences.
• Supports strict-to-relaxed chroma caps via relaxation (0.0 image-only, 1.0 gamut-assisted).

Library quick start

use chromoxide::{
    ColorSignature, SliceSpec, CandidateGenerator, CandidatePool,
    MinContrast, LightnessOrder, SolverConfig, Constraint, solve,
};

let img = image::open("input.png")?;
let sig = ColorSignature::from_image(&img, None);

let slots = [
    SliceSpec::new().with_l_range(0.05, 0.25).with_c_range(0.0, 0.03).with_achromatic(true),
    SliceSpec::new().with_l_range(0.35, 0.65).with_c_range(0.06, 0.25).with_hue_wedge(0.0, 40.0),
];

let pools: Vec<_> = slots
    .iter()
    .enumerate()
    .map(|(i, s)| CandidatePool::new(i, CandidateGenerator::generate(s, &sig, 32)))
    .collect();

let constraints: Vec<Box<dyn Constraint>> = vec![
    Box::new(MinContrast::new(0, 1, 4.5)),
    Box::new(LightnessOrder::new(0, 1, 0.05)),
];

let order = vec![0, 1];
let config = SolverConfig::new(64);
let solution = solve(&pools, &constraints, &order, &config)?;
println!("slots={}, cost={:.3}", solution.len(), solution.cost);
# Ok::<(), Box<dyn std::error::Error>>(())

Included examples (demos)

• Basic signature extraction:

cargo run --example basic_extraction -- /path/to/image.png

• Sampling from different slice specs:

cargo run --example sampling -- /path/to/image.png 0.5

• ANSI 16-color generation demo:

cargo run --example ansi_scheme -- /path/to/image.png 0.0

• Micro-benchmarks:

cargo run --release --example benchmark

Diagnostics feature

Diagnostics are optional and disabled by default.

cargo run --features diagnostics --example ansi_scheme -- /path/to/image.png 0.0

Notes

• SignatureConfig defaults to sampling all image pixels.
• solve returns Result<Solution, SolveError> with explicit failure reasons.
• SliceSpec includes utility methods like raise_lightness, lower_lightness, raise_chroma, and lower_chroma.