[−][src]Crate prisma

Prisma - The Rust Color Library

Overview:

Prisma is a rust library aimed to be a comprehensive set of color representations, manipulations, conversions and algorithms that are easy to use for projects of all levels. Prisma follows a model of "opt-in" complexity, meaning that if you just want a library to convert from Rgb to Hsv and back, prisma will let you do it with minimal knowledge of color science. If you need to access the CIE spaces or do color space conversions however, prisma also provides that functionality with wrappers to use the type system to enforce validity.

Prisma aims to be the go-to source for color conversions and color science in rust. It is currently a work in progress, and any contributions or feature requests are appreciated.

Color Models:

Currently prisma supports the following color models:

Device Dependent:

Rgb - The standard color model for displays
Rgi - A chromaticity model constructed from Rgb that decouples chromaticity and lightness
Hsv - Hue, saturation, value: a more intuitive polar Rgb model
Hsl - Hue, saturation, lightness: an alternate to Hsv fulfilling similar roles
Hsi - Hue, saturation, intensity: a hue-based model without distortion
eHsi - An extension to Hsi that rescaled saturation to avoid going out of gamut in Rgb
Hwb - Hue, whiteness, blackness: a hue-based model made to be easy for users to select colors in
YCbCr - A representation of the various YUV and YIQ models used in display and broadcast

Device Independent:

Xyz - The "parent" absolute color space other color spaces are defined in terms of
Lms - A color space simulating human cone response
Lab - A uniform perception color space transformation of XYZ
Lchab - A polar transformation of Lab. A uniform perception analog of Hsl
Luv - An alternative uniform perception color space useful in lighting calculations
Lchuv - A polar transformation of Luv

Prisma also supports these color spaces with an alpha channel via the Alpha type.

Why Prisma?

Currently, there are two main color libraries for rust:

color -- color is a very old library that hasn't been updated in several years. While it works for conversion through a few color spaces, and is easy to use, it has a very minimal set of features.
palette -- palette has significantly more features and can go into a few of the CIE spaces, but requiring all computations to be done in linear encoding is a serious drawback, as if you just want a nice looking gradient in a game, linear Hsv will not get you that. It also is built on predefined models and doesn't support dynamic configuration. prisma supports considerably more color spaces, as well as multiple encodings and spaces which can be built at runtime. prisma also does not require you to specify a color space, as most applications don't really care and use the device color space or sRgb.

Prisma aims to support all the features of the above libraries, while making it up to the user how much complexity they need.

A Tour by Example:

Converting from Rgb to Hsv, manipulating hue, and converting back

#[macro_use] extern crate approx;
extern crate angular_units as angle;

use prisma::{Rgb, Hsv, FromColor};
use angle::Deg;

let rgb = Rgb::new(0.5, 0.75, 1.0);
let mut hsv = Hsv::from_color(&rgb);
hsv.set_hue(Deg(180.0));
let rgb = Rgb::from_color(&hsv);
assert_relative_eq!(rgb, Rgb::new(0.5, 1.0, 1.0), epsilon=1e-6);

Interpolating between two colors in Hsl.

#[macro_use] extern crate approx;
extern crate angular_units as angle;

use prisma::{Rgb, Hsl, FromColor, Lerp};
use angle::Deg;

let rgb1 = Rgb::new(0.8, 0.25, 0.0f32);
let rgb2 = Rgb::new(0.5, 0.66, 1.0);
// Specify the hue channel should use degrees
let hsl1: Hsl<_, Deg<f32>> = Hsl::from_color(&rgb1);
let hsl2 = Hsl::from_color(&rgb2);
// Note that hue channels will interpolate in the shortest direction. This is usually
// the expected behavior, but you can always go forward with `lerp_flat`.
let rgb_out = Rgb::from_color(&hsl1.lerp(&hsl2, 0.35));
assert_relative_eq!(rgb_out, Rgb::new(1.0, 0.045, 0.62648), epsilon=1e-4);

Converting from Rgb to Rgb

#[macro_use] extern crate approx;

use prisma::Rgb;

let rgb_in = Rgb::new(100, 200, 255u8);
let rgb_out: Rgb<f32> = rgb_in.color_cast();
assert_relative_eq!(rgb_out, Rgb::new(0.39216, 0.78431, 1.0), epsilon=1e-4);

Convert from sRgb encoded to linear encoded Rgb

#[macro_use] extern crate approx;

use prisma::Rgb;
use prisma::encoding::{EncodableColor, TranscodableColor, SrgbEncoding};

