Crate cint

cint - color interop

This library provides a lean, minimal, and stable set of types for color interoperation between crates in Rust. Its goal is to serve the same function that mint provides for (linear algebra) math types. It does not actually provide any conversion, math, etc. for these types, but rather serves as a stable interface that multiple libraries can rely on and then convert to their own internal representations to actually use. It is also #![no_std]. bytemuck impls are provided with the bytemuck feature.

How to Use

If you have no idea about color management or encoding principles but you want to use this crate in your own, here’s a very basic rundown.

If you have a color that you loaded from an 8-bit format like a PNG, JPG, etc., or if you have a color that you picked from some sort of online color picker or in Photoshop or Aseprite, then what you have is almost certainly an EncodedSrgb<u8> color. If you have a color that you loaded from a similar format but has floating point values instead of u8 ints, then you almost certainly instead have a EncodedSrgb<f32> color.

If you “linearized” or performed “inverse gamma correction” on such a color, then you instead might have a LinearSrgb<f32>.

If you are more familiar with color encoding, then you’ll find a collection of other color spaces represented, as well as the generic color types (like GenericColor3<ComponentTy>) which can be used if the color space you wish to use is not represented.

All spaces are also collected into the Spaces enum, and you can get the variant represented by any of the concrete color types by taking advantage of the ColorType’s SPACE associated type, i.e. EncodedSrgb::SPACE will give Spaces::EncodedSrgb.

The ColorInterop trait exists to provide a “canonical” transformation to and from cint types. Since it is often possible to convert a color to and from multiple cint types, and because of how the Rust type inference system works, it can often be inconvenient to chain together from or into calls from the From/Into trait. ColorInterop solves this by providing a strongly typed “reference” conversion to/from cint types. This way, you can do things like:

let color_crate1 = color_crate2.into_cint().into();
// or
let color_crate2 = ColorCrate2::from_cint(color_crate1.into());

which would otherwise be quite inconvenient. Provider crates (those that provide their own color types) should implement the relevant From/Into implementations to and from cint types, and also the ColorInterop trait once for each color type. The into_cint and from_cint methods will then be provided automatically.

Colors with alpha channels

cint provides the Alpha<ColorTy> and PremultipliedAlpha<ColorTy> structs, which are generic over the inner ColorTy. To represent an EncodedSrgb<u8> color with a premultiplied alpha component, you’d use PremultipliedAlpha<EncodedSrgb<u8>>. If, on the other hand, you want to represent an Oklab<f32> color with an independent alpha component, you’d use Alpha<Oklab<f32>>

Structs

Aces2065

A color in the ACES 2065-1 color space.

AcesCc

A color in the ACEScc color space.

AcesCct

A color in the ACEScct color space.

AcesCg

A color in the ACEScg color space.

Alpha

A color with an alpha component.

Bt2020

A color in the BT.2020 color space.

Bt2100

A color in the BT.2100 color space.

CieLCh

A color in the CIE L*C*h° color space.

CieLab

A color in the CIE L*a*b* color space.

CieXYZ

A color in the CIE XYZ color space.

DciP3

A color in the DCI-P3 (aka P3 DCI and P3 D60) color space.

DciXYZPrime

A color in the X’Y’Z’ color space, a DCI specification used for digital cinema mastering.

DisplayP3

A color in the Display P3 (aka P3 D65) color space.

EncodedBt2020

A color in the encoded BT.2020 color space.

EncodedBt2100HLG

A color in the encoded BT.2100 color space with HLG (Hybrid Log-Gamma) transfer function.

EncodedBt2100PQ

A color in the encoded BT.2100 color space with PQ (Perceptual Quantizer) transfer function.

EncodedDisplayP3

A color in the Display P3 (aka P3 D65) color space.

EncodedRec709

A color in the encoded Rec.709/BT.709 color space.

EncodedSrgb

A color in the encoded sRGB color space.

GenericColor1

A color in a generic color space that can be represented by 1 component. The user is responsible for ensuring that the correct color space is respected.

GenericColor3

A color in a generic color space that can be represented by 3 components. The user is responsible for ensuring that the correct color space is respected.

Hsl

A color in the HSL color space.

Hsv

A color in the HSV color space.

ICtCpHLG

A color in the ICtCp color space with HLG (Hybrid Log-Gamma) nonlinearity.

ICtCpPQ

A color in the ICtCp color space with PQ (Perceptual Quantizer) nonlinearity.

LinearSrgb

A color in the linear (decoded) sRGB color space.

Luma

A single-channel CIE luma (non-linear transform from luminance).

Luminance

A single-channel CIE luminance.

Oklab

A color in the Oklab color space.

Oklch

A color in the Oklch color space (a transformation from Oklab to LCh° coordinates).

PremultipliedAlpha

A premultiplied color with an alpha component.

Rec709

A color in the Rec.709/BT.709 color space.

YCbCr

A color in the YCbCr color space. See discussion of the difference between YCbCr, YUV, and YPbPr in YCbCr Wikipedia article

YCxCz

A color in the YCxCz (also called YyCxCz) color space, originally defined in “Optimized universal color palette design for error diffusion” by B. W. Kolpatzik and C. A. Bouman. Can be thought of as a “linear CIE Lab”.

YPbPr

A color in the YPbPr color space. See discussion of the difference between YCbCr, YUV, YPbPr, and Y’PbPr in the YCbCr Wikipedia article

YPrimeCbCr

A color in the Y’CbCr color space. See discussion of the difference between YCbCr, Y’CbCr, YUV, YPbPr, and Y’PbPr in the YCbCr Wikipedia article

YPrimePbPr

A color in the Y’PbPr color space. See discussion of the difference between YCbCr, YUV, YPbPr, and Y’PbPr in the YCbCr Wikipedia article

Yuv

A color in the YUV color space. See discussion of the difference between YCbCr, YUV, and YPbPr in YCbCr Wikipedia article

Enums

Spaces

An enum with a variant for each of the color spaces supported by the library. Useful for tracking as metadata in something like an image type, and for runtime-determined color types.

Traits

ColorInterop

A trait that should be implemented by provider crates on their local color types so that you can call color.to_cint() and Color::from_cint(cint_color).

ColorType

A trait used to simpify the interface of the Alpha and PremultipliedAlpha types and allow use with Spaces enum.