Struct Matrix3 

pub struct Matrix3<I, O>
where
    I: ArrayCast,
{ /* private fields */ }

A statically typed 3x3 conversion matrix.

It’s applied via Convert or ConvertOnce and helps making some conversions more efficient by only needing to be constructed once.

use palette::{
    Xyz, Srgb,
    convert::{Convert, Matrix3},
};

// Multiple matrices can be combined into one:
let matrix = Xyz::matrix_from_rgb()
    .then(Matrix3::scale(0.5, 0.5, 0.5));

let rgb = Srgb::new(0.8f32, 0.3, 0.3).into_linear();
let scaled_xyz = matrix.convert(rgb);

Implementations

impl<T, C> Matrix3<C, C>

where C: ArrayCast<Array = [T; 3]>,

pub fn identity() -> Matrix3<C, C>

where T: One + Zero,

Produce an identity matrix, which leaves the components unchanged.

use palette::{Srgb, convert::{Matrix3, Convert}};

let matrix = Matrix3::identity();

let input = Srgb::new(0.1, 0.2, 0.3);
let output = matrix.convert(input);

assert_eq!(input, output);

pub fn scale(s1: T, s2: T, s3: T) -> Matrix3<C, C>

where T: Zero,

Produce a scale matrix, which scales each component separately.

use palette::{Srgb, convert::{Matrix3, Convert}};

let matrix = Matrix3::scale(0.1, 0.2, 0.3);

let input = Srgb::new(1.0, 1.0, 1.0);
let output = matrix.convert(input);

assert_eq!(Srgb::new(0.1, 0.2, 0.3), output);

impl<T, I, O> Matrix3<I, O>

where I: ArrayCast<Array = [T; 3]>, O: ArrayCast<Array = <I as ArrayCast>::Array>,

pub fn then<U>(self, next: Matrix3<O, U>) -> Matrix3<I, U>

where U: ArrayCast<Array = <I as ArrayCast>::Array>, T: Arithmetics + Clone,

Chain another matrix after this one.

The combined matrix will result in the same values as if the two matrices were applied separately, at the cost of only applying a single matrix. This may speed up computations if the matrix can be constructed once, and applied multiple times.

use palette::{
    lms::VonKriesLms, Xyz, Srgb,
    convert::Convert,
    white_point::D65,
};
use approx::assert_relative_eq;

let rgb_to_xyz = Xyz::matrix_from_rgb();
let xyz_to_lms = VonKriesLms::<D65, _>::matrix_from_xyz();

let rgb_to_lms = rgb_to_xyz.then(xyz_to_lms);

let rgb = Srgb::new(0.8f32, 0.3, 0.3).into_linear();
let lms = rgb_to_lms.convert(rgb);

// Applying the matrices separately for comparison:
let xyz = rgb_to_xyz.convert(rgb);
let lms2 = xyz_to_lms.convert(xyz);
assert_relative_eq!(lms, lms2);

pub fn invert(self) -> Matrix3<O, I>

where T: Recip + IsValidDivisor<Mask = bool> + Arithmetics + Clone,

Invert the matrix to create a reversed conversion.

Panics

A matrix that cannot be inverted will result in a panic.

Examples

use palette::{
    Xyz, Srgb,
    convert::Convert,
};
use approx::assert_relative_eq;

let rgb_to_xyz = Xyz::matrix_from_rgb();
let xyz_to_rgb = rgb_to_xyz.invert();

let rgb = Srgb::new(0.8f32, 0.3, 0.3).into_linear();
let xyz = rgb_to_xyz.convert(rgb);
let rgb2 = xyz_to_rgb.convert(xyz);

assert_relative_eq!(rgb, rgb2);

pub const fn from_array(matrix: [T; 9]) -> Matrix3<I, O>

Create a conversion matrix from a plain array.

The matrix elements are expected to be in row-major order.

This doesn't verify that the conversion results in correct or expected values.

use palette::{Srgb, convert::{Matrix3, Convert}};

let matrix = Matrix3::from_array([
    1.0, 0.0, 0.0,
    0.0, 1.0, 0.0,
    0.0, 0.0, 1.0,
]);

let input = Srgb::new(0.1, 0.2, 0.3);
let output = matrix.convert(input);

assert_eq!(input, output);

pub fn into_array(self) -> [T; 9]

Extract the inner array.

The matrix elements are stored in row-major order.

Trait Implementations

impl<I, O> Clone for Matrix3<I, O>

where I: ArrayCast, <<I as ArrayCast>::Array as ArrayExt>::Item: Clone,

fn clone(&self) -> Matrix3<I, O>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<I, O> Convert<I, O> for Matrix3<I, O>

where Matrix3<I, O>: ConvertOnce<I, O> + Copy, I: ArrayCast,

fn convert(&self, input: I) -> O

Convert an input value of type I to a value of type O.

impl<T, I, O> ConvertOnce<I, O> for Matrix3<I, O>

where T: Arithmetics, I: ArrayCast<Array = [T; 3]>, O: ArrayCast<Array = <I as ArrayCast>::Array>,

fn convert_once(self, input: I) -> O

Convert an input value of type I to a value of type O, while consuming itself.

impl<I, O> Copy for Matrix3<I, O>

where I: ArrayCast, <<I as ArrayCast>::Array as ArrayExt>::Item: Copy,