Struct scarlet::color::RGBColor

pub struct RGBColor {
    pub r: f64,
    pub g: f64,
    pub b: f64,
}

A color with red, green, and blue primaries of specified intensity, specifically in the sRGB gamut: most computer screens use this to display colors. The attributes r, g, and b are floating-point numbers from 0 to 1 for visible colors, allowing the avoidance of rounding errors or clamping errors when converting to and from RGB. Many conveniences are afforded so that working with RGB as if it were instead three integers from 0-255 is painless. Note that the integers generated from the underlying floating-point numbers round away from 0.

Examples of this abound: this is used ubiquitously in Scarlet. Check the Color documentation for plenty.

Fields

r: f64

The red component. Ranges from 0 to 1 for numbers displayable by sRGB machines.

g: f64

The green component. Ranges from 0 to 1 for numbers displayable by sRGB machines.

b: f64

The blue component. Ranges from 0 to 1 for numbers displayable by sRGB machines.

Implementations

impl RGBColor

pub fn int_r(&self) -> u8

Gets an 8-byte version of the red component, as a u8. Clamps values outside of the range 0-1 and discretizes, so this may not correspond to the exact values kept internally.

Example

let super_red = RGBColor{r: 1.2, g: 0., b: 0.};
let non_integral_red = RGBColor{r: 0.999, g: 0., b: 0.};
// the first one will get clamped in range, the second one will be rounded
assert_eq!(super_red.int_r(), non_integral_red.int_r());
assert_eq!(super_red.int_r(), 255);

pub fn int_g(&self) -> u8

Gets an 8-byte version of the green component, as a u8. Clamps values outside of the range 0-1 and discretizes, so this may not correspond to the exact values kept internally.

Example

let super_green = RGBColor{r: 0., g: 1.2, b: 0.};
let non_integral_green = RGBColor{r: 0., g: 0.999, b: 0.};
// the first one will get clamped in range, the second one will be rounded
assert_eq!(super_green.int_g(), non_integral_green.int_g());
assert_eq!(super_green.int_g(), 255);

pub fn int_b(&self) -> u8

Gets an 8-byte version of the blue component, as a u8. Clamps values outside of the range 0-1 and discretizes, so this may not correspond to the exact values kept internally.

Example

let super_blue = RGBColor{r: 0., g: 0., b: 1.2};
let non_integral_blue = RGBColor{r: 0., g: 0., b: 0.999};
// the first one will get clamped in range, the second one will be rounded
assert_eq!(super_blue.int_b(), non_integral_blue.int_b());
assert_eq!(super_blue.int_b(), 255);

pub fn int_rgb_tup(&self) -> (u8, u8, u8)

Purely for convenience: gives a tuple with the three integer versions of the components. Used over standard conversion traits to avoid ambiguous operations.

Example

let color = RGBColor{r: 0.3, g: 0.6, b: 0.7};
assert_eq!(color.int_rgb_tup(), (color.int_r(), color.int_g(), color.int_b()));

impl RGBColor

pub fn from_hex_code(hex: &str) -> Result<RGBColor, RGBParseError>

Given a string that represents a hex code, returns the RGB color that the given hex code represents. Four formats are accepted: "#rgb" as a shorthand for "#rrggbb", #rrggbb by itself, and either of those formats without #: "rgb" or "rrggbb" are acceptable. Returns a ColorParseError if the given string does not follow one of these formats.

Example

let fuchsia = RGBColor::from_hex_code("#ff00ff")?;
// if 3 digits, interprets as doubled
let fuchsia2 = RGBColor::from_hex_code("f0f")?;
assert_eq!(fuchsia.int_rgb_tup(), fuchsia2.int_rgb_tup());
assert_eq!(fuchsia.int_rgb_tup(), (255, 0, 255));
let err = RGBColor::from_hex_code("#afafa");
let err2 = RGBColor::from_hex_code("#gafd22");
assert_eq!(err, err2);

pub fn from_color_name(name: &str) -> Result<RGBColor, RGBParseError>

Gets the RGB color corresponding to an X11 color name. Case is ignored.

Example

let fuchsia = RGBColor::from_color_name("fuchsia")?;
let fuchsia2 = RGBColor::from_color_name("FuCHSiA")?;
assert_eq!(fuchsia.int_rgb_tup(), fuchsia2.int_rgb_tup());
assert_eq!(fuchsia.int_rgb_tup(), (255, 0, 255));
let err = RGBColor::from_color_name("fuccshai");
let err2 = RGBColor::from_color_name("foobar");
assert_eq!(err, err2);

impl RGBColor

pub fn from_material_palette(prim: MaterialPrimary) -> RGBColor

Gets a Color from the Material palette, given a specification of such a color.

Example

let red_400 = RGBColor::from_material_palette(MaterialPrimary::Red(MaterialTone::Neutral(NeutralTone::W400)));
let amber_a100 = RGBColor::from_material_palette(MaterialPrimary::Amber(MaterialTone::Accent(AccentTone::A100)));
assert_eq!(red_400.to_string(), "#EF5350");
assert_eq!(amber_a100.to_string(), "#FFE57F");

Trait Implementations

impl Bound for RGBColor

fn bounds() -> [(f64, f64); 3]

Returns an array [(min1, max1), (min2, max2), (min3, max3)] that represents the bounds on each component of the color space, in the order that they appear in the Coord representation. If some parts of the bounds don’t exist, using infinity or negative infinity works.

fn clamp_coord(point: Coord) -> Coord

Given a Coord, returns a Coord such that each component has been clamped to the correct bounds. See trait documentation for example usage.

fn clamp<T: ColorPoint>(color: T) -> T

