colr

A general purpose, extensible color type unifying storage, channel layouts, and color spaces at the type level.

Color spaces, transfer functions, chromatic adaptation, and channel layouts are encoded in the type system. Mixing an sRGB color with a Display P3 color is a compile error unless you convert explicitly. All colorimetric matrices are derived at compile time. Colors themselves are generic over their storage representation, which itself is generic over its layout.

Usage

use colr::{Color, Srgb, Rgb, Oklab, Oklch, XyzD65};

// Construct an sRGB color. Layout is part of the type.
let srgb: Color<[f32; 3], Srgb<Rgb>> = Color::new_unchecked([0.8, 0.4, 0.2]);

// Convert to Oklab for perceptual work. The path goes through XYZ
// automatically when you chain transforms. All matrices are compile-time.
let lab: Color<[f32; 3], Oklab> = srgb
    .transform::<Color<[f32; 3], XyzD65>>()
    .transform();

// Pull out chroma and hue, reduce chroma, put it back.
let lch: Color<[f32; 3], Oklch> = lab.transform();
let [l, c, h] = lch.inner();
let muted: Color<[f32; 3], Oklch> = Color::new_unchecked([l, c * 0.5, h]);

// Converting from a large space back to sRGB can produce out-of-gamut
// values. try_transform gives you the error and the clamped result.
let result = muted
    .transform::<Color<[f32; 3], Oklab>>()
    .transform::<Color<[f32; 3], XyzD65>>()
    .try_transform::<Color<[f32; 3], Srgb<Rgb>>>();

let final_color = result.unwrap_or_else(|e| e.clamped);

Color spaces

Perceptual spaces

Lab and LCh are parameterized by illuminant: Lab<D65>, Lab<D50>, and so on. Oklab and Oklch have D65 baked into the specification. The aliases LabD65 and LChD65 cover the common case.

RGB spaces

Each alias defaults to RGBA layout. Alternate layouts are selected with the type parameter: Srgb<Rgb>, Srgb<Bgra>, and so on.

XYZ spaces

Conversions between different XYZ illuminants apply Bradford chromatic adaptation, computed at compile time.

Planned spaces

CMYK support is planned. The intent is to support ICC-described CMYK profiles as a runtime context parameter on the transform, consistent with how other context-parameterized transforms work in this library. There is no timeline for this yet.

If a space from an open standard is not listed above, please open an issue.

Transforms

Use transform for conversions that are always in range, and try_transform for conversions into a bounded space where the source may not fit.

try_transform returns Result<Dst, OutOfGamut<Dst>>. The OutOfGamut value always contains the clamped approximation, so a usable result is always present regardless of whether you propagate the error:

# use colr::{Color, Srgb, Rgb, XyzD65};
# let src: Color<[f32; 3], XyzD65> = Color::new_unchecked([2.0, 1.0, 1.0]);
let value = src.try_transform::<Color<[f32; 3], Srgb<Rgb>>>().unwrap_or_else(|e| e.clamped);

Transform context

Most transforms are fully static and require no runtime data. The Ctx parameter on Transform exists for cases where runtime data is needed:

Implement Transform<Src, YourCtx> for custom transforms.

Channel layouts

Layout is a type parameter, not a runtime tag. The compiler distinguishes RGBA from BGRA and will not accept one where the other is expected.

Layout reorders are infallible and compile to a shuffle with no arithmetic:

# use colr::{Color, Srgb, Bgra, Rgba};
# let rgba: Color<[f32; 4], Srgb<Rgba>> = Color::new_unchecked([1.0, 0.0, 0.0, 1.0]);
let bgra: Color<[f32; 4], Srgb<Bgra>> = rgba.transform();

Chromatic adaptation

Four methods are provided. Bradford is used automatically by all built-in conversions and is the correct default for standard RGB work.

Custom adaptation matrices can be computed at compile time with adapt::<A>.

no_std support

no_std support is available with the libm feature. Either std or libm must be enabled; the crate will not compile without at least one.

[dependencies]
colr = { version = "0.1", default-features = false, features = ["libm"] }

To support both std and no_std builds in a library crate:

[features]
default = ["std"]
std     = ["colr/std"]
libm    = ["colr/libm"]

[dependencies]
colr = { version = "0.1", default-features = false }

Optional features

std is the default feature and enables standard library math functions. The remaining features are opt-in.

Adding a custom primary set

Implement Primaries for your type and register it with the provided macros. All matrices are derived at compile time from the chromaticity coordinates and white point you supply.

use colr::primaries::{Primaries, derive_rgb_to_xyz};
use colr::illuminant::{Illuminant, D65};
use colr::math::Mat3;

pub struct CustomPrimaries;

const CUSTOM_TO_XYZ: Mat3 = derive_rgb_to_xyz(
    [0.680, 0.320],  // red
    [0.265, 0.690],  // green
    [0.150, 0.060],  // blue
    D65::WHITE_POINT_XYZ,
);

impl Primaries for CustomPrimaries {
    type Native = D65;
    const R: [f32; 2] = [0.680, 0.320];
    const G: [f32; 2] = [0.265, 0.690];
    const B: [f32; 2] = [0.150, 0.060];
    const TO_XYZ_NATIVE:  Mat3 = CUSTOM_TO_XYZ;
    const FROM_XYZ_NATIVE: Mat3 = Mat3::invert(&CUSTOM_TO_XYZ);
}

Then call impl_native! and any needed impl_adapted! to register the XYZ connection hubs for your target illuminant. See src/primaries.rs for examples.

Design notes

All colorimetric matrices are derived in const fn at compile time, including RGB-to-XYZ, chromatic adaptation, and composed primaries-to-primaries transforms. There is no matrix inversion or multiplication at runtime, in any build profile.

Color<S, Sp> is #[repr(transparent)] over its storage type. The space is carried only as PhantomData. There is no runtime memory overhead from the type-level bookkeeping.

Minimum Supported Rust Version (MSRV)

The minimum supported version of Rust for this crate is 1.85.

Edition 2024 requires Rust 1.85. Inline const {} blocks, used to evaluate transform matrices at compile time in generic contexts, stabilized in Rust 1.82.

Contributing

This crate is early in development. Consider raising an issue if the crate doesn't fit your needs, is missing any obvious functionality, or is unergonomic in any way.

Contributions are welcome for any color space or transfer function defined in an open standard. If a standard space is missing, please open an issue before implementing it so the approach can be agreed on first. Spaces from proprietary or closed formats belong in a separate crate.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual licensed as below, without any additional terms or conditions.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.