Prisma - The Rust Color Library

Table of Contents:

• Overview
  • Color Models
  • Why Prisma?
  • A Tour by Example
• Details
• Definitions

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 toHsithat 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 theAlphatype.

Why Prisma?

Currently, there are two main color libraries for rust:

• color--coloris 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--palettehas 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 willnotget you that. It also is built on predefined models and doesn't support dynamic configuration.prismasupports considerably more color spaces, as well as multiple encodings and spaces which can be built at runtime.prismaalso 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]externcrateapprox;
externcrateangular_unitsasangle;
#externcrateprisma;

useprisma::{Rgb,Hsv,FromColor};
useangle::Deg;

letrgb =Rgb::new(0.5,0.75,1.0);
letmuthsv =Hsv::from_color(&rgb);
hsv.set_hue(Deg(180.0));
letrgb =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]externcrateapprox;
externcrateangular_unitsasangle;
#externcrateprisma;

useprisma::{Rgb,Hsl,FromColor,Lerp};
useangle::Deg;

letrgb1 =Rgb::new(0.8,0.25,0.0f32);
letrgb2 =Rgb::new(0.5,0.66,1.0);
// Specify the hue channel should use degrees
lethsl1:Hsl<_,Deg<f32>>=Hsl::from_color(&rgb1);
lethsl2 =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`.
letrgb_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]externcrateapprox;
#externcrateprisma;

useprisma::Rgb;

letrgb_in =Rgb::new(100,200,255u8);
letrgb_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]externcrateapprox;
#externcrateprisma;

useprisma::Rgb;
useprisma::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.
letrgb_srgb =Rgb::new(0.5,1.0,0.25f32).srgb_encoded();
// Decode goes from an encoding to linear.
letrgb_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`
letrgb_out = rgb_linear.encode(SrgbEncoding);
assert_relative_eq!(rgb_out, rgb_srgb, epsilon=1e-6);

Going to XYZ

#[macro_use]externcrateapprox;
#externcrateprisma;

useprisma::{Rgb,Xyz};
useprisma::encoding::{EncodableColor,TranscodableColor};
useprisma::color_space::{ColorSpace,EncodedColorSpace,NamedColorSpace,ConvertToXyz};
useprisma::color_space::presets::sRgb;

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