palette

Palette implements various color operations (like saturate, desaturate, hue shift, and lightening) as operator traits. This allows you to write generic functions that operate on any color space that supports the specific operation.

Common traits include:

• ShiftHue
• Lighten
• Mix (for interpolation)

Additionally, Palette provides SVG blend and composition functions, such as .over() for alpha blending.

use palette::{Hsl, Hsv, Lighten, Mix, ShiftHue};

fn transform_color<C>(color: C, amount: f32) -> C
where
    C: ShiftHue<Scalar = f32> + Lighten<Scalar = f32> + Mix<Scalar = f32> + Copy,
{
    let new_color = color.shift_hue(170.0).lighten(1.0);

    // Interpolate between the old and new color.
    color.mix(new_color, amount)
}

let new_hsl = transform_color(Hsl::new_srgb(0.00, 0.70, 0.20), 0.8);
let new_hsv = transform_color(Hsv::new_srgb(0.00, 0.82, 0.34), 0.8);

The palette_derive crate provides derive macros for the palette crate. Instead of adding palette_derive as a direct dependency, you should add palette to your Cargo.toml. The macros are re-exported through the main palette crate.

To use them, ensure palette is in your dependencies and use the macros as provided by the palette namespace.

// In your Cargo.toml
[dependencies]
palette = "0.7.7"

// In your code
use palette::SomeDeriveMacro;

#[derive(SomeDeriveMacro)]
struct MyColor;

Built-in color spaces are highly customizable. You can define new color spaces by composing different components, such as primaries, white points, and transfer functions (encodings).

For example, you can define a custom RGB standard by combining encoding, white_point, and rgb::Rgb types.

use palette::{
    encoding,
    white_point,
    rgb::Rgb,
    Srgb
};

// Combining sRGB primaries, the CIE equal energy white point and the sRGB transfer function
type EqualEnergyStandard = (encoding::Srgb, white_point::E, encoding::Srgb);
type EqualEnergySrgb<T> = Rgb<EqualEnergyStandard, T>;

let ee_rgb = EqualEnergySrgb::new(1.0, 0.5, 0.3);

To use Palette in your project, add it to your Cargo.toml dependencies. By default, it includes std, alloc, named constants, and approx comparison support.

For standard usage:

[dependencies]
palette = "0.7.7"

If you are working in an embedded or no_std environment, you must disable default features and enable libm to provide floating-point math without the standard library:

[dependencies.palette]
version = "0.7.7"
default-features = false
features = ["libm"]

To use palette_math in a #![no_std] environment, you must disable the default std feature. You should then enable the libm feature to provide floating-point math operations via the libm crate, and the alloc feature if you require types that allocate memory (like Vec).

# Uses libm instead of std for floating point math:
palette_math = { version = "0.7.7", features = ["libm"], default-features = false }

To use palette_math in your Rust project, add it to your Cargo.toml dependencies. By default, it enables the std and alloc features.

[dependencies]
palette_math = "0.7.7"

The cast module provides traits and functions to treat slices or arrays of components (like &[u8]) as slices of Palette colors without cloning the entire buffer. This is highly efficient for image or pixel buffers.

• Use components_as_mut() to convert a mutable slice of components into a mutable slice of Palette colors (e.g., &mut [Srgb<u8>]).
• Use components_as() to convert a slice of components into a slice of Palette colors (e.g., &[Srgb<u8>]).
• You can also convert a single color from an object that implements AsMut<[u8; N]>.

use palette::{cast::ComponentsAsMut, Srgb};

// Convert `my_rgb_image` into `&mut [Srgb<u8>]` without copying.
fn swap_red_and_blue(my_rgb_image: &mut [u8]) {
    let my_rgb_image: &mut [Srgb<u8>] = my_rgb_image.components_as_mut();

    for color in my_rgb_image {
        std::mem::swap(&mut color.red, &mut color.blue);
    }
}

The UintCast trait is a marker trait used to identify types that can be represented as an unsigned integer with the same memory layout and size. This allows for zero-cost conversions between color types and integer types (e.g., converting an Srgba<u8> to a u32).

Safety Requirements

To implement UintCast safely, the type must satisfy these conditions:

• It must be inhabited (not Infallible).
• It must allow any bit pattern (or have a way to recover from invalid values).
• It must be a wrapper around Self::Uint or be safe to transmute to/from Self::Uint.
• It must not contain any internal padding.
• It must be repr(C) or repr(transparent).
• It must have the same size and alignment as Self::Uint.
• It is assumed not to implement Drop.