Struct Color

pub struct Color { /* private fields */ }

Color is a struct that represents a color.

Implementations

impl Color

Color channel extraction methods.

Examples

use color_art::{Color, color};
use std::str::FromStr;

let color = color!(rgba(10, 20, 30, 0.8));
assert_eq!(color.red(), 10);
assert_eq!(color.green(), 20);
assert_eq!(color.blue(), 30);
assert_eq!(color.alpha(), 0.8);

let color = Color::from_str("hsl(90, 100%, 50%)").unwrap();
assert_eq!(color.hue(), 90.0);
assert_eq!(color.saturation(), 1.0);
assert_eq!(color.lightness(), 0.5);

pub fn red(&self) -> u8

Extracts the red channel of color as a number between 0 and 255.

pub fn green(&self) -> u8

Extracts the green channel of color as a number between 0 and 255.

pub fn blue(&self) -> u8

Extracts the blue channel of color as a number between 0 and 255.

pub fn alpha(&self) -> f64

Extracts the alpha channel of color as a number between 0.0 and 1.0.

pub fn hue(&self) -> f64

Extracts the hue channel of color as a number between 0.0 and 360.0.

pub fn saturation(&self) -> f64

Extracts the HSL saturation of color as a number between 0.0 and 1.0.

pub fn lightness(&self) -> f64

Extracts the HSL lightness of color as a number between 0.0 and 1.0.

pub fn whiteness(&self) -> f64

Extracts the HWB whiteness of color as a number between 0.0 and 1.0.

pub fn blackness(&self) -> f64

Extracts the HWB blackness of color as a number between 0.0 and 1.0.

pub fn luma(&self) -> f64

Calculates the relative luminance of color.

the relative brightness of any point in a colorspace, normalized to 0 for darkest black and 1 for lightest white.

same as luminance()

pub fn luminance(&self) -> f64

Calculates the relative luminance of color.

the relative brightness of any point in a colorspace, normalized to 0 for darkest black and 1 for lightest white.

same as luma()

pub fn hsv_hue(&self) -> f64

Extracts the hue channel of color in the HSV color space.

pub fn hsv_saturation(&self) -> f64

Extracts the saturation channel of color in the HSV color space.

pub fn hsv_value(&self) -> f64

Extracts the value channel of color in the HSV color space.

pub fn gray(&self) -> f64

Calculates the gray value of color.

impl Color

pub fn from_num(num: u32) -> Result<Self, Error>

Returns the numeric representation of the hexadecimal color.

Examples

use color_art::Color;

let color = Color::from_num(0xff3399).unwrap();
assert_eq!(color.hex(), "#f39");

impl Color

pub fn from_rgb<T>(r: T, g: T, b: T) -> Result<Self, Error>

where T: Into<f64>,

Create a color from RGB values.

Parameters

• r: Red value (0-255)
• g: Green value (0-255)
• b: Blue value (0-255)

Examples

use color_art::Color;

let color = Color::from_rgb(255, 51, 153).unwrap();
assert_eq!(color.hex(), "#f39");

pub fn from_rgba<T>(r: T, g: T, b: T, a: f64) -> Result<Self, Error>

where T: Into<f64>,

Create a color from RGBA values.

Parameters

• r: Red value (0-255)
• g: Green value (0-255)
• b: Blue value (0-255)
• a: Alpha value (0-1)

Examples

use color_art::Color;
let color = Color::from_rgba(255, 51, 153, 0.5).unwrap();
assert_eq!(color.rgba(), "rgba(255, 51, 153, 0.5)");

pub fn from_hsl(h: f64, s: f64, l: f64) -> Result<Self, Error>

Create a color from HSL values.

Examples

use color_art::Color;

let color = Color::from_hsl(330.0, 1.0, 0.6).unwrap();
assert_eq!(color.hex(), "#f39");

pub fn from_hsv(h: f64, s: f64, v: f64) -> Result<Self, Error>

Create a color from HSV values.

Examples

use color_art::Color;

let color = Color::from_hsv(38.82, 1.0, 1.0).unwrap();
assert_eq!(color.hex(), "#ffa500");

pub fn from_cmyk(c: f64, m: f64, y: f64, k: f64) -> Result<Self, Error>

Create a color from CMYK values.

Examples

use color_art::Color;

