Overhaul color scaling and add a gamut mapping method that performs it (#505)

- New gamut mapping method called scale added that scales a color into
  gamut while preserving lower end luminance and relative, dominant
  wavelength, with options to clip instead of trying to preserve the
  dominant wavelength, and an option to abandon luminance preserving.
- blackbody(), from_wavelength(), and chromaticity() all use new scaling
  logic to perform color scale fitting.
- Refactor temperature plugins to let the Color object scale the colors
  and focus on just calculating the chromaticity points.
- Extend wavelength functions' allowed wavelength range.

Author: facelessuser

coloraide/__meta__.py

@@ -204,5 +204,5 @@ def parse_version(ver: str) -> Version:
     return Version(major, minor, micro, release, pre, post, dev)
 
 
-__version_info__ = Version(8, 3, 0, "final")
+__version_info__ = Version(8, 4, 0, "final")
 __version__ = __version_info__._get_canonical()

coloraide/algebra.py

@@ -1200,11 +1200,10 @@ def ray_line_intersect(
     if abs(denom) < abs_tol:  # pragma: no cover
         return None
     t = dot(dap, dp, dims=D1) / denom
-    # Intersect
-    i = add(b1, multiply(t, db, dims=SC_D1), dims=D1)
     # Check if intersection is within bounds
     if 0 <= t <= 1:
-        return i
+        # Intersect
+        return add(b1, multiply(t, db, dims=SC_D1), dims=D1)
     return None  # pragma: no cover
 
 

coloraide/color.py

@@ -25,7 +25,7 @@
 from itertools import zip_longest as zipl
 from .css import parse
 from .types import VectorLike, Vector, ColorInput
-from .spaces import Space, RGBish
+from .spaces import Space
 from .spaces.hsv import HSV
 from .spaces.srgb.css import sRGB
 from .spaces.srgb_linear import sRGBLinear
@@ -69,6 +69,7 @@
 from .gamut.fit_lch_chroma import LChChroma
 from .gamut.fit_oklch_chroma import OkLChChroma
 from .gamut.fit_raytrace import RayTrace
+from .gamut.fit_scale import Scale
 from .cat import CAT, Bradford
 from .filters import Filter
 from .filters.w3c_filter_effects import Sepia, Brightness, Contrast, Saturate, Opacity, HueRotate, Grayscale, Invert
@@ -523,9 +524,11 @@ def blackbody(
         temp: float,
         duv: float = 0.0,
         *,
+        method: str | None = None,
         scale: bool = True,
         scale_space: str | None = None,
-        method: str | None = None,
+        max_saturation: bool = True,
+        clip_negative: bool = False,
         **kwargs: Any
     ) -> Self:
         """
@@ -542,8 +545,16 @@ def blackbody(
         """
 
         cct = temperature.cct(method, cls)
-        color = cct.from_cct(cls, space, temp, duv, scale, scale_space, **kwargs)
-        return color
+        uv, name = cct.from_cct(temp, duv, **kwargs)
+        return cls.chromaticity(
+            space,
+            uv,
+            name,
+            scale=scale,
+            scale_space=scale_space,
+            max_saturation=max_saturation,
+            clip_negative=clip_negative
+        )
 
     def cct(self, *, method: str | None = None, **kwargs: Any) -> Vector:
         """Get color temperature."""
@@ -829,9 +840,11 @@ def chromaticity(
         coords: VectorLike,
         cspace: str = 'uv-1976',
         *,
+        white: VectorLike | None = None,
         scale: bool = False,
         scale_space: str | None = None,
-        white: VectorLike | None = None
+        max_saturation: bool = False,
+        clip_negative: bool = False
     ) -> Self:
         """
         Create a color from chromaticity coordinates.
@@ -847,9 +860,6 @@ def chromaticity(
         limitations. Default linear RGB space is linear sRGB.
         """
 
-        if scale_space is None:
-            scale_space = 'srgb-linear'
-
         # Use the white point of the target color space unless a white point is given.
         if white is None:
             white = cls.CS_MAP[space].WHITE
@@ -867,9 +877,13 @@ def chromaticity(
         )
 
         # Normalize in the given RGB color space (ideally linear).
-        if scale and isinstance(cls.CS_MAP[scale_space], RGBish):
-            color.convert(scale_space, in_place=True)
-            color[:-1] = util.rgb_scale(color.coords())
+        if scale:
+            gamut.scale_rgb(
+                color,
+                scale_space=scale_space if scale_space is not None else 'srgb-linear',
+                max_saturation=max_saturation,
+                clip_negative=clip_negative
+            )
 
         # Convert to targeted color space
         if space != color.space():
@@ -879,7 +893,8 @@ def chromaticity(
 
     @classmethod
     def convert_chromaticity(
-        cls, cspace1: str,
+        cls,
+        cspace1: str,
         cspace2: str,
         coords: VectorLike,
         *,
@@ -1353,7 +1368,7 @@ def wavelength(
 
         return spectrum.closest_wavelength(
             self.xy(),
-            white or util.xyz_to_xyY(self.white())[:-1],
+            white or self._space.WHITE,
             reverse=complementary
         )
 
@@ -1363,13 +1378,24 @@ def from_wavelength(
         space: str,
         wavelength: float,
         *,
+        white: VectorLike | None = None,
         scale: bool = True,
-        scale_space: str | None = None
+        scale_space: str | None = None,
+        max_saturation: bool = True,
+        clip_negative: bool = False
     ) -> Self:
         """Create a color from a wavelength."""
 
-        xyY = util.xyz_to_xyY(spectrum.wavelength_to_color(wavelength))
-        return cls.chromaticity(space, xyY, 'xy-1931', scale=scale, scale_space=scale_space)
+        return cls.chromaticity(
+            space,
+            util.xyz_to_xyY(spectrum.wavelength_to_color(wavelength)),
+            'xy-1931',
+            white=white,
+            scale=scale,
+            scale_space=scale_space,
+            max_saturation=max_saturation,
+            clip_negative=clip_negative
+        )
 
     @overload
     def get(self,
@@ -1618,6 +1644,7 @@ def alpha(
         LChChroma(),
         OkLChChroma(),
         RayTrace(),
+        Scale(),
 
         # Filters
         Sepia(),

coloraide/gamut/__init__.py

@@ -1,17 +1,25 @@
 """Gamut handling."""
 from __future__ import annotations
 import math
-from ..channels import FLG_ANGLE
 from abc import ABCMeta, abstractmethod
-from ..types import Plugin
-from typing import Any, TYPE_CHECKING, Callable  # noqa: F401
+from functools import lru_cache
 from . import pointer
 from . import visible_spectrum
+from .. import util
+from .. import algebra as alg
+from ..channels import FLG_ANGLE
+from ..types import Plugin, Vector, VectorLike
+from ..spaces import Prism, Luminant, Space, HSLish, HSVish, HWBish
+from ..spaces.hsl import hsl_to_srgb, srgb_to_hsl
+from ..spaces.hsv import hsv_to_srgb, srgb_to_hsv
+from ..spaces.hwb import hwb_to_hsv, hsv_to_hwb
+from ..spaces.srgb_linear import sRGBLinear
+from typing import Any, TYPE_CHECKING, Callable  # noqa: F401
 
 if TYPE_CHECKING:  #pragma: no cover
     from ..color import Color
 
-__all__ = ('clip_channels', 'verify', 'Fit', 'pointer', 'visible_spectrum')
+__all__ = ('clip_channels', 'verify', 'Fit', 'pointer', 'visible_spectrum', 'scale_rgb', 'coerce_to_rgb')
 
 SPECIAL_GAMUTS = {
     'pointer-gamut': {
@@ -25,6 +33,154 @@
 }   # type: dict[str, dict[str, Callable[..., Any]]]
 
 
+def hwb_to_srgb(coords: Vector) -> Vector:  # pragma: no cover
+    """Convert HWB to sRGB."""
+
+    return hsv_to_srgb(hwb_to_hsv(coords))
+
+
+def srgb_to_hwb(coords: Vector) -> Vector:  # pragma: no cover
+    """Convert sRGB to HWB."""
+
+    return hsv_to_hwb(srgb_to_hsv(coords))
+
+
+@lru_cache(maxsize=20, typed=True)
+def coerce_to_rgb(cs: Space) -> Space:
+    """
+    Coerce an HSL, HSV, or HWB color space to RGB to allow us to ray trace the gamut.
+
+    It is rare to have a color space that is bound to an RGB gamut that does not exist as an RGB
+    defined RGB space. HPLuv is one that is defined only as a cylindrical, HSL-like space. Okhsl
+    and Okhsv are another whose gamut is meant to target sRGB, but it is very fuzzy and has sRGB
+    colors not quite in gamut, and others that exceed the sRGB gamut.
+
+    For gamut mapping, RGB cylindrical spaces can be coerced into an RGB form using traditional
+    HSL, HSV, or HWB approaches which is good enough.
+    """
+
+    if isinstance(cs, HSLish):
+        to_ = hsl_to_srgb  # type: Callable[[Vector], Vector]
+        from_ = srgb_to_hsl  # type: Callable[[Vector], Vector]
+    elif isinstance(cs, HSVish):
+        to_ = hsv_to_srgb
+        from_ = srgb_to_hsv
+    elif isinstance(cs, HWBish):  # pragma: no cover
+        to_ = hwb_to_srgb
+        from_ = srgb_to_hwb
+    else:  # pragma: no cover
+        raise ValueError(f'Cannot coerce {cs.NAME} to an RGB space.')
+
+    class RGB(sRGBLinear):
+        """Custom RGB class."""
+
+        NAME = f'-rgb-{cs.NAME}'
+        BASE = cs.NAME
+        GAMUT_CHECK = None
+        CLIP_SPACE = None
+        WHITE = cs.WHITE
+        DYAMIC_RANGE = cs.DYNAMIC_RANGE
+        INDEXES = cs.indexes()
+        # Scale saturation and lightness (or HWB whiteness and blackness)
+        SCALE_SAT = cs.channels[INDEXES[1]].high
+        SCALE_LIGHT = cs.channels[INDEXES[2]].high
+
+        def to_base(self, coords: Vector) -> Vector:
+            """Convert from RGB to HSL."""
+
+            coords = from_(coords)
+            if self.SCALE_SAT != 1:
+                coords[1] *= self.SCALE_SAT
+            if self.SCALE_LIGHT != 1:
+                coords[2] *= self.SCALE_LIGHT
+            ordered = [0.0, 0.0, 0.0]
+            for e, c in enumerate(coords):
+                ordered[self.INDEXES[e]] = c
+            return ordered
+
+        def from_base(self, coords: Vector) -> Vector:
+            """Convert from HSL to RGB."""
+
+            coords = [coords[i] for i in self.INDEXES]
+            if self.SCALE_SAT != 1:
+                coords[1] /= self.SCALE_SAT
+            if self.SCALE_LIGHT != 1:
+                coords[2] /= self.SCALE_LIGHT
+            coords = to_(coords)
+            return coords
+
+    return RGB()
+
+
+def adjust_luminance(color: Color, Y: float, white: VectorLike) -> None:
+    """Adjust luminance of a color."""
+
+    with color.within('xyz-d65') as c:
+        c.convert('xyz-d65', in_place=True)
+        d65 = c._space.WHITE
+        adapt = d65 != white
+        xyz = c.chromatic_adaptation(d65, white, c[:-1]) if adapt else c[:-1]
+        if xyz[1] > Y:
+            xyz = util.xy_to_xyz(util.xyz_to_xyY(xyz, white)[:-1], Y)
+            c[:-1] = c.chromatic_adaptation(white, d65, xyz) if adapt else xyz
+
+
+def scale_rgb(
+    color: Color,
+    *,
+    scale_space: str,
+    clip_negative: bool = False,
+    max_saturation: bool = False
+) -> None:
+    """Apply color scaling."""
+
+    cs = color.CS_MAP[scale_space]
+    orig_space = scale_space
+
+    # Requires an RGB-ish or Prism space, preferably a linear space.
+    # Coerce RGB cylinders with no defined RGB space to RGB
+    coerced = False
+    if not isinstance(cs, Prism) or isinstance(cs, Luminant):
+        coerced = True
+        cs = coerce_to_rgb(cs)
+
+    # If there is a linear version of the RGB space, results will be better if we use that.
+    maximum = cs.channels[0].high
+    linear = cs.linear()
+    if linear and linear in color.CS_MAP:
+        subtractive = cs.SUBTRACTIVE
+        cs = color.CS_MAP[linear]
+        if subtractive != cs.SUBTRACTIVE:
+            maximum = color.new(scale_space, [cs.CHANNELS[0].low] * 3).convert(linear, in_place=True)[0]
+        else:
+            maximum = color.new(scale_space, [maximum] * 3).convert(linear, in_place=True)[0]
+        scale_space = linear
+
+    # Convert to the target gamut
+    mapcolor = color.convert(scale_space).normalize(nans=False)
+
+    # Grab the white point and the luminance of the current gamut.
+    white = mapcolor._space.WHITE
+    Y = mapcolor.luminance()
+
+    # Scale the color into gamut
+    rgb = cs.from_base(mapcolor[:-1]) if coerced else mapcolor[:-1]
+    mn = min(min(rgb), 0.0) if not clip_negative else 0.0
+    mx = max(rgb) - mn
+    for i in range(len(rgb)):
+        rgb[i] = alg.clamp((rgb[i] - mn) / mx if mx else (rgb[i] - mn), 0.0, 1.0) * maximum
+    mapcolor[:-1] = cs.to_base(rgb) if coerced else rgb
+
+    # If the current luminance is greater than the original luminance,
+    # set the luminance to the original. Set it xyY with the same white point.
+    if not max_saturation:
+        adjust_luminance(mapcolor, Y, white)
+
+    # Clip in the original gamut bound color space and update the original color
+    clip_channels(mapcolor.convert(orig_space, in_place=True))
+    color.update(mapcolor)
+
+
 def clip_channels(color: Color, nans: bool = True) -> bool:
     """Clip channels."""