Given a Color that can be embedded in 3D space, returns a new version of that color that is in the bounds of this color space, even if the coordinate systems of the two spaces differ. If the color is already in the gamut, it simply returns a copy. See trait documentation for example usage.

impl Clone for RGBColor

fn clone(&self) -> RGBColor

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Color for RGBColor

fn from_xyz(xyz: XYZColor) -> RGBColor

Converts from a color in CIE 1931 XYZ to the given color type.

fn to_xyz(&self, illuminant: Illuminant) -> XYZColor

Converts from the given color type to a color in CIE 1931 XYZ space. Because most color types don’t include illuminant information, it is provided instead, as an enum. For most applications, D50 or D65 is a good choice.

fn convert<T: Color>(&self) -> T

Converts generic colors from one representation to another. This is done by going back and forth from the CIE 1931 XYZ space, using the illuminant D50 (although this should not affect the results). Just like collect() and other methods in the standard library, the use of type inference will usually allow for clean syntax, but occasionally the turbofish is necessary.

fn hue(&self) -> f64

Gets the generally most accurate version of hue for a given color: the hue coordinate in CIELCH. There are generally considered four “unique hues” that humans perceive as not decomposable into other hues (when mixing additively): these are red, yellow, green, and blue. These unique hues have values of 0, 90, 180, and 270 degrees respectively, with other colors interpolated between them. This returned value will never be outside the range 0 to 360. For more information, you can start at the Wikpedia page.

fn set_hue(&mut self, new_hue: f64)

Sets a perceptually-accurate version hue of a color, even if the space itself does not have a conception of hue. This uses the CIELCH version of hue. To use another one, simply convert and set it manually. If the given hue is not between 0 and 360, it is shifted in that range by adding multiples of 360.

fn lightness(&self) -> f64

Gets a perceptually-accurate version of lightness as a value from 0 to 100, where 0 is black and 100 is pure white. The exact value used is CIELAB’s definition of luminance, which is generally considered a very good standard. Note that this is nonlinear with respect to the physical amount of light emitted: a material with 18% reflectance has a lightness value of 50, not 18.

fn set_lightness(&mut self, new_lightness: f64)

Sets a perceptually-accurate version of lightness, which ranges between 0 and 100 for visible colors. Any values outside of this range will be clamped within it.

fn chroma(&self) -> f64

Gets a perceptually-accurate version of chroma, defined as colorfulness relative to a similarly illuminated white. This has no explicit upper bound, but is always positive and generally between 0 and 180 for visible colors. This is done using the CIELCH model.

fn set_chroma(&mut self, new_chroma: f64)

Sets a perceptually-accurate version of chroma, defined as colorfulness relative to a similarly illuminated white. Uses CIELCH’s defintion of chroma for implementation. Any value below 0 will be clamped up to 0, but because the upper bound depends on the hue and lightness no clamping will be done. This means that this method has a higher chance than normal of producing imaginary colors and any output from this method should be checked.

fn saturation(&self) -> f64

Gets a perceptually-accurate version of saturation, defined as chroma relative to lightness. Generally ranges from 0 to around 10, although exact bounds are tricky. from This means that e.g., a very dark purple could be very highly saturated even if it does not seem so relative to lighter colors. This is computed using the CIELCH model and computing chroma divided by lightness: if the lightness is 0, the saturation is also said to be 0. There is no official formula except ones that require more information than this model of colors has, but the CIELCH formula is fairly standard.

fn set_saturation(&mut self, new_sat: f64)

Sets a perceptually-accurate version of saturation, defined as chroma relative to lightness. Does this without modifying lightness or hue. Any negative value will be clamped to 0, but because the maximum saturation is not well-defined any positive value will be used as is: this means that this method is more likely than others to produce imaginary colors. Uses the CIELCH color space. Generally, saturation ranges from 0 to about 1, but it can go higher.

fn grayscale(&self) -> Selfwhere Self: Sized,

Returns a new Color of the same type as before, but with chromaticity removed: effectively, a color created solely using a mix of black and white that has the same lightness as before. This uses the CIELAB luminance definition, which is considered a good standard and is perceptually accurate for the most part.

fn distance<T: Color>(&self, other: &T) -> f64

Returns a metric of the distance between the given color and another that attempts to accurately reflect human perception. This is done by using the CIEDE2000 difference formula, the current international and industry standard. The result, being a distance, will never be negative: it has no defined upper bound, although anything larger than 100 would be very extreme. A distance of 1.0 is conservatively the smallest possible noticeable difference: anything that is below 1.0 is almost guaranteed to be indistinguishable to most people.

fn visually_indistinguishable<T: Color>(&self, other: &T) -> bool

Using the metric that two colors with a CIEDE2000 distance of less than 1 are indistinguishable, determines whether two colors are visually distinguishable from each other. For more, check out this guide.

impl Debug for RGBColor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<(u8, u8, u8)> for RGBColor

fn from(rgb: (u8, u8, u8)) -> RGBColor

Converts to this type from the input type.

impl From<Coord> for RGBColor

fn from(c: Coord) -> RGBColor

Converts to this type from the input type.

impl From<RGBColor> for (u8, u8, u8)

fn from(val: RGBColor) -> Self

Converts to this type from the input type.

impl From<RGBColor> for Coord

fn from(val: RGBColor) -> Self

Converts to this type from the input type.

impl FromStr for RGBColor

type Err = RGBParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<RGBColor, RGBParseError>

Parses a string s to return a value of this type.

impl PartialEq<RGBColor> for RGBColor

fn eq(&self, other: &RGBColor) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ToString for RGBColor

fn to_string(&self) -> String

Converts the given value to a String.

impl Copy for RGBColor