let color = Color::from_cmyk(0.0, 0.8, 0.4, 0.0).unwrap();
assert_eq!(color.hex(), "#f39");

pub fn from_hex(hex_str: &str) -> Result<Self, Error>

Create a color from a hex string.

Examples

use color_art::Color;

let color = Color::from_hex("#ff3399").unwrap();
assert_eq!(color.hex(), "#f39");

let color = Color::from_hex("#ff339933").unwrap();
assert_eq!(color.hex(), "#f393");

pub fn from_name(name: &str) -> Result<Self, Error>

Create a color from a color name.

Currently supported color names are:

• English color names from X11_color_names
• 中国传统色 (Chinese traditional colors)

Examples

use color_art::Color;

let color = Color::from_name("yellow").unwrap();
assert_eq!(color.hex(), "#ff0");

let color = Color::from_name("水绿").unwrap();
assert_eq!(color.hex(), "#8cc269");

impl Color

Stringify a color to a string.

pub fn hex(self) -> String

hex string of the color

The hex string is simplified to a short hex string if possible.

For example:

• #ff00ff -> #f0f
• #ffffff88 -> #fff8

Examples

use color_art::Color;

let color = Color::new(255, 0, 255, 1.0);
assert_eq!(color.hex(), "#f0f");

let color = Color::new(255, 255, 255, 0.5);
assert_eq!(color.hex(), "#ffffff80");

pub fn hex_full(self) -> String

hex string of the color with the full length.

Examples

use color_art::Color;

let color = Color::new(255, 0, 255, 1.0);
assert_eq!(color.hex_full(), "#ff00ff");

pub fn rgb(self) -> String

rgb string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 255.0, 1.0);
assert_eq!(color.rgb(), "rgb(255, 255, 255)");

pub fn rgba(self) -> String

rgba string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 255.0, 0.5);
assert_eq!(color.rgba(), "rgba(255, 255, 255, 0.5)");

pub fn hsl(self) -> String

hsl string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 255.0, 1.0);
assert_eq!(color.hsl(), "hsl(0, 0%, 100%)");

pub fn hsla(self) -> String

hsla string of the color

Examples

use color_art::Color;

let color = Color::new(255, 255, 255, 0.3);
assert_eq!(color.hsla(), "hsla(0, 0%, 100%, 0.3)");

pub fn hsv(self) -> String

hsv string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 255.0, 1.0);
assert_eq!(color.hsv(), "hsv(0, 0%, 100%)");

pub fn hsi(self) -> String

hsi string of the color

Examples

use color_art::Color;

let color = Color::new(255, 255, 255, 1.0);
assert_eq!(color.hsi(), "hsi(0, 0%, 100%)");

pub fn hwb(self) -> String

hwb string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 255.0, 1.0);
assert_eq!(color.hwb(), "hwb(0, 100%, 0%)");

pub fn cmyk(self) -> String

cmyk string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 255.0, 1.0);
assert_eq!(color.cmyk(), "cmyk(0%, 0%, 0%, 0%)");

pub fn xyz(self) -> String

xyz string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 0.0, 0.0, 1.0);
assert_eq!(color.xyz(), "xyz(0.412391, 0.212639, 0.019331)");

pub fn yiq(self) -> String

yiq string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 0.0, 0.0, 1.0);
assert_eq!(color.yiq(), "yiq(0.299, 0.59572, 0.21146)");

pub fn yuv(self) -> String

yuv string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 0.0, 0.0, 1.0);
assert_eq!(color.yuv(), "yuv(0.299, -0.1471, 0.6148)");

pub fn lab(self) -> String

lab string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 0.0, 1.0);
assert_eq!(color.lab(), "lab(97.61, -15.75, 93.39)");

pub fn ycbcr(self) -> String

YCbCr string of the color

Examples

use color_art::Color;

let color = Color::new(255.0, 255.0, 0.0, 1.0);
assert_eq!(color.ycbcr(), "YCbCr(225.93, 0.5755, 148.7269)");

pub fn name(self) -> String

name of the color

The color name is based on the CSS3 color name or 中国传统色彩.

If the color is not named, the hex string will be returned.

Examples

use color_art::{Color, color};

