Source code
Revision control
Copy as Markdown
Other Tools
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
//! Gamut mapping - Raytrace algorithm.
use crate::color::{gamut::MIN_PRECISION, AbsoluteColor, ColorComponents, ColorSpace};
impl AbsoluteColor {
/// 13.2.5. The Ray Trace Gamut Mapping
pub fn gamut_map_raytrace(&self, dest_color_space: ColorSpace) -> Self {
macro_rules! in_range {
($l:expr, $c:expr, $h:expr) => {{
$c >= $l && $c <= $h
}};
}
const MIN_L: f32 = MIN_PRECISION;
const MAX_L: f32 = 1.0;
// Get the linear version of the destination color space;
// else, use the same space for the destination.
// NOTE that this will cause temporary approximations for wide-gamut
// RGB spaces beyond DisplayP3 (A98RGB, ProPhoto, and Rec2020) that
// currently don't have linear versions built-out for them.
// See comments/notes on [`ColorSpace::get_linear_color_space()`].
let dest_linear_color_space = dest_color_space
.get_linear_color_space()
.unwrap_or(dest_color_space);
// 1. if destination has no gamut limits (XYZ-D65, XYZ-D50, Lab, LCH,
// Oklab, OkLCh) convert origin to destination and return it as the
// gamut mapped color
if matches!(
dest_color_space,
ColorSpace::Lab
| ColorSpace::Lch
| ColorSpace::Oklab
| ColorSpace::Oklch
| ColorSpace::XyzD50
| ColorSpace::XyzD65
) {
return self.to_color_space(dest_color_space);
}
// 2. let `origin_OkLCh` be `origin` converted from `origin color
// space` to the OkLCh color space
let origin_oklch = self.to_color_space(ColorSpace::Oklch);
// 3. if the Lightness of `origin_OkLCh` is greater than or equal to
// 100%, convert `oklab(1 0 0 / origin.alpha)` to `destination` and
// return it as the gamut mapped color
if origin_oklch.components.0 >= MAX_L {
return AbsoluteColor::new(ColorSpace::Oklab, 1.0, 0.0, 0.0, self.alpha)
.to_color_space(dest_color_space);
}
// 4. if the Lightness of `origin_OkLCh` is less than than or equal to
// 0%, convert `oklab(0 0 0 / origin.alpha)` to `destination` and
// return it as the gamut mapped color
if origin_oklch.components.0 <= MIN_L {
return AbsoluteColor::new(ColorSpace::Oklab, 0.0, 0.0, 0.0, self.alpha)
.to_color_space(dest_color_space);
}
// 5. let `l_origin` be the OkLCh lightness component of `origin_OkLCh`
// 6. let `h_origin` be the OkLCh hue component of `origin_OkLCh`
let ColorComponents(l_origin, _, h_origin) = origin_oklch.components;
// 7. let `anchor` be an achromatic OkLCh color formed with `l_origin`
// as lightness, 0 as chroma, and `h_origin` as hue, converted to
// the linear-light form of destination
let mut anchor = AbsoluteColor::new(ColorSpace::Oklch, l_origin, 0.0, h_origin, self.alpha)
.to_color_space(dest_linear_color_space);
// 8. let `origin_rgb` be `origin_OkLCh` converted to the linear-light
// form of destination
let mut origin_rgb = origin_oklch.to_color_space(dest_linear_color_space);
// 9. if origin_rgb is not in gamut
if !origin_rgb.in_gamut() {
// 9.1. let `low` be 1E-6 [^1]
const LOW: f32 = 1.0e-6;
// 9.2 let `high` be 1.0 - `low` [^2]
const HIGH: f32 = 1.0 - LOW;
// 9.3 let `last` be `origin_rgb`
let mut last = origin_rgb;
// We're doing 4 cycles of ray tracing.
// 9.4 `for (i=0; i<4; i++)`:
for i in 0..4 {
// 9.4.1. if (`i > 0`)
if i > 0 {
// 9.4.1.1. let `current_OkLCh` be `origin_rgb` converted to OkLCh
let mut current_oklch = origin_rgb.to_color_space(ColorSpace::Oklch);
// 9.4.1.2. let the lightness of `current_OkLCh` be `l_origin`
current_oklch.components.0 = l_origin;
// 9.4.1.3. let the hue of `current_OkLCh` be `h_origin` [^3]
current_oklch.components.2 = h_origin;
// 9.4.1.4. let `origin_rgb` be `current_OkLCh` converted to the
// linear-light form of destination
origin_rgb = current_oklch.to_color_space(dest_linear_color_space);
}
// 9.4.2. **Cast a ray** from `anchor` to `origin_rgb` and let
// `intersection` be the intersection of this ray with the
// gamut boundary
let intersection = Self::cast_ray(&anchor.components, &origin_rgb.components);
// 9.4.3. if an intersection was not found, let `origin_rgb` be
// `last` and exit the loop [^5]
let Some(intersection) = intersection else {
origin_rgb = last;
break;
};
// 9.4.4. if (`i > 0`) AND (each component of `origin_rgb` is
// between `low` and `high`) then let `anchor` be
// `origin_rgb` [^4]
if (i > 0)
&& in_range!(LOW, origin_rgb.components.0, HIGH)
&& in_range!(LOW, origin_rgb.components.1, HIGH)
&& in_range!(LOW, origin_rgb.components.2, HIGH)
{
anchor = origin_rgb;
}
// 9.4.5. let `origin_rgb` be `intersection`
origin_rgb.components = intersection;
// 9.4.6. let `last` be `intersection`
last.components = intersection;
}
}
// 10. let clip(color) be a function which converts color to
// destination, clamps each component to the bounds of the
// reference range for that component, and returns the result
// See [`Self::clip`] and [`Self::clip_to_dest_space`].
// NOTE: in the 2026-02-27 draft, this line doesn't make sense.
// I've posted a question/issue to the CSS Color 4 team about it.
// Isaac (@facelessuser) replied that it is ambiguous, but ATOW this hasn't
// been fixed in the working copy pseudo-code.
// 11. set clipped to clip(current)
//
// In the meantime, this was the logic from the 2026-02-02 draft that worked:
// 13. let `clipped` be `origin_rgb` clipped to gamut (components in
// the range 0 to 1), thus trimming off any noise due to floating
// point inaccuracy
let clipped = origin_rgb.clip_to_dest_space(dest_color_space);
// 12. return `clipped` as the gamut mapped color
clipped
}
/// To **cast a ray** through a linear-light RGB space from `start` to
/// `end` (in gamut mapping, `start` is an anchor within the RGB gamut and
/// `end` is the gamut mapped color, on the cubical gamut surface)
fn cast_ray(start: &ColorComponents, end: &ColorComponents) -> Option<ColorComponents> {
const MAGIC_EPSILON: f32 = 1.0e-12;
// 1. let `bmin` and `bmax` be 3-element arrays with the gamut’s lower
// and upper bounds, respectively [^6]
// NOTE: assuming these are always tied to RGB bounds [0.0, 1.0]
let bmin = [0.0, 0.0, 0.0];
let bmax = [1.0, 1.0, 1.0];
// 2. let `tfar` be `infinity` (or some very large number)
let mut tfar = std::f32::INFINITY;
// 3. let `tnear` be `-infinity` (or some very large, negative number)
let mut tnear = std::f32::NEG_INFINITY;
// 4. let `direction` be a 3-element array
let mut direction = [0.0, 0.0, 0.0];
// reshape start and end so we can iterate over them
let start_array = start.to_array();
let end_array = end.to_array();
// 5. `for (i = 0; i < 3; i++)`:
for i in 0..3 {
// 5.1. let `a` be `start[i]`
let a = start_array[i];
// 5.2. let `b` be `end[i]`
let b = end_array[i];
// 5.3. let `d` be `b - a`
let d = b - a;
// 5.4. let `direction[i]` be `d`
direction[i] = d;
// 5.5. if abs(d) > MAGIC_EPSILON:
// NOTE the 2026-02-27 spec is incorrect; it uses less-than -- should be greater-than.
// Reference impls colorjs.io and ColorAide both use greater-than.
// Issue reported to CSS Color 4 team; yet to be fixed in working draft ATOW.
if d.abs() > MAGIC_EPSILON {
// 5.5.1. let `inv_d` be `1 / d`
let inv_d = 1.0 / d;
// 5.5.2. let `t1` be `(bmin[i] - a) * inv_d`
let t1 = (bmin[i] - a) * inv_d;
// 5.5.3. let `t2` be `(bmax[i] - a) * inv_d`
let t2 = (bmax[i] - a) * inv_d;
// 5.5.4. let `tnear` be `max(min(t1, t2), tnear)`
tnear = t1.min(t2).max(tnear);
// 5.5.5. let `tfar` be `min(max(t1, t2), tfar)`
tfar = t1.max(t2).min(tfar);
}
// 5.6. else if (`a < bmin[i]` or `a > bmax[i]`)
// * return `INTERSECTION NOT FOUND`
else if a < bmin[i] || a > bmax[i] {
return None;
}
}
// 6. if (`tnear > tfar` or `tfar < 0`)
// * return `INTERSECTION NOT FOUND`
if (tnear > tfar) || (tfar < 0.0) {
return None;
}
// 7. if `tnear < 0`
// * let `tnear` be `tfar` [^7]
if tnear < 0.0 {
tnear = tfar;
}
// 8. if tnear is infinite (or matches the initial very large value)
// * return `INTERSECTION NOT FOUND`
if tnear.is_infinite() {
return None;
}
let mut result = [0.0, 0.0, 0.0];
// 9. for (`i = 0; i < 3; i++`):
// * let `result[i]` be `start[i] + direction[i] * tnear`
for i in 0..3 {
result[i] = start_array[i] + direction[i] * tnear;
}
// 10. return `result`
Some(ColorComponents(result[0], result[1], result[2]))
}
}