colors_transform/
lib.rs

1//! A module for color conversion and mutation.
2//!
3//! For now you can work with four color representation options: Rgb (Rgba), Hsl (Hsla). Each of them has a variety of methods to modify and convert. See the Color trait they implement. There are also a couple of methods for hex string color.
4//!
5//! All values are given as f32 for more accurate calculations.
6//!
7//! ## What It Can Do
8//!
9//! ### getters & setters
10//! ```
11//! use colors_transform::{Rgb, Color};
12//! let rgb = Rgb::from(57.3, 12.7, 53.0);
13//! // where tuple is ($red, $green, $blue)
14//!
15//! let modified = rgb
16//!   .set_red(245.0) // Rgb { r: 245.0, g: 152.0, b: 53.0 }
17//!   .set_green(152.0) // Rgb { r: 245.0, g: 152.0, b: 53.0 }
18//!   .set_hue(279.0); // Rgb { r: 177.80003, g: 53.00001, b: 245.0 }
19//!
20//! let saturation = modified.get_saturation(); // 63.71429
21//! let blue = modified.get_blue(); // 53.00001
22//!
23//! ```
24//!
25//! ### conversion
26//! ```ignore
27//! let hex_color = Hsl::from(315.9, 99.7, 50.0)
28//! // where tuple is ($hue, $saturation, $lightness)
29//!   .to_rgb() // ~Rgb { r: 254.6, g: 0.38, b: 187.24 }
30//!   .set_saturation(33.3) // ~Rgb { r: 169.9, g: 85.04, b: 147.45 }
31//!   .to_hsl() // Hsl { h: 315.9, s: 33.3, l: 50.0 }
32//!   .set_alpha(0.47) // Hsl { h: 315.9, s: 99.7, l: 50.0 } // a: 0.47
33//!   .to_rgb() // Rgb { r: 169.95749, g: 85.0425, b: 147.45502 }
34//!   .to_css_hex_string(); // #aa5593
35//! ```
36//!
37//! ### modification
38//! ```ignore
39//! let rgb = Rgb::from(245.0,152.0,53.0)
40//!   .lighten(21.0) // Rgb { r: 250.05188, g: 204.03442, b: 155.04813 }
41//!   .saturate( 3.9999 ); // Rgb { r: 252.14981, g: 204.1, b: 152.9502 }
42//! ```
43//!
44//! ### parsing from string & css string representation
45//! ```ignore
46//! let hsl: Hsl = "hsl(359,12%,71)".parse().unwrap();
47//! // Hsl { h: 359.0, s: 12.0, l: 71.0 alpha: 0.3 }
48//!
49//! let rgb1 = "rgb(12,13,14)"
50//!   .parse::<Rgb>()
51//!   .unwrap()
52//!   .adjust_color( RgbUnit::Green, 139.7 );
53//! // Rgb { r: 12.0, g: 152.7, b: 14.0 }
54//!
55//! let rgb2 = Rgb::from_hex_str("#fc0").unwrap();
56//! // Rgb { r: 255.0, g: 204.0, b: 0.0 }
57//!
58//! let rgb_str = rgb1.to_css_string();
59//! // rgb(12,153,14)
60//!
61//! let hsl_str = rgb2.to_hsl().to_css_string();
62//! // "hsl(48,100%,50%)"
63//! ```
64//!
65//! As you see it is completely chainable.
66//!
67//!
68//! ## Color unit ranges
69//! All color units is f32. Here are their ranges:
70//!  - red - 0.0 .. 255.0
71//!  - green - 0.0 .. 255.0
72//!  - blue - 0.0 .. 255.0
73//!  - hue - 0.0 .. 359.0
74//!  - saturation - 0.0 .. 100.0
75//!  - lightness - 0.0 .. 100.0
76//!  - alpha - 0.0 .. 1.0
77//!
78//! If you specify a value that does not fit within these ranges, they are replaced with a minimum or maximum value.
79//!
80//!
81//! <p style="margin: 50px 0">Enjoy using!</p>
82//! <style>
83//! h3 {border:none !important; margin: 30px 0px 0px 0px !important}
84//! </style>
85
86mod colors;
87mod converters;
88mod error;
89mod from_str;
90mod grayscale;
91mod normalize;
92
93#[cfg(test)]
94mod tests;
95
96pub use colors::{Hsl, Rgb};
97pub use grayscale::GrayScaleMethod;
98
99pub use error::ParseError;
100
101/// Tuple type just for data exchange. May be a:
102/// - `($red,$green,$blue)` _`(0.0..255.0, 0.0..255.0, 0.0..255.0)`_
103///
104/// or
105///
106/// - `($hue, $saturation, $lightness)` _`(0.0..359.0, 0.0..100.0, 0.0..100.0)`_
107/// # Example
108/// ```
109/// use colors_transform::{Rgb,Color,Hsl};
110///
111/// let rgb = Rgb::from_tuple(&(255.0,13.0,177.0));
112/// assert_eq!(rgb.get_red(), 255.0);
113///
114/// let hsl: Hsl = "hsl(315,99,12)".parse().unwrap();
115/// assert_eq!(hsl.get_saturation(), 99.0);
116/// ```
117pub type ColorTuple = (f32, f32, f32);
118
119/// Like a `ColorTuple` but with fourth alpha value
120pub type ColorTupleA = (f32, f32, f32, f32);
121
122/// Common to all trait
123pub trait Color {
124  /// ColorTuple or ColorTupleA.
125  ///
126
127  type Tuple;
128  type TupleA;
129  /// Creates a black color
130  /// # Example
131  /// ```
132  /// use colors_transform::{Rgb,Color};
133  ///
134  /// let black = Rgb::from(0.0,0.0,0.0);
135  /// assert_eq!(black, Rgb::new());
136  /// ```
137  fn new() -> Self;
138
139  /// Creates a color from tuple.
140  /// # Example
141  /// ```
142  /// use colors_transform::{Rgb,Hsl,Color};
143  ///
144  /// let rgb = Rgb::from_tuple(&(10.0,11.0,12.0));
145  /// let hsl = Hsl::from(310.0,50.0,50.0);
146  /// ```
147  fn from_tuple(tuple: &Self::Tuple) -> Self;
148
149  fn from_tuple_with_alpha(tuple: &Self::TupleA) -> Self;
150
151  /// Returns tuple representation of color
152  /// # Example
153  /// ```
154  /// use colors_transform::{Hsl,Color};
155  /// let hsl_tuple = (10.0,11.0,12.0);
156  /// let hsl = Hsl::from_tuple(&hsl_tuple);
157  /// assert_eq!(hsl_tuple,hsl.as_tuple());
158  /// ```
159  fn as_tuple(&self) -> Self::Tuple;
160
161  /// Returns red value of color (`0.0..255.00`)
162  fn get_red(&self) -> f32;
163
164  /// Returns green value of color (`0.0..255.00`)
165  fn get_green(&self) -> f32;
166
167  /// Returns blue value of color (`0.0..255.00`)
168  fn get_blue(&self) -> f32;
169
170  /// Sets red value of color (`0.0..255.00`). Returns Color
171  fn set_red(&self, val: f32) -> Self;
172
173  /// Sets green value of color (`0.0..255.00`). Returns Color
174  fn set_green(&self, val: f32) -> Self;
175
176  /// Sets blue value of color (`0.0..255.00`). Returns Color
177  fn set_blue(&self, val: f32) -> Self;
178
179  /// Returns hue value of color (`0.0..359.00`)
180  fn get_hue(&self) -> f32;
181
182  /// Returns saturation value of color (`0.0..100.00`)
183  fn get_saturation(&self) -> f32;
184
185  /// Returns lightness value of color (`0.0..100.00`)
186  fn get_lightness(&self) -> f32;
187
188  /// Sets hue value of color (`0.0..359.00`). Returns Color
189  fn set_hue(&self, val: f32) -> Self;
190
191  /// Sets saturation value of color (`0.0..100.00`). Returns Color
192  fn set_saturation(&self, val: f32) -> Self;
193
194  /// Sets lightness value of color (`0.0..100.00`). Returns Color
195  fn set_lightness(&self, val: f32) -> Self;
196
197  fn to_rgb(&self) -> Rgb;
198  fn to_hsl(&self) -> Hsl;
199
200  /// Returns css string
201  /// # Example
202  /// ```
203  /// use colors_transform::{Hsl,Color};
204  ///
205  /// let hsl = Hsl::from_tuple(&(301.0,27.0,91.0));
206  /// assert_eq!(hsl.to_css_string(), "hsl(301,27%,91%)");
207  /// ```
208  fn to_css_string(&self) -> String;
209
210  fn adjust_hue(&self, amt: f32) -> Self;
211  fn saturate(&self, amt: f32) -> Self;
212  fn lighten(&self, amt: f32) -> Self;
213  fn adjust_color(&self, col_name: RgbUnit, val: f32) -> Self;
214  fn invert(&self) -> Self;
215}
216
217/// Some methods for working with alpha channel for Rgba & Hsla
218pub trait AlphaColor {
219  fn get_alpha(&self) -> f32;
220  fn set_alpha(&self, a: f32) -> Self;
221  fn opacify(&self, o: f32) -> Self;
222}
223
224#[derive(Clone, Copy)]
225pub enum RgbUnit {
226  Red,
227  Green,
228  Blue,
229}
colors_transform/lib.rs

colors_transform/
lib.rs
