@texel/color 1.0.2 → 1.0.4

package/README.md

@@ -93,9 +93,7 @@ import { gamutMapOKLCH, sRGBGamut, sRGBLinear, OKLCH } from "@texel/color";
 // gamut map to sRGB but return linear sRGB
 const lrgb = gamutMapOKLCH(oklch, sRGBGamut, sRGBLinear);
 
-// or gamut map to sRGB but return OKLCH
-// note, when finally converting this back to sRGB you will likely
-// want to clip the result to 0..1 bounds due to floating point loss
+// or gamut map to sRGB but return OKLCH (does not perform RGB clip)
 const lch = gamutMapOKLCH(oklch, sRGBGamut, OKLCH);
 ```
 
@@ -118,6 +116,8 @@ gamutMapOKLCH(oklch, sRGBGamut, sRGB, rgb, MapToL);
 
 The `cusp` can also be passed as the last parameter, allowing for faster evaluation for known hues. See below for calculating the cusp.
 
+> :Note: If you output to an OKLab-based target (OKLCH, OKHSL etc), the final step of RGB clipping will be skipped. This produces more predictable OKLab and OKLCH based results, but you will likely want to perform a final clampedRGB() step when converting to a displayable color.
+
 #### `LC = findCuspOKLCH(a, b, gamut, out = [0, 0])`
 
 Finds the 'cusp' of a given OKLab hue plane (denoted with normalized `a` and `b` values in OKLab space), returning the `[L, C]` (lightness and chroma). This is useful for pre-computing aspects of gamut mapping when you are working across a known hue:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texel/color",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "a minimal and modern color library",
   "type": "module",
   "main": "./src/index.js",

package/src/gamut.js

@@ -288,8 +288,19 @@ export const gamutMapOKLCH = (
   // convert oklch to base gamut space (i.e. linear sRGB)
   convert(out, OKLCH, gamutSpaceBase, rgbVec);
 
+  // Note: this is a possible area of performance improvement for some edge cases
+  // If you gamut map without clipping, you end up lying on the edge of the gamut,
+  // but in some cases very slightly out of gamut. Gamut mapping *again* is redundant
+  // as it will produce the same result; and in those cases, it should just skip straight
+  // to clipping. So, in theory, a small epsilon like 1e-7 would catch these and prevent redundant gamut mapping.
+  // See test/check-gamut-epsilon.js
+  // However, in practice, inputs to this function are likely not going to be already-mapped-but-not-clipped points,
+  // so we are talking about a very negligible improvement, and it is probably better to be accurate in as many cases
+  // as possible than to shave off a little time.
+  const RGB_CLIP_EPSILON = 0;
+
   // check where the point lies in gamut space
-  if (!isRGBInGamut(rgbVec, 0)) {
+  if (!isRGBInGamut(rgbVec, RGB_CLIP_EPSILON)) {
     // we aren't in gamut, so let's map toward it
     const L = out[0];
     const C = out[1];
@@ -314,17 +325,20 @@ export const gamutMapOKLCH = (
     out[0] = lerp(LTarget, L, t);
     out[1] *= t;
 
-    // special case: if requested targetSpace is base=OKLCH, we can return early.
-    // note this creates a potential difference compared to other targetSpaces, which
-    // will be clipped in RGB before converting to the target space.
-    // however, due to floating point arithmetic, a user doing OKLCH -> RGB will still
-    // need to clip the result again anyways, so perhaps this difference is negligible.
-    const targetSpaceBase = targetSpace.base ?? targetSpaceBase;
+    // Note: if requested targetSpace is base=OKLCH, we can return early.
+    // note this creates a potential difference compared to going to other targetSpaces:
+    // a) mapping to sRGB then finally converting back to OKLCH the result may be lossy in
+    //    some coordinates that you might not expect, e.g. hue loss when hue should be unchanged
+    //    during gamut mapping, due to conversion / floating point math
+    // b) if you map to sRGB it will perform clipping, but if you map to OKLCH then no sRGB clipping
+    //    will be applied. The OKLCH result is _basically_ in gamut, but not exactly; you'll need to clip at final stage.
+    // I've documented this behaviour in the readme.
+    const targetSpaceBase = targetSpace.base ?? targetSpace;
     if (targetSpaceBase == OKLab) {
       return convert(out, OKLCH, targetSpace, out);
     }
 
-    // now that we have a LCH that sits on the gamut, convert again to linear space
+    // now that we have a LCH that sits on (or nearly on) the gamut, convert again to linear space
     convert(out, OKLCH, gamutSpaceBase, rgbVec);
   }
   // clip the linear RGB to 0..1 range

package/test/bench-culori.js

@@ -19,6 +19,8 @@ import {
 import { p3, toGamut, oklch, okhsl, converter } from "culori";
 
 const N = 256 * 256;
+const gamut = DisplayP3Gamut;
+const target = gamut.space;
 
 // get N OKLCH in-gamut pixels by sampling uniformly from OKHSL cube
 const oklchPixelsInGamut = Array(N)
@@ -27,8 +29,8 @@ const oklchPixelsInGamut = Array(N)
     const t = i / (lst.length - 1);
     // note if we use the standard OKHSL space, it is bound to sRGB gamut...
     // so instead we use the OKHSLToOKLab function and pass P3 gamut
-    const okhsl = [t, t, t * 360];
-    const oklab = OKHSLToOKLab(okhsl, DisplayP3Gamut);
+    const okhsl = [t * 360, t, t];
+    const oklab = OKHSLToOKLab(okhsl, gamut);
     return convert(oklab, OKLab, OKLCH);
   });
 
@@ -44,12 +46,34 @@ const toP3Gamut = toGamut("p3", "oklch");
 // same perf as p3() it seems
 // const p3Converter = converter("p3");
 
-test(oklchPixelsInGamut, "Random Samling in P3 Gamut");
-test(oklchPixelsRandom, "Random Samling in OKLab L Planes");
+test(oklchPixelsInGamut, "Random Sampling in P3 Gamut");
+test(oklchPixelsRandom, "Random Sampling in OKLab L Planes");
+test(oklchPixelsRandom, "Random Sampling in OKLab L Planes", true);
+
+function test(inputPixelsOKLCH, label, fixedCusp) {
+  let cuspMap;
+  if (fixedCusp) {
+    cuspMap = new Array(360).fill(null);
+    inputPixelsOKLCH = inputPixelsOKLCH.map((oklch) => {
+      const H = constrainAngle(Math.round(oklch[2]));
+      oklch = oklch.slice();
+      oklch[2] = H;
+      if (!cuspMap[H]) {
+        const Hr = degToRad(H);
+        const a = Math.cos(Hr);
+        const b = Math.sin(Hr);
+        cuspMap[H] = findCuspOKLCH(a, b, gamut);
+      }
+      return oklch;
+    });
+  }
 
-function test(inputPixelsOKLCH, label) {
-  console.log("Testing with input type: %s", label);
-  const culoriInputsOKLCH = oklchPixelsRandom.map(([l, c, h]) => {
+  console.log(
+    "Testing with input type: %s%s",
+    label,
+    fixedCusp ? " (Fixed Cusp)" : ""
+  );
+  const culoriInputsOKLCH = inputPixelsOKLCH.map(([l, c, h]) => {
     return {
       mode: "oklch",
       l,
@@ -66,7 +90,7 @@ function test(inputPixelsOKLCH, label) {
   tmp = [0, 0, 0];
   now = performance.now();
   for (let oklch of inputPixelsOKLCH) {
-    convert(oklch, OKLCH, DisplayP3, tmp);
+    convert(oklch, OKLCH, target, tmp);
   }
   elapsedOurs = performance.now() - now;
 
@@ -74,7 +98,7 @@ function test(inputPixelsOKLCH, label) {
   for (let oklchColor of culoriInputsOKLCH) {
     p3(oklchColor);
 
-    // same perf
+    // same perf ?
     // p3Converter(oklchColor);
   }
   elapsedCulori = performance.now() - now;
@@ -83,11 +107,20 @@ function test(inputPixelsOKLCH, label) {
   //// gamut
 
   tmp = [0, 0, 0];
-  now = performance.now();
-  for (let oklch of inputPixelsOKLCH) {
-    gamutMapOKLCH(oklch, DisplayP3Gamut, DisplayP3, tmp);
+  if (fixedCusp && cuspMap) {
+    now = performance.now();
+    for (let oklch of inputPixelsOKLCH) {
+      const cusp = cuspMap[oklch[2]];
+      gamutMapOKLCH(oklch, gamut, target, tmp, undefined, cusp);
+    }
+    elapsedOurs = performance.now() - now;
+  } else {
+    now = performance.now();
+    for (let oklch of inputPixelsOKLCH) {
+      gamutMapOKLCH(oklch, gamut, target, tmp);
+    }
+    elapsedOurs = performance.now() - now;
   }
-  elapsedOurs = performance.now() - now;
 
   now = performance.now();
   for (let oklchColor of culoriInputsOKLCH) {

package/test/canvas-graph.js

@@ -13,12 +13,13 @@ import {
   constrainAngle,
   floatToByte,
   isRGBInGamut,
+  clampedRGB,
 } from "../src/index.js";
 import arrayAlmostEqual from "./almost-equal.js";
 
 const settings = {
   dimensions: [768, 768],
-  animate: true,
+  animate: false,
   playbackRate: "throttle",
   fps: 2,
   attributes: {
@@ -34,7 +35,8 @@ const sketch = ({ width, height }) => {
 
     context.fillStyle = "gray";
     context.fillRect(0, 0, width, height);
-    const H = constrainAngle((frame * 45) / 2);
+    const H = 264.1;
+    // const H = constrainAngle((frame * 45) / 2);
 
     // console.time("map");
     // console.profile("map");
@@ -123,7 +125,7 @@ const sketch = ({ width, height }) => {
         context.lineTo(...LCtoXY(mapped));
         context.stroke();
         context.globalAlpha = 1;
-        drawLCPoint(context, mapped.slice(0, 2), radius, "white");
+        drawLCPoint(context, mapped.slice(0, 2), radius / 4, "white");
       } else {
         drawLCPoint(context, lc, radius);
       }

package/test/check-gamut-epsilon.js

@@ -0,0 +1,136 @@
+// When gamut mapping with OKLCH approximation,
+// the resulting points do not always lie exactly in gamut.
+// The same may be true of OKHSL to RGB spaces.
+// Let's figure out how far away they are:
+// if a given point is under this threshold, gamut mapping
+// will be redundant as it will just produce the same epsilon.
+// This value is used in gamut.js as the RGB_CLIP_EPSILON
+
+import {
+  clampedRGB,
+  convert,
+  degToRad,
+  findCuspOKLCH,
+  findGamutIntersectionOKLCH,
+  gamutMapOKLCH,
+  isRGBInGamut,
+  lerp,
+  MapToCuspL,
+  OKLCH,
+  sRGB,
+  sRGBGamut,
+  sRGBLinear,
+} from "../src/index.js";
+
+const gamut = sRGBGamut;
+const target = gamut.space.base; // linear form
+
+// slice the plane into a square
+const slices = 100;
+let avgDelta = 0;
+let avgCount = 0;
+let minDelta = Infinity;
+let maxDelta = -Infinity;
+
+// a very small number which still catches many gamut-mapped points
+// but produces very little difference in practical and visual results
+const RGB_CLIP_EPSILON = 0.0000001;
+let totalPointsOutOfGamut = 0;
+let totalPointsUnderEpsilon = 0;
+let totalPointsUnderEpsilonBeforeMapping = 0;
+
+// this particular hue is a little funky
+// https://github.com/color-js/color.js/issues/81
+// it produces out of gamut sRGB, however, the oklab gamut approximation seems to handle it fine
+const hue = 264.1;
+const lightness = 0.4;
+for (let chroma = 0.22; chroma < 0.285; chroma += 0.001) {
+  const oklch = [lightness, chroma, hue];
+  const rgb = convert(oklch, OKLCH, sRGBLinear);
+  if (!isRGBInGamut(rgb, 0)) {
+    const mappedOKLCH = gamutMapWithoutClipOKLCH(oklch);
+    const mappedRGB = convert(mappedOKLCH, OKLCH, sRGBLinear);
+    const delta = clipDelta(mappedRGB);
+    if (!delta.every((n) => n == 0)) console.log("hue", hue, "delta", delta);
+  }
+}
+
+// test all hue planes Nº difference apart
+// we will see some gamut mapped points still do not lie exactly in gamut
+for (let H = 0; H < 360; H += 0.5) {
+  for (let y = 0; y < slices; y++) {
+    for (let x = 0; x < slices; x++) {
+      const u = x / (slices - 1);
+      const v = y / (slices - 1);
+      const L = 1 - v;
+      const C = u * 0.4;
+
+      // try conversion
+      let rgbl = convert([L, C, H], OKLCH, target);
+
+      // not exactly in space
+      if (!isRGBInGamut(rgbl, 0)) {
+        // check epsilons
+        if (isRGBInGamut(rgbl, RGB_CLIP_EPSILON)) {
+          totalPointsUnderEpsilonBeforeMapping++;
+        }
+
+        const oklch = gamutMapWithoutClipOKLCH([L, C, H]);
+        rgbl = convert(oklch, OKLCH, target);
+
+        const [dr, dg, db] = clipDelta(rgbl);
+        const avg = (dr + dg + db) / 3;
+        const min = Math.min(dr, dg, db);
+        const max = Math.max(dr, dg, db);
+        avgDelta += avg;
+        avgCount++;
+        minDelta = Math.min(min, minDelta);
+        maxDelta = Math.max(max, maxDelta);
+
+        totalPointsOutOfGamut++;
+        if (isRGBInGamut(rgbl, RGB_CLIP_EPSILON)) {
+          totalPointsUnderEpsilon++;
+        }
+      }
+    }
+  }
+}
+
+function clipDelta(rgb) {
+  const clipped = clampedRGB(rgb);
+  const dr = Math.abs(rgb[0] - clipped[0]);
+  const dg = Math.abs(rgb[1] - clipped[1]);
+  const db = Math.abs(rgb[2] - clipped[2]);
+  return [dr, dg, db];
+}
+
+function gamutMapWithoutClipOKLCH(oklch) {
+  const [L, C, H] = oklch;
+  // we aren't in gamut, so let's map toward it
+  const hueAngle = degToRad(H);
+  const aNorm = Math.cos(hueAngle);
+  const bNorm = Math.sin(hueAngle);
+
+  const out = [L, C, H];
+  // choose our strategy
+  const cusp = findCuspOKLCH(aNorm, bNorm, gamut);
+  const LTarget = MapToCuspL(out, cusp);
+
+  let t = findGamutIntersectionOKLCH(aNorm, bNorm, L, C, LTarget, cusp, gamut);
+  out[0] = lerp(LTarget, L, t);
+  out[1] *= t;
+  return out;
+}
+
+avgDelta /= avgCount;
+
+console.log("Min Epsilon:", minDelta);
+console.log("Max Epsilon:", maxDelta);
+console.log("Average Epsilon:", avgDelta);
+console.log("Compare against epsilon:", RGB_CLIP_EPSILON);
+console.log("Total points out of gamut:", totalPointsOutOfGamut);
+console.log(
+  "Total points under epsilon (before map):",
+  totalPointsUnderEpsilonBeforeMapping
+);
+console.log("Total points under epsilon (after map):", totalPointsUnderEpsilon);