Crate color

Color is a Rust crate which implements color space conversions, targeting at least CSS Color Level 4.

Main types

The crate has two approaches to representing color in the Rust type system: a set of types with static color space as part of the types, and DynamicColor in which the color space is represented at runtime.

The static color types come in three variants: OpaqueColor without an alpha channel, AlphaColor with a separate alpha channel, and PremulColor with premultiplied alpha. The last type is particularly useful for making interpolation and compositing more efficient. These have a marker type parameter, indicating which ColorSpace they are in. Conversion to another color space uses the convert method on each of these types. The static types are open-ended, as it’s possible to implement this trait for new color spaces.

Scope and goals

Color in its entirety is an extremely deep and complex topic. It is completely impractical for a single crate to meet all color needs. The goal of this one is to strike a balance, providing color capabilities while also keeping things simple and efficient.

The main purpose of this crate is to provide a good set of types for representing colors, along with conversions between them and basic manipulations, especially interpolation. A major inspiration is the CSS Color Level 4 draft spec; we implement most of the operations and strive for correctness.

A primary use case is rendering, including color conversions and methods for preparing gradients. The crate should also be suitable for document authoring and editing, as it contains methods for parsing and serializing colors with CSS Color 4 compatible syntax.

Simplifications include:

• Always using f32 to represent component values.
• Only handling 3-component color spaces (plus optional alpha).
• Choosing a fixed, curated set of color spaces for dynamic color types.
• Choosing linear sRGB as the central color space.
• Keeping white point implicit in the general conversion operations.

A number of other tasks are out of scope for this crate:

• Print color spaces (CMYK).
• Spectral colors.
• Color spaces with more than 3 components generally.
• ICC color profiles.
• ACES color transforms.
• Appearance models and other color science not needed for rendering.
• Quantizing and packing to lower bit depths.

The Rgba8 and PremulRgba8 types are a partial exception to this last item, as those representation are ubiquitous and requires special logic for serializing to maximize compatibility.

Some of these capabilities may be added as other crates within the color repository, and we will also facilitate interoperability with other color crates in the Rust ecosystem as needed.

Features

• std (enabled by default): Get floating point functions from the standard library (likely using your target’s libc).
• libm: Use floating point implementations from libm.
• bytemuck: Implement traits from bytemuck on AlphaColor, ColorSpaceTag, HueDirection, OpaqueColor, PremulColor, PremulRgba8, and Rgba8.
• serde: Implement serde::Deserialize and serde::Serialize on AlphaColor, DynamicColor, OpaqueColor, PremulColor, PremulRgba8, and Rgba8.

At least one of std and libm is required; std overrides libm.

Modules

cache_key

Hashing and other caching utilities for Color types.

palette

Palettes with predefined colors.

Structs

A98Rgb

🌌 The Adobe RGB (1998) color space.

Aces2065_1

🌌 The ACES2065-1 color space.

AcesCg

🌌 The ACEScg color space.

AlphaColor

A color with an alpha channel.

Chromaticity

CIE xy chromaticity, specifying a color in the XYZ color space, but not its luminosity.

DisplayP3

🌌 The Display P3 color space, often used for wide-gamut displays.

DynamicColor

A color with a color space tag decided at runtime.

Flags

Flags indicating DynamicColor state.

GradientIter

The iterator for gradient approximation.

Hsl

🌌 The HSL color space

Hwb

🌌 The HWB color space

Interpolator

An intermediate struct used for interpolating between colors.

Lab

🌌 The CIELAB color space

Lch

🌌 The cylindrical version of the Lab color space.

LinearSrgb

🌌 The linear-light RGB color space with sRGB primaries.

Missing

Missing color components, extracted from Flags.

Oklab

🌌 The Oklab color space, intended to be a perceptually uniform color space.

Oklch

🌌 The cylindrical version of the Oklab color space.

OpaqueColor

An opaque color.

PremulColor

A color with premultiplied alpha.

PremulRgba8

A packed representation of pre-multiplied sRGB colors.

ProphotoRgb

🌌 The ProPhoto RGB color space.

Rec2020

🌌 The Rec. 2020 color space.

Rgba8

A packed representation of sRGB colors.

Srgb

🌌 The standard RGB color space.

XyzD50

🌌 The CIE XYZ color space with a 2° observer and a reference white of D50.

XyzD65

🌌 The CIE XYZ color space with a 2° observer and a reference white of D65.

Enums

ColorSpaceLayout

The layout of a color space, particularly the hue component.

ColorSpaceTag

The color space tag for dynamic colors.

HueDirection

The hue direction for interpolation.

ParseError

Error type for parse errors.

Traits

ColorSpace

The main trait for color spaces.

Functions

gradient

Generate a piecewise linear approximation to a gradient ramp.

parse_color

Parse a color string in CSS syntax into a color.

parse_color_prefix

Parse a color string prefix in CSS syntax into a color.