Skip to main content

three_rs/math/
color.rs

1//! Port of `three.js/src/math/Color.js`.
2//!
3//! three.js' colour management is on by default: a hex literal is interpreted
4//! as sRGB and stored in the working colour space (linear-sRGB), which is what
5//! the renderer then uses as a clear value. The working space here is always
6//! `LinearSRGBColorSpace` and the only other space with a transfer function is
7//! `SRGBColorSpace`, so the `ColorManagement.convert()` machinery collapses to
8//! the two transfer functions below (the primaries never differ, and
9//! `NoColorSpace` converts nothing).
10
11use super::math_utils::{clamp, euclidean_modulo, js_max, js_min, lerp};
12use super::vector3::js_round;
13use super::{ColorSpace, Matrix3, Vector3};
14
15/// The `{ h, s, l }` object `Color.getHSL()` fills in.
16#[derive(Clone, Copy, Debug, Default, PartialEq)]
17pub struct Hsl {
18    /// Hue, in 0..1.
19    pub h: f64,
20    /// Saturation, in 0..1.
21    pub s: f64,
22    /// Lightness, in 0..1.
23    pub l: f64,
24}
25
26/// Port of `three.js/src/math/Color.js`'s `Color` class: an RGB color, stored
27/// in the working color space (linear-sRGB).
28#[derive(Clone, Copy, Debug, PartialEq)]
29pub struct Color {
30    /// The red channel.
31    pub r: f64,
32    /// The green channel.
33    pub g: f64,
34    /// The blue channel.
35    pub b: f64,
36}
37
38impl Default for Color {
39    /// `new Color()` — three.js' constructor initialises to white before
40    /// applying its arguments, so a no-argument `Color` is white.
41    fn default() -> Self {
42        Self::new(1.0, 1.0, 1.0)
43    }
44}
45
46impl Color {
47    /// `new Color( r, g, b )` / `setRGB( r, g, b )` with the working colour
48    /// space, i.e. the components are stored as given.
49    pub const fn new(r: f64, g: f64, b: f64) -> Self {
50        Self { r, g, b }
51    }
52
53    /// `new Color( hex )` — `setHex( hex, SRGBColorSpace )`.
54    pub fn from_hex(hex: u32) -> Self {
55        let mut c = Self::default();
56        c.set_hex(hex, ColorSpace::Srgb);
57        c
58    }
59
60    /// `Color.setScalar()`.
61    pub fn set_scalar(&mut self, scalar: f64) -> &mut Self {
62        self.r = scalar;
63        self.g = scalar;
64        self.b = scalar;
65        self
66    }
67
68    /// `Color.setHex()`.
69    pub fn set_hex(&mut self, hex: u32, color_space: ColorSpace) -> &mut Self {
70        self.r = ((hex >> 16) & 255) as f64 / 255.0;
71        self.g = ((hex >> 8) & 255) as f64 / 255.0;
72        self.b = (hex & 255) as f64 / 255.0;
73
74        self.color_space_to_working(color_space)
75    }
76
77    /// `Color.setRGB()`.
78    pub fn set_rgb(&mut self, r: f64, g: f64, b: f64, color_space: ColorSpace) -> &mut Self {
79        self.r = r;
80        self.g = g;
81        self.b = b;
82
83        self.color_space_to_working(color_space)
84    }
85
86    /// `Color.setHSL()`. `h`, `s` and `l` are in 0..1.
87    pub fn set_hsl(&mut self, h: f64, s: f64, l: f64, color_space: ColorSpace) -> &mut Self {
88        let h = euclidean_modulo(h, 1.0);
89        let s = clamp(s, 0.0, 1.0);
90        let l = clamp(l, 0.0, 1.0);
91
92        if s == 0.0 {
93            self.r = l;
94            self.g = l;
95            self.b = l;
96        } else {
97            let p = if l <= 0.5 {
98                l * (1.0 + s)
99            } else {
100                l + s - (l * s)
101            };
102            let q = (2.0 * l) - p;
103
104            self.r = hue2rgb(q, p, h + 1.0 / 3.0);
105            self.g = hue2rgb(q, p, h);
106            self.b = hue2rgb(q, p, h - 1.0 / 3.0);
107        }
108
109        self.color_space_to_working(color_space)
110    }
111
112    /// `Color.copy()`.
113    pub fn copy(&mut self, color: &Self) -> &mut Self {
114        *self = *color;
115        self
116    }
117
118    /// `Color.copySRGBToLinear()`.
119    pub fn copy_srgb_to_linear(&mut self, color: &Self) -> &mut Self {
120        self.r = srgb_to_linear(color.r);
121        self.g = srgb_to_linear(color.g);
122        self.b = srgb_to_linear(color.b);
123        self
124    }
125
126    /// `Color.copyLinearToSRGB()`.
127    pub fn copy_linear_to_srgb(&mut self, color: &Self) -> &mut Self {
128        self.r = linear_to_srgb(color.r);
129        self.g = linear_to_srgb(color.g);
130        self.b = linear_to_srgb(color.b);
131        self
132    }
133
134    /// `Color.convertSRGBToLinear()`.
135    pub fn convert_srgb_to_linear(&mut self) -> &mut Self {
136        let c = *self;
137        self.copy_srgb_to_linear(&c)
138    }
139
140    /// `Color.convertLinearToSRGB()`.
141    pub fn convert_linear_to_srgb(&mut self) -> &mut Self {
142        let c = *self;
143        self.copy_linear_to_srgb(&c)
144    }
145
146    /// `Color.getHex()`.
147    pub fn get_hex(&self, color_space: ColorSpace) -> u32 {
148        let mut c = *self;
149        c.working_to_color_space(color_space);
150
151        (js_round(clamp(c.r * 255.0, 0.0, 255.0)) as u32) * 65536
152            + (js_round(clamp(c.g * 255.0, 0.0, 255.0)) as u32) * 256
153            + (js_round(clamp(c.b * 255.0, 0.0, 255.0)) as u32)
154    }
155
156    /// `Color.getHexString()`.
157    pub fn get_hex_string(&self, color_space: ColorSpace) -> String {
158        format!("{:06x}", self.get_hex(color_space))
159    }
160
161    /// `Color.getHSL()`.
162    pub fn get_hsl(&self, color_space: ColorSpace) -> Hsl {
163        let mut c = *self;
164        c.working_to_color_space(color_space);
165
166        let (r, g, b) = (c.r, c.g, c.b);
167
168        let max = js_max(js_max(r, g), b);
169        let min = js_min(js_min(r, g), b);
170
171        let hue;
172        let saturation;
173        let lightness = (min + max) / 2.0;
174
175        if min == max {
176            hue = 0.0;
177            saturation = 0.0;
178        } else {
179            let delta = max - min;
180
181            saturation = if lightness <= 0.5 {
182                delta / (max + min)
183            } else {
184                delta / (2.0 - max - min)
185            };
186
187            let h = if max == r {
188                (g - b) / delta + if g < b { 6.0 } else { 0.0 }
189            } else if max == g {
190                (b - r) / delta + 2.0
191            } else {
192                (r - g) / delta + 4.0
193            };
194
195            hue = h / 6.0;
196        }
197
198        Hsl {
199            h: hue,
200            s: saturation,
201            l: lightness,
202        }
203    }
204
205    /// `Color.getRGB()`.
206    pub fn get_rgb(&self, color_space: ColorSpace) -> Self {
207        let mut c = *self;
208        c.working_to_color_space(color_space);
209        c
210    }
211
212    /// `Color.getStyle()`, `SRGBColorSpace`.
213    pub fn get_style(&self) -> String {
214        let c = self.get_rgb(ColorSpace::Srgb);
215
216        format!(
217            "rgb({},{},{})",
218            js_round(c.r * 255.0),
219            js_round(c.g * 255.0),
220            js_round(c.b * 255.0)
221        )
222    }
223
224    /// `Color.offsetHSL()`.
225    pub fn offset_hsl(&mut self, h: f64, s: f64, l: f64) -> &mut Self {
226        let hsl = self.get_hsl(ColorSpace::LinearSrgb);
227        self.set_hsl(hsl.h + h, hsl.s + s, hsl.l + l, ColorSpace::LinearSrgb)
228    }
229
230    /// `Color.add()`.
231    pub fn add(&mut self, color: &Self) -> &mut Self {
232        self.r += color.r;
233        self.g += color.g;
234        self.b += color.b;
235        self
236    }
237
238    /// `Color.addColors()`.
239    pub fn add_colors(&mut self, color1: &Self, color2: &Self) -> &mut Self {
240        self.r = color1.r + color2.r;
241        self.g = color1.g + color2.g;
242        self.b = color1.b + color2.b;
243        self
244    }
245
246    /// `Color.addScalar()`.
247    pub fn add_scalar(&mut self, s: f64) -> &mut Self {
248        self.r += s;
249        self.g += s;
250        self.b += s;
251        self
252    }
253
254    /// `Color.sub()` — clamps at zero.
255    pub fn sub(&mut self, color: &Self) -> &mut Self {
256        self.r = js_max(0.0, self.r - color.r);
257        self.g = js_max(0.0, self.g - color.g);
258        self.b = js_max(0.0, self.b - color.b);
259        self
260    }
261
262    /// `Color.multiply()`.
263    pub fn multiply(&mut self, color: &Self) -> &mut Self {
264        self.r *= color.r;
265        self.g *= color.g;
266        self.b *= color.b;
267        self
268    }
269
270    /// `Color.multiplyScalar()`.
271    pub fn multiply_scalar(&mut self, s: f64) -> &mut Self {
272        self.r *= s;
273        self.g *= s;
274        self.b *= s;
275        self
276    }
277
278    /// `Color.lerp()`.
279    pub fn lerp(&mut self, color: &Self, alpha: f64) -> &mut Self {
280        self.r += (color.r - self.r) * alpha;
281        self.g += (color.g - self.g) * alpha;
282        self.b += (color.b - self.b) * alpha;
283        self
284    }
285
286    /// `Color.lerpColors()`.
287    pub fn lerp_colors(&mut self, color1: &Self, color2: &Self, alpha: f64) -> &mut Self {
288        self.r = color1.r + (color2.r - color1.r) * alpha;
289        self.g = color1.g + (color2.g - color1.g) * alpha;
290        self.b = color1.b + (color2.b - color1.b) * alpha;
291        self
292    }
293
294    /// `Color.lerpHSL()`.
295    pub fn lerp_hsl(&mut self, color: &Self, alpha: f64) -> &mut Self {
296        let a = self.get_hsl(ColorSpace::LinearSrgb);
297        let b = color.get_hsl(ColorSpace::LinearSrgb);
298
299        let h = lerp(a.h, b.h, alpha);
300        let s = lerp(a.s, b.s, alpha);
301        let l = lerp(a.l, b.l, alpha);
302
303        self.set_hsl(h, s, l, ColorSpace::LinearSrgb)
304    }
305
306    /// `Color.setFromVector3()`.
307    pub fn set_from_vector3(&mut self, v: &Vector3) -> &mut Self {
308        self.r = v.x;
309        self.g = v.y;
310        self.b = v.z;
311        self
312    }
313
314    /// `Color.applyMatrix3()`.
315    pub fn apply_matrix3(&mut self, m: &Matrix3) -> &mut Self {
316        let (r, g, b) = (self.r, self.g, self.b);
317        let e = &m.elements;
318
319        self.r = e[0] * r + e[3] * g + e[6] * b;
320        self.g = e[1] * r + e[4] * g + e[7] * b;
321        self.b = e[2] * r + e[5] * g + e[8] * b;
322
323        self
324    }
325
326    /// `Color.equals()`.
327    pub fn equals(&self, c: &Self) -> bool {
328        c.r == self.r && c.g == self.g && c.b == self.b
329    }
330
331    /// `Color.fromArray()`.
332    pub fn from_array(&mut self, array: &[f64], offset: usize) -> &mut Self {
333        self.r = array[offset];
334        self.g = array[offset + 1];
335        self.b = array[offset + 2];
336        self
337    }
338
339    /// `Color.toArray()`.
340    pub fn to_array(&self) -> [f64; 3] {
341        [self.r, self.g, self.b]
342    }
343
344    /// `ColorManagement.colorSpaceToWorking()`: the working space is
345    /// linear-sRGB, so only an sRGB source needs decoding.
346    fn color_space_to_working(&mut self, source: ColorSpace) -> &mut Self {
347        if source == ColorSpace::Srgb {
348            self.r = srgb_to_linear(self.r);
349            self.g = srgb_to_linear(self.g);
350            self.b = srgb_to_linear(self.b);
351        }
352        self
353    }
354
355    /// `ColorManagement.workingToColorSpace()`.
356    fn working_to_color_space(&mut self, target: ColorSpace) -> &mut Self {
357        if target == ColorSpace::Srgb {
358            self.r = linear_to_srgb(self.r);
359            self.g = linear_to_srgb(self.g);
360            self.b = linear_to_srgb(self.b);
361        }
362        self
363    }
364}
365
366/// `Color.js`' `hue2rgb()`.
367fn hue2rgb(p: f64, q: f64, t: f64) -> f64 {
368    let mut t = t;
369
370    if t < 0.0 {
371        t += 1.0;
372    }
373    if t > 1.0 {
374        t -= 1.0;
375    }
376
377    if t < 1.0 / 6.0 {
378        return p + (q - p) * 6.0 * t;
379    }
380    if t < 1.0 / 2.0 {
381        return q;
382    }
383    if t < 2.0 / 3.0 {
384        return p + (q - p) * 6.0 * (2.0 / 3.0 - t);
385    }
386
387    p
388}
389
390/// `ColorManagement.SRGBToLinear()`.
391pub(crate) fn srgb_to_linear(c: f64) -> f64 {
392    if c < 0.04045 {
393        c * 0.0773993808
394    } else {
395        (c * 0.9478672986 + 0.0521327014).powf(2.4)
396    }
397}
398
399/// `ColorManagement.LinearToSRGB()`.
400pub(crate) fn linear_to_srgb(c: f64) -> f64 {
401    if c < 0.0031308 {
402        c * 12.92
403    } else {
404        1.055 * c.powf(0.41666) - 0.055
405    }
406}