culors

A Rust port of culori, the JavaScript color library by Dan Burzo. Covers color spaces, conversion, CSS Color Module 4 parsing and formatting, interpolation, gamut mapping, ΔE, blending, averaging, WCAG contrast, and CSS filters. Output values match culori 4.0.2 within 1e-10 across an exhaustive fixture set.

Used in production by Spectralite, a lighting-control application whose UI relies on culori. The Rust render core needed to produce the same colors as the JS layer, end to end. culors is the result.

Status

As of v1.5 culors tracks culori 4.0.2 at full feature parity, modulo the intentional divergences listed below. The library is in maintenance mode. New features land in culori first; once accepted upstream they are mirrored here. Bug fixes and culori version bumps remain in scope.

Features (v1.6)

Installation

[dependencies]
culors = "1"

With serde support:

[dependencies]
culors = { version = "1", features = ["serde"] }

Quick start

use culors::{blend, format_css, parse, BlendMode, Color};

let red = parse("#ff0000").unwrap();
let blue = parse("rgb(0 0 255 / 0.5)").unwrap();
let mixed = blend(&[red, blue], BlendMode::Multiply);
let css = format_css(&mixed);
assert!(css.starts_with("color(srgb"));

Convert in three flavors, each with different precision and ergonomic trade-offs:

use culors::convert::convert_culori;
use culors::{convert, Color};
use culors::spaces::{Lab, Oklch, Rgb};

let red = Rgb { r: 1.0, g: 0.0, b: 0.0, alpha: None };

// 1. Direct `From`. Typed, zero overhead, bit-for-bit culori parity on
//    pairs where the impl exists. Best when both spaces are known at
//    compile time.
let lab_direct: Lab = Lab::from(red);

// 2. Generic `convert<A, B>`. Typed, simple semantics, always routes
//    through XYZ D65. ~1e-14 drift versus culori on pairs where culori
//    takes a shorter path; back-compatible with v1.0 and v1.1 callers.
let lab_via_hub: Lab = convert(red);

// 3. `Color::convert_to` (dynamic) and `convert_culori<A, B>` (typed
//    wrapper). Both match culori's `converter(mode)` dispatch exactly.
//    Per-pair routing closes the 1e-14 gap.
let lab_culori: Lab = convert_culori(red);
let lab_dyn = Color::Rgb(red).convert_to("lab").unwrap();

// Cylindrical: oklch with hue fixup for grayscale.
let oklch: Oklch = Oklch::from(red);
assert!(!oklch.l.is_nan());

Color::convert_to returns None when the target string is not a known mode; otherwise it produces the same routing culori would. Use it for CSS tooling, design-tool UIs, and any caller that carries the target space as a &str. Use convert_culori<A, B> when the source and target types are known at compile time but you still want culori's per-pair routing.

Interpolate between two colors in Oklab and sample at t = 0.5:

use culors::{interpolate, parse};

let a = parse("oklch(70% 0.15 30deg)").unwrap();
let b = parse("oklch(70% 0.15 200deg)").unwrap();
let ramp = interpolate(&[a, b], "oklab");
let mid = ramp(0.5);
let _ = mid;

Comparison to culori

Every public function in culori 4.0.2 has a culors equivalent, with the exceptions listed under "Intentional divergences" below. The mapping is direct enough that culori code translates almost mechanically: culori.parse(s) becomes culors::parse(s), culori.convert(c, mode) becomes either the generic convert::<_, T>() or a direct T::from(c), and the curried difference, interpolate, and blend factories return Rust closures with the same shape.

Intentional divergences from culori

• No runtime plugin registry. culori exposes useMode, getMode, useParser, and removeParser so JS callers can inject custom color spaces at runtime. culors is statically typed; new spaces are added at compile time. This is a language-design difference, not a missing feature.
• Sub-parsers and sub-serializers are private. culori re-exports parseHex, parseRgb, parseLab, …, serializeHex, serializeRgb, etc. for monkey-patching the parse and format chain. culors keeps these as pub(crate); the canonical entry points are parse() and the format_* family. Behavior is fully equivalent.
• colorsNamed is internal. culori exposes the named-color map as a public dictionary. The culors equivalent is a pub(crate) lookup table behind parse(name).
• NaN channels render as none. culori emits "NaN" for NaN channels in color() formatting; culors emits "none" (CSS Color Module 4 spec-compliant). Cosmetic, applies only to artificially constructed inputs since culori's own pipeline never produces NaN.
• Three culors-only color spaces. Hsluv, Hpluv, and Prismatic are not in culori 4.0.2. Hsluv and Hpluv track the official hsluv-javascript reference; Prismatic follows Hauke 2009.
• Three culors-only ΔE variants. difference_ok, difference_jz, and difference_euclidean_xyz are not exposed as named symbols by culori 4.0.2 (their math is reachable through differenceEuclidean(mode, weights) instead).
• Maintenance mode. As of v1.4, culors tracks culori 4.0.2 with the parity guarantees above. New features land in culori first; once accepted upstream they are mirrored here. Bug fixes and culori version bumps remain in scope.

Documentation

API reference on docs.rs. Release history is in CHANGELOG.md.

Contributing

Bug reports, fixture additions, and color-space implementations are welcome. The fixture generators under fixtures-gen/ consume culori 4.0.2 directly, so any drift between Rust and JavaScript output surfaces immediately when you regenerate. Run npm run gen-fixtures && npm run gen-parse-fixtures && npm run gen-format-fixtures before opening a PR; CI fails if regeneration produces a diff.

License

MIT.