@texel/color 1.0.5 → 1.1.0

package/README.md

@@ -5,7 +5,7 @@
 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
-- Optimized for speed: approx 20-125 times faster than [Colorjs.io](https://colorjs.io/) (see [benchmarks](#benchmarks))
+- Optimized for speed: approx 5-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
@@ -85,7 +85,7 @@ The return value is the new coordinates in the destination space; such as `[r,g,
 
 #### `output = gamutMapOKLCH(oklch, gamut = sRGBGamut, targetSpace = gamut.space, out = [0, 0, 0], mapping = MapToCuspL, [cusp])`
 
-Performs fast gamut mapping in OKLCH as [described by Björn Ottoson](https://bottosson.github.io/posts/gamutclipping/) (2021). This takes an input `[l,c,h]` coords in OKLCH space, and ensures the final result will lie within the specified color `gamut` (default `sRGBGamut`). You can further specify a different target space (which default's the the gamut's space), for example to get a linear-light sRGB and avoid the transfer function, or to keep the result in OKLCH:
+Performs fast gamut mapping in OKLCH as [described by Björn Ottoson](https://bottosson.github.io/posts/gamutclipping/) (2021). This takes an input `[l,c,h]` coords in OKLCH space, and ensures the final result will lie within the specified color `gamut` (default `sRGBGamut`). You can further specify a different target space (which default's to the gamut's space), for example to get a linear-light sRGB and avoid the transfer function, or to keep the result in OKLCH:
 
 ```js
 import { gamutMapOKLCH, sRGBGamut, sRGBLinear, OKLCH } from "@texel/color";
@@ -142,6 +142,7 @@ const cuspLC = findCuspOKLCH(a, b, gamut);
 
 // ... somewhere else in your program ...
 // pass 'cusp' parameter for faster evaluation
+// expected that your OKLCH coord has the same hue as the cusp (H)
 gamutMapOKLCH(oklch, gamut, gamut.space, out, MapToCuspL, cuspLC);
 ```
 
@@ -162,7 +163,7 @@ serialize([1, 0, 0], OKLCH, sRGB); // "rgb(255, 255, 255)"
 serialize([1, 0, 0], OKLCH); // "oklch(1 0 0)"
 ```
 
-#### `coords = deserialize(colorString)`
+#### `info = deserialize(colorString)`
 
 The inverse of `serialize`, this will take a string and determine the color space `id` it is referencing, and the 3 or 4 (for alpha) `coords`. This is intentionally limited in functionality, only supporting hex RGB, `rgb()` and `rgba()` bytes, and `oklch()`, `oklab()`, and plain `color()` functions with no modifiers.
 
@@ -264,6 +265,10 @@ Converts the xyY coordinates to XYZ form, storing the results in `out` if specif
 
 Performs linear interpolation between min and max with the factor `t`.
 
+#### `v = lerpAngle(min, max, t)`
+
+Performs circular linear interpolation between min and max with the factor `t`, but where the min and max are considered to be angles (in degrees) allowing the value to wrap around within 0 to 360, interpolating to create the shortest arc.
+
 #### `c = clamp(value, min, max)`
 
 Clamps the `value` between min and max and returns the result.
@@ -325,19 +330,27 @@ sRGB.toBase(in_sRGB, out_linear_sRGB); // linear to gamma transfer function
 OKHSLToOKLab([h, s, l], DisplayP3Gamut, optionalOutVec);
 ```
 
+## Interpolation
+
+The library currently only exposes `{ lerp, lerpAngle }` functions. To interpolate colors, you will need to build some additional logic, for example see the [example-interpolation.js](./test/example-interpolation.js) script which creates a color ramp in Canvas2D.
+
+## Custom Color Spaces
+
+You can build custom color space objects to extend this library, such as adding support for CIELab and HSL. See [test/spaces/lab.js](./test/spaces/lab.js) and [test/spaces/hsl.js](./test/spaces/hsl.js) for examples of this. Some of these spaces may be added to the library at a later point, although the current focus is on "modern" spaces (such as OKLab that has largely made CIELab and HSL obsolete). Documentaiton on custom color spaces is WIP.
+
 ## Notes
 
 ### 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, 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).
+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).
 
 ### Supported Spaces
 
-This library does not aim to target every color space; it only focuses on a limited "modern" set, i.e. OKLab, OKHSL and DeltaEOK have replaced CIELab, HSL, and CIEDE2000 for many practical purposes, allowing this library to be simpler and slimmer.
+This library does not aim to target every color space; it only focuses on a limited "modern" set, i.e. OKLab, OKHSL and DeltaEOK have replaced CIELab, HSL, and CIEDE2000 for many practical purposes, allowing this library to be simpler and slimmer. Note that other spaces like CIELab and HSL are supported through 'custom color spaces'.
 
 ### Improvements & Techniques
 
@@ -365,26 +378,47 @@ There are a few benchmarks inside [test](./test):
 - [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
 
-Colorjs comparison benchmark on MacBook Air M2:
+Results below, based on MacBook Air M2. Note that Colorjs performance depends on which API you use (the default class-based API is much slower than the procedural API).
+
+<details>
+  <summary>Benchmark Against Colorjs.io</summary>
 
 ```
-OKLCH to sRGB with gamut mapping --
-Colorjs: 6146.67 ms
-Ours: 46.77 ms
-Speedup: 131.4x faster
-
-All Conversions --
-Colorjs: 10219.40 ms
-Ours: 431.13 ms
-Speedup: 23.7x faster
-
-Conversion + Gamut Mapping --
-Colorjs: 1936.29 ms
-Ours: 82.04 ms
-Speedup: 23.6x faster
+conversion (Colorjs.io procedural API) --
+Colorjs.io: 2955.88 ms
+Ours: 457.86 ms
+Speedup: 6.5x faster
+
+conversion (Colorjs.io main API) --
+Colorjs.io: 10034.38 ms
+Ours: 452.11 ms
+Speedup: 22.2x faster
+
+gamut mapping OKLCH - sRGB (Colorjs.io procedural API) --
+Colorjs.io: 5602.46 ms
+Ours: 49.10 ms
+Speedup: 114.1x faster
+
+gamut mapping OKLCH - sRGB (Colorjs.io main API) --
+Colorjs.io: 5913.80 ms
+Ours: 44.91 ms
+Speedup: 131.7x faster
+
+gamut mapping all spaces to P3 (Colorjs.io procedural API) --
+Colorjs.io: 4693.43 ms
+Ours: 150.16 ms
+Speedup: 31.3x faster
+
+gamut mapping all spaces to P3 (Colorjs.io main API) --
+Colorjs.io: 5478.16 ms
+Ours: 145.88 ms
+Speedup: 37.6x faster
 ```
 
-And against culori:
+</details>
+
+<details>
+  <summary>Benchmark Against Culori</summary>
 
 ```
 Testing with input type: Random Samling in OKLab L Planes
@@ -399,6 +433,8 @@ Ours: 23.05 ms
 Speedup: 68.9x faster
 ```
 
+</details>
+
 ### Running Locally
 
 Clone, `npm install`, then `npm run` to list the available scripts, or `npm t` to run the tests.

package/package.json

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

package/src/core.js

@@ -200,6 +200,12 @@ export const convert = (input, fromSpace, toSpace, out = vec3()) => {
   // and the base we want to get to, linear, OKLab, XYZ etc...
   let toBaseSpace = toSpace.base ?? toSpace;
 
+  // this is something we may support in future, if there is a nice
+  // zero-allocation way of achieving it
+  if (fromSpace.base || toBaseSpace.base) {
+    throw new Error(`Currently only base of depth=1 is supported`);
+  }
+
   if (fromBaseSpace === toBaseSpace) {
     // do nothing, spaces are the same
   } else {
@@ -220,39 +226,47 @@ export const convert = (input, fromSpace, toSpace, out = vec3()) => {
     if (fromBaseSpace.id === "oklab") {
       let mat = toBaseSpace.fromLMS_M;
       if (!mat) {
-        // space doesn't support direct
+        // space doesn't support direct from OKLAB
         // let's convert OKLab to XYZ and then use that
         mat = XYZ.fromLMS_M;
         throughXYZ = true;
         xyzIn = true;
       }
+      // convert OKLAB to output (other space, or xyz)
       out = OKLab_to(out, mat, out);
     } else if (toBaseSpace.id === "oklab") {
       let mat = fromBaseSpace.toLMS_M;
       if (!mat) {
-        // space doesn't support direct
+        // space doesn't support direct to OKLAB
+        // we will need to use XYZ as connection, then convert to OKLAB
         throughXYZ = true;
         outputOklab = true;
       } else {
-        // direct from space to oklab
+        // direct from space to OKLAB
         out = OKLab_from(out, mat, out);
       }
     } else {
+      // any other spaces, we use XYZ D65 as a connection
       throughXYZ = true;
     }
 
     if (throughXYZ) {
       // First, convert to XYZ if we need to
       if (!xyzIn) {
-        if (!fromBaseSpace.toXYZ_M)
-          throw new Error(`no toXYZ_M on ${fromBaseSpace.id}`);
-        out = transform(out, fromBaseSpace.toXYZ_M, out);
+        if (fromBaseSpace.toXYZ) {
+          out = fromBaseSpace.toXYZ(out, out);
+        } else if (fromBaseSpace.toXYZ_M) {
+          out = transform(out, fromBaseSpace.toXYZ_M, out);
+        } else {
+          throw new Error(`no toXYZ or toXYZ_M on ${fromBaseSpace.id}`);
+        }
       }
 
       // Then, adapt D50 <-> D65 if we need to
       if (fromBaseSpace.adapt) {
         out = transform(out, fromBaseSpace.adapt.to, out);
-      } else if (toBaseSpace.adapt) {
+      }
+      if (toBaseSpace.adapt) {
         out = transform(out, toBaseSpace.adapt.from, out);
       }
 
@@ -260,10 +274,12 @@ export const convert = (input, fromSpace, toSpace, out = vec3()) => {
       if (!xyzOut) {
         if (outputOklab) {
           out = OKLab_from(out, XYZ.toLMS_M, out);
-        } else {
-          if (!toBaseSpace.fromXYZ_M)
-            throw new Error(`no fromXYZ_M on ${toBaseSpace.id}`);
+        } else if (toBaseSpace.fromXYZ) {
+          out = toBaseSpace.fromXYZ(out, out);
+        } else if (toBaseSpace.fromXYZ_M) {
           out = transform(out, toBaseSpace.fromXYZ_M, out);
+        } else {
+          throw new Error(`no fromXYZ or fromXYZ_M on ${toBaseSpace.id}`);
         }
       }
     }

package/src/spaces/prophoto-rgb.js

@@ -14,7 +14,7 @@ const ProPhotoRGBToGamma = (v) => (v >= Et ? v ** (1 / 1.8) : 16 * v);
 
 // Note: below is a possibly improved transfer function proposed by CSS Module 4 spec
 // It is currently not matching the outputs of Colorjs.io when dealing with particular
-// negative values, such as convert([1,1,1], OKlab, ProPhotoRGB)
+// negative values, such as convert([1,1,1], OKLab, ProPhotoRGB)
 
 // const ProPhotoRGBToLinear = (val) => {
 //   // convert an array of prophoto-rgb values

package/src/spaces/xyz.js

@@ -2,6 +2,12 @@ import { vec3 } from "../util.js";
 import { transform } from "../core.js";
 import { LMS_to_XYZ_M, XYZ_to_LMS_M } from "../conversion_matrices.js";
 
+// Note: for the time being, these are not exported
+// It may be exported in a future version
+// for compatibility, the four-digit chromaticity-derived ones everyone else uses
+// const D50 = [0.3457 / 0.3585, 1.0, (1.0 - 0.3457 - 0.3585) / 0.3585];
+// const D65 = [0.3127 / 0.329, 1.0, (1.0 - 0.3127 - 0.329) / 0.329];
+
 // Bradford chromatic adaptation from D65 to D50
 // The matrix below is the result of three operations:
 // - convert from XYZ to retinal cone domain

package/src/util.js

@@ -26,9 +26,12 @@ export const hexToRGB = (str, out = vec3()) => {
   return out;
 };
 
-export const RGBtoHex = (rgb) =>
+export const RGBToHex = (rgb) =>
   `#${rgb.map((n) => floatToByte(n).toString(16).padStart(2, "0")).join("")}`;
 
+/** @deprecated use RGBToHex */
+export const RGBtoHex = (rgb) => RGBToHex;
+
 export const isRGBInGamut = (lrgb, ep = GAMUT_EPSILON) => {
   const r = lrgb[0];
   const g = lrgb[1];
@@ -104,16 +107,9 @@ export const vec3 = () => [0, 0, 0];
 //   return ((2 * da) % max) - da;
 // }
 
-// function shortAngleDistDeg(a0, a1) {
-//   var max = 360;
-//   var da = (a1 - a0) % max;
-//   return ((2 * da) % max) - da;
-// }
-
-// function lerpAngleRad(a0, a1, t) {
-//   return a0 + shortAngleDistRad(a0, a1) * t;
-// }
+export const deltaAngle = (a0, a1) => {
+  var da = (a1 - a0) % 360;
+  return ((2 * da) % 360) - da;
+};
 
-// function lerpAngleDeg(a0, a1, t) {
-//   return radToDeg(lerpAngleRad(degToRad(a0), degToRad(a1), t));
-// }
+export const lerpAngle = (a0, a1, t) => a0 + deltaAngle(a0, a1) * t;

package/test/bench-colorjs.js

@@ -1,10 +1,16 @@
 import Color from "colorjs.io";
+import {
+  sRGB as sRGB_ColorJS,
+  OKLCH as OKLCH_ColorJS,
+  P3 as DisplayP3_ColorJS,
+  toGamut,
+} from "colorjs.io/fn";
 import {
   convert,
   OKLCH,
+  OKLab,
   sRGB,
   sRGBGamut,
-  listColorSpaces,
   DisplayP3Gamut,
   DisplayP3,
   gamutMapOKLCH,
@@ -14,27 +20,25 @@ import {
   MapToCuspL,
 } from "../src/index.js";
 
-const fixName = (name) => {
-  return name
-    .replace("display-", "")
-    .replace("a98-rgb", "a98rgb")
-    .replace("prophoto-rgb", "prophoto");
-};
+import { getSupportedColorJSSpaces } from "./colorjs-fn.js";
+
+const supportedSpaces = getSupportedColorJSSpaces();
+
+// @texel/color space interfaces
+const spaces = supportedSpaces.map((s) => s.space);
+
+// Colorjs.io space interfaces & IDs
+const colorJSSpaces = supportedSpaces.map((s) => s.colorJSSpace);
+const colorJSSpaceIDs = supportedSpaces.map((s) => s.colorJSSpace.id);
 
-// TODO: test okhsl with latest version of colorjs
-const spaces = listColorSpaces().filter((f) => !/ok(hsv|hsl)/i.test(f.id));
-const spacesForColorjs = spaces.map((s) => fixName(s.id));
+const N = 128 * 128;
 
-const vecs = Array(128 * 128)
+// sampling variables within OKLab and converting to OKLCH
+const vecs = Array(N)
   .fill()
   .map((_, i, lst) => {
     const t = i / (lst.length - 1);
-    return (
-      Array(3)
-        .fill()
-        // -0.5 .. 1.5
-        .map(() => t + (t * 2 - 1) * 0.5)
-    );
+    return convert([t, t * 2 - 1, t * 2 - 1], OKLab, OKLCH);
   });
 
 const tmp = [0, 0, 0];
@@ -59,80 +63,165 @@ const oklchVecs = Array(512 * 256)
     return [t0, t0, H];
   });
 
-now = performance.now();
-for (let vec of oklchVecs) {
-  new Color("oklch", vec).to("srgb").toGamut({ space: "srgb", method: "css" });
-}
-elapsedColorjs = performance.now() - now;
-
-now = performance.now();
-for (let vec of oklchVecs) {
-  // you can omit the cusp and it will be found on the fly
-  // however the test will run slightly slower (e.g. ~100x faster rather than ~120x)
-  const cusp = hueCusps[vec[2]];
-  gamutMapOKLCH(vec, sRGBGamut, sRGB, tmp, MapToCuspL, cusp);
-}
-elapsedOurs = performance.now() - now;
-
-console.log("OKLCH to sRGB with gamut mapping --");
-console.log("Colorjs: %s ms", elapsedColorjs.toFixed(2));
-console.log("Ours: %s ms", elapsedOurs.toFixed(2));
-console.log("Speedup: %sx faster", (elapsedColorjs / elapsedOurs).toFixed(1));
-
-//// conversions
-
-now = performance.now();
-for (let vec of vecs) {
-  for (let i = 0; i < spacesForColorjs.length; i++) {
-    for (let j = 0; j < spacesForColorjs.length; j++) {
-      const a = spacesForColorjs[i];
-      const b = spacesForColorjs[j];
-      new Color(a, vec).to(b);
+compare(
+  "conversion (Colorjs.io procedural API)",
+  () => {
+    for (let vec of vecs) {
+      for (let i = 0; i < colorJSSpaces.length; i++) {
+        for (let j = 0; j < colorJSSpaces.length; j++) {
+          const a = colorJSSpaces[i];
+          const b = colorJSSpaces[j];
+          const ret = b.from(a, vec);
+        }
+      }
+    }
+  },
+  () => {
+    for (let vec of vecs) {
+      for (let i = 0; i < spaces.length; i++) {
+        for (let j = 0; j < spaces.length; j++) {
+          const a = spaces[i];
+          const b = spaces[j];
+          convert(vec, a, b, tmp);
+        }
+      }
     }
   }
-}
-elapsedColorjs = performance.now() - now;
-
-now = performance.now();
-for (let vec of vecs) {
-  for (let i = 0; i < spaces.length; i++) {
-    for (let j = 0; j < spaces.length; j++) {
-      const a = spaces[i];
-      const b = spaces[j];
-      convert(vec, a, b, tmp);
+);
+
+compare(
+  "conversion (Colorjs.io main API)",
+  () => {
+    for (let vec of vecs) {
+      for (let i = 0; i < colorJSSpaceIDs.length; i++) {
+        for (let j = 0; j < colorJSSpaceIDs.length; j++) {
+          const a = colorJSSpaceIDs[i];
+          const b = colorJSSpaceIDs[j];
+          new Color(a, vec).to(b);
+        }
+      }
+    }
+  },
+  () => {
+    for (let vec of vecs) {
+      for (let i = 0; i < spaces.length; i++) {
+        for (let j = 0; j < spaces.length; j++) {
+          const a = spaces[i];
+          const b = spaces[j];
+          convert(vec, a, b, tmp);
+        }
+      }
     }
   }
-}
-elapsedOurs = performance.now() - now;
-console.log();
-console.log("All Conversions --");
-console.log("Colorjs: %s ms", elapsedColorjs.toFixed(2));
-console.log("Ours: %s ms", elapsedOurs.toFixed(2));
-console.log("Speedup: %sx faster", (elapsedColorjs / elapsedOurs).toFixed(1));
-
-//// gamut mapping
-
-now = performance.now();
-for (let vec of vecs) {
-  for (let i = 0; i < spacesForColorjs.length; i++) {
-    const a = spacesForColorjs[i];
-    new Color(a, vec).to("p3").toGamut({ space: "p3", method: "css" });
+);
+
+compare(
+  "gamut mapping OKLCH - sRGB (Colorjs.io procedural API)",
+  () => {
+    let tmpColor = { space: sRGB_ColorJS, coords: [0, 0, 0], alpha: 1 };
+    for (let vec of oklchVecs) {
+      tmpColor.coords = sRGB_ColorJS.from(OKLCH_ColorJS, vec);
+      toGamut(tmpColor);
+    }
+  },
+  () => {
+    for (let vec of oklchVecs) {
+      // you can omit the cusp and it will be found on the fly,
+      // however the test will run slightly slower
+      const cusp = hueCusps[vec[2]];
+      gamutMapOKLCH(vec, sRGBGamut, sRGB, tmp, MapToCuspL, cusp);
+    }
   }
-}
-elapsedColorjs = performance.now() - now;
-
-now = performance.now();
-for (let vec of vecs) {
-  for (let i = 0; i < spaces.length; i++) {
-    const a = spaces[i];
-    convert(vec, a, OKLCH, tmp);
-    gamutMapOKLCH(tmp, DisplayP3Gamut, DisplayP3, tmp);
+);
+
+compare(
+  "gamut mapping OKLCH - sRGB (Colorjs.io main API)",
+  () => {
+    for (let vec of oklchVecs) {
+      new Color("oklch", vec)
+        .to("srgb")
+        .toGamut({ space: "srgb", method: "css" });
+    }
+  },
+  () => {
+    for (let vec of oklchVecs) {
+      // you can omit the cusp and it will be found on the fly,
+      // however the test will run slightly slower
+      const cusp = hueCusps[vec[2]];
+      gamutMapOKLCH(vec, sRGBGamut, sRGB, tmp, MapToCuspL, cusp);
+    }
   }
+);
+
+compare(
+  "gamut mapping all spaces to P3 (Colorjs.io procedural API)",
+  () => {
+    let tmpColor = { space: DisplayP3_ColorJS, coords: [0, 0, 0], alpha: 1 };
+    for (let vec of vecs) {
+      for (let i = 0; i < colorJSSpaces.length; i++) {
+        const a = colorJSSpaces[i];
+        tmpColor.coords = DisplayP3_ColorJS.from(a, vec);
+        toGamut(tmpColor);
+      }
+    }
+  },
+  () => {
+    for (let vec of vecs) {
+      for (let i = 0; i < spaces.length; i++) {
+        const a = spaces[i];
+        convert(vec, a, OKLCH, tmp);
+        gamutMapOKLCH(tmp, DisplayP3Gamut, DisplayP3, tmp);
+      }
+    }
+  }
+);
+
+compare(
+  "gamut mapping all spaces to P3 (Colorjs.io main API)",
+  () => {
+    for (let vec of vecs) {
+      for (let i = 0; i < colorJSSpaceIDs.length; i++) {
+        const a = colorJSSpaceIDs[i];
+        new Color(a, vec).to("p3").toGamut({ space: "p3", method: "css" });
+      }
+    }
+  },
+  () => {
+    for (let vec of vecs) {
+      for (let i = 0; i < spaces.length; i++) {
+        const a = spaces[i];
+        convert(vec, a, OKLCH, tmp);
+        gamutMapOKLCH(tmp, DisplayP3Gamut, DisplayP3, tmp);
+      }
+    }
+  }
+);
+
+function print(label) {
+  console.log("%s --", label);
+  console.log("Colorjs.io: %s ms", elapsedColorjs.toFixed(2));
+  console.log("Ours: %s ms", elapsedOurs.toFixed(2));
+  if (elapsedColorjs > elapsedOurs)
+    console.log(
+      "Speedup: %sx faster",
+      (elapsedColorjs / elapsedOurs).toFixed(1)
+    );
+  else
+    console.log(
+      "Slowdown: %sx slower",
+      (elapsedOurs / elapsedColorjs).toFixed(1)
+    );
+  console.log();
 }
-elapsedOurs = performance.now() - now;
 
-console.log();
-console.log("Conversion + Gamut Mapping --");
-console.log("Colorjs: %s ms", elapsedColorjs.toFixed(2));
-console.log("Ours: %s ms", elapsedOurs.toFixed(2));
-console.log("Speedup: %sx faster", (elapsedColorjs / elapsedOurs).toFixed(1));
+function compare(label, colorJSFn, ourFn) {
+  now = performance.now();
+  colorJSFn();
+  elapsedColorjs = performance.now() - now;
+
+  now = performance.now();
+  ourFn();
+  elapsedOurs = performance.now() - now;
+
+  print(label);
+}

package/test/colorjs-fn.js

@@ -0,0 +1,34 @@
+import * as ColorJSFn from "colorjs.io/fn";
+import { listColorSpaces } from "../src/index.js";
+
+// Colorjs.io uses some different naming conventions than @texel/color
+const getColorJSID = (name) => {
+  return name
+    .replace("display-", "")
+    .replace(/^xyz$/, "xyz-d65")
+    .replace("a98-rgb", "a98rgb")
+    .replace("prophoto-rgb", "prophoto");
+};
+
+// returns a list of ColorJS.io space IDs that are supported by @texel/color
+// okhsl/okhsv is skipped due to it not being included in this npm version of colorjs.io
+export function getSupportedColorJSSpaces() {
+  const spaceFns = Object.values(ColorJSFn);
+  const spaces = listColorSpaces().filter((s) => !/ok(hsv|hsl)/i.test(s.id));
+  return spaces.map((space) => {
+    const cjsID = getColorJSID(space.id);
+    const colorJSSpace = spaceFns.find((f) => f.id === cjsID);
+    if (!colorJSSpace)
+      throw new Error(`expected ${cjsID} to exist in colorjs.io/fn`);
+    return {
+      space,
+      colorJSSpace,
+    };
+  });
+}
+
+// Register all spaces
+const spaces = getSupportedColorJSSpaces().map((s) => s.colorJSSpace);
+for (let space of spaces) {
+  ColorJSFn.ColorSpace.register(space);
+}

package/test/example-interpolation.js

@@ -0,0 +1,107 @@
+import canvasSketch from "canvas-sketch";
+import {
+  convert,
+  DisplayP3Gamut,
+  gamutMapOKLCH,
+  lerp,
+  lerpAngle,
+  OKLab,
+  OKLCH,
+  serialize,
+  sRGB,
+  sRGBGamut,
+} from "../src/index.js";
+
+const settings = {
+  dimensions: [2048, 512],
+  attributes: {
+    // comment this out if you want sRGB output
+    colorSpace: "display-p3",
+  },
+};
+
+const mix = (() => {
+  const tmpA = [0, 0, 0];
+  const tmpB = [0, 0, 0];
+
+  // you can decide whether you'd like to interpolate in
+  // OKLab, OKLCH or another space (you may need to adjust interpolation
+  // if you use a custom space)
+  const interpolationSpace = OKLCH;
+
+  // e.g. mix({ space, coords }, { space, coords }, 0.5, sRGB)
+  return (a, b, t, outputSpace = sRGB, out = [0, 0, 0]) => {
+    // bring both spaces into the shared interpolation space
+    convert(a.coords, a.space, interpolationSpace, tmpA);
+    convert(b.coords, b.space, interpolationSpace, tmpB);
+
+    // now do interpolation
+    out[0] = lerp(tmpA[0], tmpB[0], t);
+    out[1] = lerp(tmpA[1], tmpB[1], t);
+    if (interpolationSpace.id === "oklch") {
+      // for cylindrical spaces, use a circular interpolation for Hue parameter
+      // note if you decide to use a custom space like HSL as your interpolation space,
+      // you'll have to use the first parameter instead...
+      out[2] = lerpAngle(tmpA[2], tmpB[2], t);
+    } else {
+      // otherwise can use a regular linear interpolation
+      out[2] = lerp(tmpA[2], tmpB[2], t);
+    }
+
+    // make sure we convert from interpolation space to the target output space
+    convert(out, interpolationSpace, outputSpace, out);
+    return out;
+  };
+})();
+
+// utility to create a ramp between two 'colors' as { space, coords }
+function ramp(a, b, steps = 4, outputSpace = sRGB) {
+  return Array(steps)
+    .fill()
+    .map((_, i, lst) => {
+      const t = lst.length <= 1 ? 0 : i / (lst.length - 1);
+      return mix(a, b, t, outputSpace);
+    });
+}
+
+const sketch = ({ context }) => {
+  const { colorSpace = "srgb" } = context.getContextAttributes();
+  const gamut = colorSpace === "srgb" ? sRGBGamut : DisplayP3Gamut;
+
+  return ({ context, width, height }) => {
+    context.fillStyle = "white";
+    context.fillRect(0, 0, width, height);
+
+    const A = {
+      space: sRGB,
+      coords: [0, 0, 1],
+    };
+
+    const B = {
+      space: OKLCH,
+      coords: [0.55, 0.4, 30],
+    };
+
+    const slices = 16;
+    const sliceWidth = width / slices;
+
+    // the output space is whatever the canvas expects (sRGB or DisplayP3)
+    const outputSpace = gamut.space;
+
+    // create a ramp of colors in OKLCH
+    // then gamut map them to the outputSpace
+    const colors = ramp(A, B, slices, OKLCH).map((oklch) =>
+      gamutMapOKLCH(oklch, gamut, outputSpace)
+    );
+
+    for (let i = 0; i < slices; i++) {
+      const color = colors[i];
+
+      // turn the color (now in outputSpace) into a context string
+      context.fillStyle = serialize(color, outputSpace);
+      context.fillRect(i * sliceWidth, 0, sliceWidth, height);
+    }
+  };
+};
+
+canvasSketch(sketch, settings);

package/test/spaces/hsl.js

@@ -0,0 +1,82 @@
+import { sRGB, sRGBLinear } from "../../src/index.js";
+
+export const HSL = {
+  id: "hsl",
+  // Note: @texel/color currently only supports 1-level depth for color spaces
+  // (for performance & memory reasons) - so our base must be one without another base space
+  base: sRGBLinear,
+  // Adapted from https://drafts.csswg.org/css-color-4/better-rgbToHsl.js
+  fromBase: (rgb, out = [0, 0, 0]) => {
+    // from sRGBLinear (this space's base) to sRGB (for HSL conversion)
+    sRGB.fromBase(rgb, out);
+    const r = out[0];
+    const g = out[1];
+    const b = out[2];
+    let max = Math.max(r, g, b);
+    let min = Math.min(r, g, b);
+    let h = 0,
+      s = 0,
+      l = (min + max) / 2;
+    let d = max - min;
+
+    if (d !== 0) {
+      s = l === 0 || l === 1 ? 0 : (max - l) / Math.min(l, 1 - l);
+
+      switch (max) {
+        case r:
+          h = (g - b) / d + (g < b ? 6 : 0);
+          break;
+        case g:
+          h = (b - r) / d + 2;
+          break;
+        case b:
+          h = (r - g) / d + 4;
+      }
+
+      h = h * 60;
+    }
+
+    // Very out of gamut colors can produce negative saturation
+    // If so, just rotate the hue by 180 and use a positive saturation
+    // see https://github.com/w3c/csswg-drafts/issues/9222
+    if (s < 0) {
+      h += 180;
+      s = Math.abs(s);
+    }
+
+    if (h >= 360) {
+      h -= 360;
+    }
+
+    out[0] = h;
+    out[1] = s * 100;
+    out[2] = l * 100;
+    return out;
+  },
+  // Adapted from https://en.wikipedia.org/wiki/HSL_and_HSV#HSL_to_RGB_alternative
+  toBase: (hsl, out = [0, 0, 0]) => {
+    let h = hsl[0];
+    let s = hsl[1];
+    let l = hsl[2];
+    h = h % 360;
+    if (h < 0) {
+      h += 360;
+    }
+
+    s /= 100;
+    l /= 100;
+
+    const a = s * Math.min(l, 1 - l);
+    out[0] = f(h, l, a, 0);
+    out[1] = f(h, l, a, 8);
+    out[2] = f(h, l, a, 4);
+    // from sRGB to sRGBLinear (this space's base)
+    sRGB.toBase(out, out);
+    return out;
+  },
+};
+
+function f(h, l, a, n) {
+  let k = (n + h / 30) % 12;
+  return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+}

package/test/spaces/lab.js

@@ -0,0 +1,58 @@
+// Lab aka CIELAB aka L*a*b* (uses a D50 WHITE_D50 point and has to be adapted)
+// refer to CSS Color Module Level 4 Spec for more details
+// Source code reference: Colorjs.io
+import { D50_to_D65_M, D65_to_D50_M } from "../../src/index.js";
+
+// K * e  = 2^3 = 8
+const e = 216 / 24389; // 6^3/29^3 == (24/116)^3
+const e3 = 24 / 116;
+const K = 24389 / 27; // 29^3/3^3
+const WHITE_D50 = [0.3457 / 0.3585, 1.0, (1.0 - 0.3457 - 0.3585) / 0.3585];
+
+const fterm = (value) =>
+  value > e ? Math.cbrt(value) : (K * value + 16) / 116;
+
+const inv = (value) =>
+  value > e3 ? Math.pow(value, 3) : (116 * value - 16) / K;
+
+export const Lab = {
+  id: "lab",
+  adapt: {
+    // chromatic adaptation to and from D65
+    to: D50_to_D65_M,
+    from: D65_to_D50_M,
+  },
+  // Convert D50-adapted XYX to Lab
+  // CIE 15.3:2004 section 8.2.1.1
+  fromXYZ(xyz, out = [0, 0, 0]) {
+    // XYZ scaled relative to reference WHITE_D50, then modified
+    out[0] = fterm(xyz[0] / WHITE_D50[0]);
+    out[1] = fterm(xyz[1] / WHITE_D50[1]);
+    out[2] = fterm(xyz[2] / WHITE_D50[2]);
+    let L = 116 * out[1] - 16;
+    let a = 500 * (out[0] - out[1]);
+    let b = 200 * (out[1] - out[2]);
+    out[0] = L;
+    out[1] = a;
+    out[2] = b;
+    return out;
+  },
+  // Convert Lab to D50-adapted XYZ
+  // Same result as CIE 15.3:2004 Appendix D although the derivation is different
+  // http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html
+  toXYZ(Lab, out = [0, 0, 0]) {
+    // compute f, starting with the luminance-related term
+    const L = Lab[0];
+    const a = Lab[1];
+    const b = Lab[2];
+    out[1] = (L + 16) / 116;
+    out[0] = a / 500 + out[1];
+    out[2] = out[1] - b / 200;
+
+    // compute xyz and scale by WHITE_D50
+    out[0] = inv(out[0]) * WHITE_D50[0];
+    out[1] = (L > 8 ? Math.pow((L + 16) / 116, 3) : L / K) * WHITE_D50[1];
+    out[2] = inv(out[2]) * WHITE_D50[2];
+    return out;
+  },
+};

package/test/test-colorjs.js

@@ -1,16 +1,18 @@
 import test from "tape";
 import Color from "colorjs.io";
 import arrayAlmostEqual from "./almost-equal.js";
-import { listColorSpaces, convert } from "../src/index.js";
+import { convert } from "../src/index.js";
+import { getSupportedColorJSSpaces } from "./colorjs-fn.js";
 
 test("should approximately match colorjs.io conversions", async (t) => {
   // note: we skip okhsv/hsl as colorjs.io doesn't support in the current npm version
-  const spaces = listColorSpaces().filter((f) => !/ok(hsl|hsv)/i.test(f.id));
+  const spaces = getSupportedColorJSSpaces();
   const vecs = [
     [0.12341, 0.12001, 0.05212],
     [1, 1, 1],
     [1, 0, 0],
     [0, 0, 0],
+    [-0.5, -0.5, -0.5],
     // some other inputs
     [0.95, 1, 1.089],
     [0.45, 1.236, -0.019],
@@ -28,18 +30,15 @@ test("should approximately match colorjs.io conversions", async (t) => {
   //     Math.random() * 2 - 1,
   //   ]);
 
-  const fixName = (name) => {
-    return name
-      .replace("display-", "")
-      .replace("a98-rgb", "a98rgb")
-      .replace("prophoto-rgb", "prophoto");
-  };
-
   for (let vec of vecs) {
     for (let i = 0; i < spaces.length; i++) {
       for (let j = 0; j < spaces.length; j++) {
-        const a = spaces[i];
-        const b = spaces[j];
+        const A = spaces[i];
+        const B = spaces[j];
+
+        // @texel/color spaces
+        const a = A.space;
+        const b = B.space;
         const suffix = `${a.id}-to-${b.id}`;
 
         console.log(suffix);
@@ -47,8 +46,8 @@ test("should approximately match colorjs.io conversions", async (t) => {
         const tmp = vec.slice();
         const expected1 = convert(vec, a, b, tmp);
 
-        const colorjsid_a = fixName(a.id);
-        const colorjsid_b = fixName(b.id);
+        const colorjsid_a = A.colorJSSpace.id;
+        const colorjsid_b = B.colorJSSpace.id;
         t.deepEqual(expected0, tmp, `${suffix} copies into`);
         t.deepEqual(expected0, expected1, `${suffix} copies into`);
         t.equal(expected1, tmp, `${suffix} copies into and returns`);

package/test/test-other-spaces.js

@@ -0,0 +1,115 @@
+import {
+  convert,
+  XYZD50,
+  sRGB,
+  XYZ,
+  ProPhotoRGB,
+  OKLCH,
+  sRGBLinear,
+} from "../src/index.js";
+import { Lab } from "./spaces/lab.js";
+import { HSL } from "./spaces/hsl.js";
+import test from "tape";
+import Color from "colorjs.io";
+import arrayAlmostEqual from "./almost-equal.js";
+
+test("should approximately match colorjs.io CIELAB", async (t) => {
+  let input = [0.5, 0.1243, -0.123];
+  let inputSpace = OKLCH;
+  let outputSpace = Lab;
+  let expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  let result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(expected, result);
+
+  inputSpace = XYZD50;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  inputSpace = XYZ;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  inputSpace = sRGB;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  inputSpace = ProPhotoRGB;
+  expected = new Color("prophoto", input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  inputSpace = Lab;
+  outputSpace = XYZ;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  outputSpace = XYZD50;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  outputSpace = Lab;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  outputSpace = sRGBLinear;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  outputSpace = sRGB;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+});
+
+test("should approximately match colorjs.io HSL", async (t) => {
+  let input = [30, 50, 50];
+  let inputSpace = HSL;
+  let outputSpace = OKLCH;
+  let expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  let result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  outputSpace = XYZD50;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  outputSpace = sRGB;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  outputSpace = sRGBLinear;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  input = [0.5, 0.2, 30];
+  inputSpace = OKLCH;
+  outputSpace = HSL;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  inputSpace = XYZ;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  inputSpace = sRGB;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+
+  inputSpace = sRGBLinear;
+  expected = new Color(inputSpace.id, input).to(outputSpace.id).coords;
+  result = convert(input, inputSpace, outputSpace);
+  t.deepEqual(arrayAlmostEqual(expected, result), true);
+});

package/test/test.js

@@ -5,7 +5,7 @@ import {
   floatToByte,
   hexToRGB,
   isRGBInGamut,
-  RGBtoHex,
+  RGBToHex,
   linear_sRGB_to_LMS_M,
   LMS_to_linear_sRGB_M,
   LMS_to_XYZ_M,
@@ -320,7 +320,7 @@ test("should deserialize color string information", async (t) => {
 });
 
 test("utils", async (t) => {
-  t.deepEqual(RGBtoHex([0, 0.5, 1]), "#0080ff");
+  t.deepEqual(RGBToHex([0, 0.5, 1]), "#0080ff");
   t.deepEqual(hexToRGB("#0080ff"), [0, 0.5019607843137255, 1]);
   const tmp = [0, 0, 0];
   hexToRGB("#0080ff", tmp);