let color = color!(#ffffff);
assert_eq!(color.name(), "white");

let color = color!(#f8df72);
assert_eq!(color.name(), "茉莉黄");

let color = Color::new(42, 42, 42, 1.0);
assert_eq!(color.name(), "#2a2a2a");

impl Color

pub fn vec_of(&self, color_space: impl Into<ColorSpace>) -> Vec<f64>

Get the color space vector of the color instance.

⚗️ Experimental: This method is experimental and may change frequently in the future.

Examples

use color_art::{color, ColorSpace};

let color = color!(rgb(255, 51, 153));
let vec = color.vec_of(ColorSpace::RGB);
assert_eq!(vec, vec![255.0, 51.0, 153.0]);

let vec = color.vec_of(ColorSpace::HSV);
assert_eq!(vec, vec![330.0, 0.8, 1.0]);

impl Color

pub fn new<T>(r: T, g: T, b: T, alpha: f64) -> Self

where T: Into<f64>,

Creates a new Color.

impl Color

pub fn average(colors: &[Color]) -> Color

Average a list of colors.

This function will return a new color that is the average of the colors in the list. It will calculate the average of the RGB channels and alpha values of the colors. If the list length is 0, it will return a black color.

Examples

use color_art::Color;
use std::str::FromStr;

let colors = vec![
   Color::from_str("#ff6600").unwrap(),
   Color::from_str("rgba(0, 0, 0, 0.5)").unwrap(),
];

let averaged_color = Color::average(&colors);
assert_eq!(averaged_color.rgba(), "rgba(128, 51, 0, 0.75)");

impl Color

pub fn mix(color1: &Color, color2: &Color, weight: f64) -> Result<Self, Error>

Mix two colors with a weight.

Arguments

• color1 - The first color.
• color2 - The second color.
• weight - The weight of the first color. Must be between 0.0 and 1.0.

Examples

use color_art::{Color, color};

let color1 = color!(#998099);
let color2 = color!(#191970);
let color3 = Color::mix(&color1, &color2, 0.5).unwrap();
assert_eq!(color3.hex(), "#594d85");

impl Color

pub fn random() -> Color

Generate a random color.

Examples

use color_art::Color;

let color = Color::random();

impl Color

pub fn darken(&self, amount: f64) -> Self

Decrease the lightness of a color in the HSL color space by an absolute amount.

Arguments

amount - The amount to decrease the lightness by. Must be between 0.0 and 1.0.

Examples

use color_art::color;

let color = color!(#426105);
let color = color.darken(0.1);
assert_eq!(color.hex(), "#213102");

pub fn lighten(&self, amount: f64) -> Self

Increase the lightness of a color in the HSL color space by an absolute amount.

Arguments

amount - The amount to increase the lightness by. Must be between 0.0 and 1.0.

Examples

use color_art::color;

let color = color!(#80e619);
let color = color.lighten(0.2);
assert_eq!(color.hex(), "#b3f075");

impl Color

pub fn fade(&self, amount: f64) -> Self

Set the absolute opacity of a color.

Can be applied to colors whether they already have an opacity value or not.

Examples

use color_art::color;

let color = color!(rgba(0, 255, 0, 0.8));
assert_eq!(color.alpha(), 0.8);
let color = color.fade(0.5);
assert_eq!(color.alpha(), 0.5);

pub fn fade_in(&self, amount: f64) -> Self

Decrease the transparency (or increase the opacity) of a color, making it more opaque.

Examples

use color_art::color;

let color = color!(rgba(0, 255, 0, 0.8));
assert_eq!(color.alpha(), 0.8);
let color = color.fade_in(0.1);
assert_eq!(color.alpha(), 0.9);

pub fn fade_out(&self, amount: f64) -> Self

Increase the transparency (or decrease the opacity) of a color, making it less opaque.

Examples

use color_art::color;

let color = color!(rgba(0, 255, 0, 0.8));
assert_eq!(color.alpha(), 0.8);
let color = color.fade_out(0.2);
assert_eq!(color.alpha(), 0.6);

impl Color

pub fn mix_with(&self, new_color: &Color, weight: f64) -> Self

Mix two colors with a weight.

Arguments

• color - The color to mix with.
• weight - The weight of the new color to mix with. 0.0 is all the original color, 1.0 is all the new color.

Examples

use color_art::color;

let color1 = color!(#998099);
let color2 = color!(#d2e1dd);
let color3 = color1.mix_with(&color2, 0.5);
assert_eq!(color3.hex(), "#b6b1bb");

pub fn tint(&self, amount: f64) -> Self

Mix color with white in variable proportion.

Arguments

• amount - The amount of white to mix in. 0.0 is no white, 1.0 is all white.

Examples

use color_art::color;

let color = color!(#ff00ff);
let color = color.tint(0.5);
assert_eq!(color.hex(), "#ff80ff");

pub fn shade(&self, amount: f64) -> Self

Mix color with black in variable proportion.

Arguments

• amount - The amount of black to mix in. 0.0 is no black, 1.0 is all black.

Examples

use color_art::color;

let color = color!(#ff00ff);
let color = color.shade(0.5);
assert_eq!(color.hex(), "#800080");

impl Color

pub fn negate(self) -> Self

Negates a color with rgb channels. The alpha channel is not affected.

Example

use color_art::color;

let color1 = color!(#f0f);
let color2 = color1.negate();
assert_eq!(color2.hex(), "#0f0");

impl Color

pub fn saturate(&self, amount: f64) -> Self

Increase the saturation of a color in the HSL color space by an absolute amount.

Arguments

amount - The amount to increase the saturation by. Must be between 0.0 and 1.0.

Examples

use color_art::color;

let color = color!(#80e619);
let color = color.saturate(0.2);
assert_eq!(color.hex(), "#80ff00");

pub fn desaturate(&self, amount: f64) -> Self

Decrease the saturation of a color in the HSL color space by an absolute amount.

Arguments

amount - The amount to decrease the saturation by. Must be between 0.0 and 1.0.

Examples

use color_art::color;

let color = color!(#80e619);
let color = color.desaturate(0.2);
assert_eq!(color.hex(), "#80cd32");

pub fn greyscale(&self) -> Self

greyscale

Remove all saturation from a color in the HSL color space.

Examples

use color_art::color;
use std::str::FromStr;

let color = color!(#80e619);
let color = color.greyscale();
assert_eq!(color.hex(), "#808080");

impl Color

pub fn spin(&self, angle: f64) -> Self

Rotate the hue angle of a color in either direction.

Arguments

• angle - The angle to rotate the hue by. Positive values rotate clockwise, negative values rotate counter-clockwise.

Examples

use color_art::Color;
use std::str::FromStr;

let color = Color::from_str("hsl(10, 90%, 50%)").unwrap();
let color = color.spin(30.0);
assert_eq!(color.hsl(), "hsl(40, 90%, 50%)");

let color = Color::from_str("hsl(10, 90%, 50%)").unwrap();
let color = color.spin(-30.0);
assert_eq!(color.hsl(), "hsl(340, 90%, 50%)");

pub fn complement(&self) -> Self

Returns the complement of color.

Trait Implementations

impl Clone for Color

fn clone(&self) -> Color

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Color

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

Formats the value using the given formatter.

impl Default for Color

fn default() -> Self

default returns a black color.

impl<'de> Deserialize<'de> for Color

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Color

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

Formats the value using the given formatter.

impl FromStr for Color

fn from_str(s: &str) -> Result<Self, Error>

Creates a new Color from a string.

Examples

use color_art::Color;
use std::str::FromStr;

let s = "rgb(255, 255, 255)";
let color = Color::from_str(s).unwrap();
assert_eq!(color, Color::new(255, 255, 255, 1.0));

let s = "rgba(255, 255, 255, 0.5)";
let color = Color::from_str(s).unwrap();
assert_eq!(color, Color::new(255, 255, 255, 0.5));

let s = "#ffffff";
let color = Color::from_str(s).unwrap();
assert_eq!(color, Color::new(255, 255, 255, 1.0));

let s = "hsl(0, 0%, 100%)";
let color = Color::from_str(s).unwrap();
assert_eq!(color, Color::new(255, 255, 255, 1.0));

let s = "hsv(0, 0%, 100%)";
let color = Color::from_str(s).unwrap();
assert_eq!(color, Color::new(255, 255, 255, 1.0));

let s = "deeppink";
let color = Color::from_str(s).unwrap();
assert_eq!(color, Color::new(255, 20, 147, 1.0));

let s = "水绿";
let color = Color::from_str(s).unwrap();
assert_eq!(color, Color::new(140, 194, 105, 1.0));

type Err = Error

The associated error which can be returned from parsing.

impl PartialEq for Color

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl Serialize for Color

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for Color

impl StructuralPartialEq for Color