@texel/color 1.0.1 → 1.0.3

package/README.md

@@ -2,13 +2,13 @@
 
 ![generated](./test/banner.png)
 
-A minimal and modern color library for JavaScript. Mainly useful for real-time applications, generative art, and graphics on the web.
+A minimal and modern color library for JavaScript. Especially useful for real-time applications, generative art, and graphics on the web.
 
 - Features: fast color conversion, color difference, gamut mapping, and serialization
-- Optimised for speed: approx 20-125 times faster than [Colorjs.io](https://colorjs.io/) (see [benchmarks](#benchmarks))
-- Optimised for low memory and minimal allocations: no arrays or objects are created within conversion and gamut mapping functions
-- Optimised for compact bundles: zero dependencies, and unused color spaces can be automatically tree-shaked away for small sizes (e.g. ~3.5kb minified if you only require OKLCH to sRGB conversion)
-- Optimised for accuracy: [high precision](#accuracy) color space matrices
+- Optimized for speed: approx 20-125 times faster than [Colorjs.io](https://colorjs.io/) (see [benchmarks](#benchmarks))
+- Optimized for low memory and minimal allocations: no arrays or objects are created within conversion and gamut mapping functions
+- Optimized for compact bundles: zero dependencies, and unused color spaces can be automatically tree-shaked away for small sizes (e.g. ~3.5kb minified if you only require OKLCH to sRGB conversion)
+- Optimized for accuracy: [high precision](#accuracy) color space matrices
 - Focused on a minimal and modern set of color spaces:
   - xyz (D65), xyz-d50, oklab, oklch, okhsv, okhsl, srgb, srgb-linear, display-p3, display-p3-linear, rec2020, rec2020-linear, a98-rgb, a98-rgb-linear, prophoto-rgb, prophoto-rgb-linear
 
@@ -307,7 +307,9 @@ sRGB.toBase(in_sRGB, out_linear_sRGB); // linear to gamma transfer function
 
 ### Why another library?
 
-[Colorjs](https://colorjs.io/) is fantastic and perhaps the current leading standard in JavaScript, but it's not very practical for creative coding and real-time web applications, where the requirements are often (1) leaner codebases, (2) highly optimized, and (3) minimal GC thrashing. Colorjs is more focused on matching CSS spec, which means it will very likely continue to grow in complexity, and performance will often be marred (for example, `@texel/color` cusp intersection gamut mapping is ~125 times faster than Colorjs and its defaultt CSS based gamut mapping).
+[Colorjs](https://colorjs.io/) is fantastic and perhaps the current leading standard in JavaScript, but it's not very practical for creative coding and real-time web applications, where the requirements are often (1) leaner codebases, (2) highly optimized, and (3) minimal GC thrashing.
+
+Colorjs, and simialrly, [Culori](https://culorijs.org/)), are focused on matching CSS spec, which means it will very likely continue to grow in complexity over time, and performance will often be marred (for example, `@texel/color` cusp intersection gamut mapping is ~125 times faster than Colorjs and ~60 times faster than culori).
 
 There are many other options such as [color-space](https://www.npmjs.com/package/color-space) or [color-convert](https://www.npmjs.com/package/color-convert), however, these do not support modern spacse such as OKLab and OKHSL, and/or have dubious levels of accuracy (many libraries, for example, do not distinguish between D50 and D65 whitepoints in XYZ).
 
@@ -337,6 +339,7 @@ If you think the matrices or accuracy could be improved, please open a PR.
 There are a few benchmarks inside [test](./test):
 
 - [bench-colorjs.js](./test/bench-colorjs.js) - run with `npm run bench` to compare against colorjs
+- [bench-culori.js](./test/bench-colorjs.js) - run with node to compare against [culori](https://culorijs.org/)
 - [bench-node.js](./test/bench-node.js) - run with `npm run bench:node` to get a node profile
 - [bench-size.js](./test/bench-size.js) - run with `npm run bench:size` to get a small bundle size with esbuild
 
@@ -359,6 +362,21 @@ Ours: 82.04 ms
 Speedup: 23.6x faster
 ```
 
+And against culori:
+
+```
+Testing with input type: Random Samling in OKLab L Planes
+Conversion OKLCH to P3 --
+Culori: 43.30 ms
+Ours: 12.83 ms
+Speedup: 3.4x faster
+
+Gamut Mapping OKLCH to P3 Gamut --
+Culori: 1588.62 ms
+Ours: 23.05 ms
+Speedup: 68.9x faster
+```
+
 ### Running Locally
 
 Clone, `npm install`, then `npm run` to list the available scripts, or `npm t` to run the tests.
@@ -373,4 +391,4 @@ This library was made possible due to the excellent prior work by many developer
 
 ## License
 
-MIT, see [LICENSE.md](http://github.com/mattdesl/@texel/color/blob/master/LICENSE.md) for details.
+MIT, see [LICENSE.md](https://github.com/texel-org/color/blob/main/LICENSE.md) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texel/color",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "a minimal and modern color library",
   "type": "module",
   "main": "./src/index.js",
@@ -13,6 +13,7 @@
     "canvas-sketch": "^0.7.7",
     "canvas-sketch-cli": "^1.11.21",
     "colorjs.io": "^0.5.2",
+    "culori": "^4.0.1",
     "esbuild": "^0.23.0",
     "faucet": "^0.0.4",
     "pako": "^2.1.0",

package/src/gamut.js

@@ -288,8 +288,14 @@ export const gamutMapOKLCH = (
   // convert oklch to base gamut space (i.e. linear sRGB)
   convert(out, OKLCH, gamutSpaceBase, rgbVec);
 
+  // Note: if the distance lies under this threshold, it's unlikely
+  // that gamut mapping will do anything, and it may simply produce a new
+  // point that lies the same or similar distance away from the gamut edge
+  // see test/test-gamut-epsilon.js
+  const RGB_CLIP_EPSILON = 0.000074;
+
   // 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 +320,7 @@ 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;
-    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

@@ -0,0 +1,148 @@
+import {
+  convert,
+  OKLCH,
+  sRGB,
+  sRGBGamut,
+  listColorSpaces,
+  DisplayP3Gamut,
+  DisplayP3,
+  gamutMapOKLCH,
+  constrainAngle,
+  findCuspOKLCH,
+  degToRad,
+  MapToCuspL,
+  OKHSL,
+  OKLab,
+  OKHSLToOKLab,
+} from "../src/index.js";
+
+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)
+  .fill()
+  .map((_, i, lst) => {
+    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 * 360, t, t];
+    const oklab = OKHSLToOKLab(okhsl, gamut);
+    return convert(oklab, OKLab, OKLCH);
+  });
+
+// get N OKLCH pixels by sampling OKLab, many will be out of srgb gamut
+const oklchPixelsRandom = Array(N)
+  .fill()
+  .map((_, i, lst) => {
+    const t = i / (lst.length - 1);
+    return convert([t, t * 2 - 1, t * 2 - 1], OKLab, OKLCH);
+  });
+
+const toP3Gamut = toGamut("p3", "oklch");
+// same perf as p3() it seems
+// const p3Converter = converter("p3");
+
+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;
+    });
+  }
+
+  console.log(
+    "Testing with input type: %s%s",
+    label,
+    fixedCusp ? " (Fixed Cusp)" : ""
+  );
+  const culoriInputsOKLCH = inputPixelsOKLCH.map(([l, c, h]) => {
+    return {
+      mode: "oklch",
+      l,
+      c,
+      h,
+    };
+  });
+
+  let now, elapsedCulori, elapsedOurs;
+  let tmp = [0, 0, 0];
+
+  //// conversion
+
+  tmp = [0, 0, 0];
+  now = performance.now();
+  for (let oklch of inputPixelsOKLCH) {
+    convert(oklch, OKLCH, target, tmp);
+  }
+  elapsedOurs = performance.now() - now;
+
+  now = performance.now();
+  for (let oklchColor of culoriInputsOKLCH) {
+    p3(oklchColor);
+
+    // same perf ?
+    // p3Converter(oklchColor);
+  }
+  elapsedCulori = performance.now() - now;
+  print("Conversion OKLCH to P3");
+
+  //// gamut
+
+  tmp = [0, 0, 0];
+  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;
+  }
+
+  now = performance.now();
+  for (let oklchColor of culoriInputsOKLCH) {
+    toP3Gamut(oklchColor);
+  }
+  elapsedCulori = performance.now() - now;
+  print("Gamut Mapping OKLCH to P3 Gamut");
+
+  function print(label) {
+    console.log("%s --", label);
+    console.log("Culori: %s ms", elapsedCulori.toFixed(2));
+    console.log("Ours: %s ms", elapsedOurs.toFixed(2));
+    if (elapsedCulori > elapsedOurs)
+      console.log(
+        "Speedup: %sx faster",
+        (elapsedCulori / elapsedOurs).toFixed(1)
+      );
+    else
+      console.log(
+        "Slowdown: %sx slower",
+        (elapsedOurs / elapsedCulori).toFixed(1)
+      );
+    console.log();
+  }
+}

package/test/bench-size.js

@@ -1,3 +1,12 @@
-import * as colors from "../";
+// To test @texel/color (~3.5 kb)
+import * as colors from "../src/index.js";
 const rgb = colors.convert([0.5, 0.15, 30], colors.OKLCH, colors.sRGB);
 console.log(rgb);
+
+// To test colorjs.io (~55.3 kb)
+// import Color from "colorjs.io";
+// console.log(new Color("oklch", [0.5, 0.15, 30]).to("srgb").coords);
+
+// To test Culori (~43.2 kb)
+// import { rgb } from "culori";
+// console.log(rgb({ mode: "oklch", l: 0.5, c: 0.15, h: 30 }));

package/test/test-gamut-epsilon.js

@@ -0,0 +1,107 @@
+// 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 {
+  A98RGBGamut,
+  clampedRGB,
+  convert,
+  degToRad,
+  DisplayP3Gamut,
+  findCuspOKLCH,
+  findGamutIntersectionOKLCH,
+  gamutMapOKLCH,
+  isRGBInGamut,
+  lerp,
+  MapToCuspL,
+  OKLCH,
+  Rec2020Gamut,
+  sRGBGamut,
+} from "../src/index.js";
+
+const huePlanes = Array(360)
+  .fill()
+  .map((_, i) => i);
+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;
+
+const EPSILON = 0.000074;
+let totalPointsOutOfGamut = 0;
+let totalPointsUnderEpsilon = 0;
+
+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
+      const rgbl = convert([L, C, H], OKLCH, target);
+
+      // not exactly in space
+      if (!isRGBInGamut(rgbl, 0)) {
+        // 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;
+
+        // convert again to rgb linear
+        const rgbl = convert(out, OKLCH, target);
+        const clipped = clampedRGB(rgbl);
+        const dr = Math.abs(rgbl[0] - clipped[0]);
+        const dg = Math.abs(rgbl[1] - clipped[1]);
+        const db = Math.abs(rgbl[2] - clipped[2]);
+        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, EPSILON)) {
+          totalPointsUnderEpsilon++;
+        }
+      }
+    }
+  }
+}
+avgDelta /= avgCount;
+
+console.log("Min Epsilon:", minDelta);
+console.log("Max Epsilon:", maxDelta);
+console.log("Average Epsilon:", avgDelta);
+console.log("Compare against epsilon:", EPSILON);
+console.log("Total points out of gamut:", totalPointsOutOfGamut);
+console.log("Total points under epsilon:", totalPointsUnderEpsilon);