// This returns a `EncodedColor<Rgb<f32>, SrgbEncoding>`
// Note: no encodind is done. `srgb_encoded` says that this value is already in sRgb encoding.
let rgb_srgb = Rgb::new(0.5, 1.0, 0.25f32).srgb_encoded();
// Decode goes from an encoding to linear.
let rgb_linear = rgb_srgb.clone().decode();
assert_relative_eq!(rgb_linear, Rgb::new(0.21404, 1.0, 0.05088).linear(), epsilon=1e-4);
// We can then go back with `encode`
let rgb_out = rgb_linear.encode(SrgbEncoding);
assert_relative_eq!(rgb_out, rgb_srgb, epsilon=1e-6);

Going to XYZ

#[macro_use] extern crate approx;

use prisma::{Rgb, Xyz};
use prisma::encoding::{EncodableColor, TranscodableColor};
use prisma::color_space::{ColorSpace, EncodedColorSpace, ConvertToXyz};
use prisma::color_space::named::SRgb;

let rgb = Rgb::new(0.25, 0.5, 0.75f32).srgb_encoded();
let color_space = SRgb::new();
// In this case, since rgb and color_space know their own encodings, the conversion to linear
// is automatic.
let xyz = color_space.convert_to_xyz(&rgb);
assert_relative_eq!(xyz, Xyz::new(0.191803, 0.201605, 0.523050), epsilon=1e-5);

Modules

channel	Provides helper scalar and channel types used internally by the color types allowing them to be used generically over the underlying types.
color_space	Traits and structures to define color spaces and convert from device-dependent to device-independent spaces
encoding	Traits and structs for dealing with and changing a color's encoding
lms	The LMS cone response device-independent color space
tags	Unit structs for identifying the various color models in generic contexts
white_point	Defines the named standard illuminants for both 2 and 10 degree observers
ycbcr	A module for encoded values in the YUV and YIQ family of device-dependent color models.

Structs

Alpha	A wrapper around a color with an alpha channel
ChromaticityCoordinates	A pair of chromaticity coordinates $`\alpha`$ and $`\beta`$
Hsi	The HSI device-dependent polar color space
Hsl	The HSL device-dependent polar color model
Hsv	The HSV device-dependent polar color model
Hwb	The HWB device-dependent polar color model
Lab	The CIELAB perceptually uniform device-independent color space
Lchab	The $`\textrm{Lch}_{(\textrm{ab})}`$ device-independent polar color space
Lchuv	The $`\textrm{Lch}_{(\textrm{uv})}`$ device-independent polar color space
Luv	The CIELUV perceptually uniform device-independent color space
Matrix3	A 3x3 matrix used for linear color transformations
Rgb	The `Rgb` device-dependent cartesian color model.
Rgi	The rgI device-dependent chromaticity color model
XyY	The xyY device-independent chromaticity space
Xyz	The CIE XYZ device-independent color space
eHsi	The eHSI device-dependent polar color model

Enums

HsiOutOfGamutMode

Defines methods for handling out-of-gamut transformations from Hsi to Rgb

Traits

Bounded	A value that is constrained between a minimum and maximum in its "normal" form
Broadcast	A color that can have all of its channels set from a single value
Color	The base color trait, representing any color
Color3	A color with three channels
Color4	A color with four channels
DeviceDependentColor	A color which must have a space specified in order to uniquely represent a color
Flatten	A color that can be represented as a slice without any conversion
FromColor	Infallibly convert between two color models
FromHsi	Convert from Hsi to another color model
FromTuple	A trait for colors that can be constructed from a tuple of channels
FromYCbCr	Convert from YCbCr to another color model
HomogeneousColor	A color only having one type of channel
Invert	A value that can be inverted
Lerp	A value that can be linearly interpolated between two values
PolarColor	A color that has a angular hue channel

Type Definitions

Hsia	An `Hsi` value with an alpha channel
Hsla	An `Hsl` value with an alpha channel
Hsva	An `Hsv` value with an alpha channel
Hwba	An `Hwb` value with an alpha channel
Laba	An `Lab` value with an alpha channel
Lchaba	An `Lchab` value with an alpha channel
Lchauv	An `Lchuv` value with an alpha channel
Lmsa	An `Lmsa` value with an alpha channel
Luva	An `Luv` value with an alpha channel
Rgba	An `Rgb` value with an alpha channel
Rgia	An `Rgi` value with an alpha channel
XyYa	An `XyY` value with an alpha channel
Xyza	An `Xyz` value with an alpha channel
YCbCra	An `YCbCr` value with an alpha channel
eHsia	An `eHsi` value with an alpha channel