@texel/color 1.0.1 → 1.0.2

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.2",
   "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/test/bench-culori.js

@@ -0,0 +1,115 @@
+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;
+
+// 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, t, t * 360];
+    const oklab = OKHSLToOKLab(okhsl, DisplayP3Gamut);
+    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 Samling in P3 Gamut");
+test(oklchPixelsRandom, "Random Samling in OKLab L Planes");
+
+function test(inputPixelsOKLCH, label) {
+  console.log("Testing with input type: %s", label);
+  const culoriInputsOKLCH = oklchPixelsRandom.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, DisplayP3, 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];
+  now = performance.now();
+  for (let oklch of inputPixelsOKLCH) {
+    gamutMapOKLCH(oklch, DisplayP3Gamut, DisplayP3, 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 }));