palette-shader 0.12.0 → 0.14.0

package/README.md

@@ -16,6 +16,19 @@ So if one of your palette colors only claims a tiny sliver, it lives very close
 - **How balanced** the palette is overall — even regions mean even coverage
 - **Whether a new color is worth adding** — if it doesn't carve out its own space, it's probably not pulling its weight
 
+### Common questions → recommended settings
+
+| I want to know…                           | Color model                     | Distance metric |
+| ----------------------------------------- | ------------------------------- | --------------- |
+| How my hue distribution looks             | `okhslPolar`                    | `oklab`         |
+| Which two colors are most similar         | `okhsl` or `oklab`              | `deltaE2000`    |
+| Whether a new color is worth adding       | `okhslPolar`                    | `oklab`         |
+| How my palette reads on print             | `cielabD50` or `cielchD50Polar` | `cielabD50`     |
+| How close the colors look to a human eye  | `oklchPolar`                    | `deltaE2000`    |
+| What the palette looks like to a computer | `hslPolar` or `rgb`             | `rgb`           |
+
+For a deeper breakdown of every color model and metric, see [docs/use-cases.md](docs/use-cases.md).
+
 ---
 
 ## Install
@@ -35,7 +48,10 @@ import { PaletteViz } from 'palette-shader';
 import { converter } from 'culori';
 
 const toSRGB = converter('srgb');
-const toRGB = (hex) => { const c = toSRGB(hex); return [c.r, c.g, c.b]; };
+const toRGB = (hex) => {
+  const c = toSRGB(hex);
+  return [c.r, c.g, c.b];
+};
 
 // option A — pass a container, canvas is appended automatically
 const viz = new PaletteViz({
@@ -50,6 +66,8 @@ const viz = new PaletteViz({ palette: ['#264653', '#2a9d8f', '#e9c46a'].map(toRG
 document.querySelector('#app').appendChild(viz.canvas);
 ```
 
+If you only use the 2D renderer, import `PaletteViz` and let your bundler tree-shake the rest. `PaletteViz3D` pulls in substantially more code for mesh generation, extra shaders, and interaction handling, so it is worth avoiding in apps that never render the 3-D view.
+
 ---
 
 ## Constructor
@@ -60,20 +78,21 @@ new PaletteViz(options?: PaletteVizOptions)
 
 All options are optional. The palette defaults to a random 20-color set.
 
-| Option           | Type                | Default            | Description                                                                                                  |
-| ---------------- | ------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
-| `palette`        | `[number, number, number][]` | random   | sRGB colors as `[r, g, b]` arrays, each component in the `0–1` range                                        |
-| `container`      | `HTMLElement`       | `undefined`        | Element the canvas is appended to. Omit and use `viz.canvas` to place it yourself                            |
-| `width`          | `number`            | `512`              | Canvas width in CSS pixels                                                                                   |
-| `height`         | `number`            | `512`              | Canvas height in CSS pixels                                                                                  |
-| `pixelRatio`     | `number`            | `devicePixelRatio` | Renderer pixel ratio                                                                                         |
-| `colorModel`     | `string`            | `'okhsv'`          | Color space for the visualization (see [Color models](#color-models))                                        |
-| `distanceMetric` | `string`            | `'oklab'`          | Distance function for nearest-color matching (see [Distance metrics](#distance-metrics))                     |
-| `axis`           | `'x' \| 'y' \| 'z'` | `'y'`              | Which axis the `position` value controls                                                                     |
-| `position`       | `number`            | `0`                | 0–1 position along the chosen axis                                                                           |
-| `invertZ`        | `boolean`           | `false`            | Flip the lightness/value axis                                                                                |
-| `showRaw`        | `boolean`           | `false`            | Bypass nearest-color matching (shows the raw color space)                                                    |
-| `outlineWidth`   | `number`            | `0`                | Draw a transparent outline where palette regions meet. Width in physical pixels. `0` disables (no overhead). |
+| Option           | Type                         | Default            | Description                                                                                                                                                            |
+| ---------------- | ---------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `palette`        | `[number, number, number][]` | random             | sRGB colors as `[r, g, b]` arrays, each component in the `0–1` range                                                                                                   |
+| `container`      | `HTMLElement`                | `undefined`        | Element the canvas is appended to. Omit and use `viz.canvas` to place it yourself                                                                                      |
+| `width`          | `number`                     | `512`              | Canvas width in CSS pixels                                                                                                                                             |
+| `height`         | `number`                     | `512`              | Canvas height in CSS pixels                                                                                                                                            |
+| `pixelRatio`     | `number`                     | `devicePixelRatio` | Renderer pixel ratio                                                                                                                                                   |
+| `colorModel`     | `string`                     | `'okhsv'`          | Color space for the visualization (see [Color models](#color-models))                                                                                                  |
+| `distanceMetric` | `string`                     | `'oklab'`          | Distance function for nearest-color matching (see [Distance metrics](#distance-metrics))                                                                               |
+| `axis`           | `'x' \| 'y' \| 'z'`          | `'y'`              | Which axis the `position` value controls                                                                                                                               |
+| `position`       | `number`                     | `0`                | 0–1 position along the chosen axis                                                                                                                                     |
+| `invertAxes`     | `('x' \| 'y' \| 'z')[]`      | `[]`               | Invert one or more axes, for example `['z']` or `['x', 'z']`. In 2-D polar views, `y` inversion is resolved as a vertical view flip to avoid the mirrored center seam. |
+| `showRaw`        | `boolean`                    | `false`            | Bypass nearest-color matching (shows the raw color space)                                                                                                              |
+| `outlineWidth`   | `number`                     | `0`                | Draw a transparent outline where palette regions meet. Width in physical pixels. `0` disables (no overhead).                                                           |
+| `gamutClip`      | `boolean`                    | `false`            | Discard out-of-sRGB-gamut pixels instead of clamping. Reveals the true gamut boundary of the color model.                                                              |
 
 ---
 
@@ -82,13 +101,18 @@ All options are optional. The palette defaults to a random 20-color set.
 Every constructor option is also a live setter/getter. Assigning any of them re-renders immediately via `requestAnimationFrame`.
 
 ```js
-viz.palette = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+viz.palette = [
+  [1, 0, 0],
+  [0, 1, 0],
+  [0, 0, 1],
+];
 viz.position = 0.5;
 viz.colorModel = 'okhslPolar';
 viz.distanceMetric = 'deltaE2000';
-viz.invertZ = true;
+viz.invertAxes = ['z'];
 viz.showRaw = true;
 viz.outlineWidth = 2; // transparent border between regions, in physical pixels
+viz.gamutClip = true; // discard out-of-gamut pixels
 viz.pixelRatio = window.devicePixelRatio; // update after display changes
 ```
 
@@ -178,11 +202,11 @@ Controls the 3-D color space the visualization is rendered in. Polar variants (`
 
 **CIE Lab / LCH — D65**
 
-| Value           | Shape | Description                                                     |
-| --------------- | ----- | --------------------------------------------------------------- |
-| `'cielab'`      | cube  | CIELab D65: x→a, y→b, z→L. The classic perceptual color space.  |
-| `'cielch'`      | cube  | CIELab D65 in cylindrical LCH coordinates.                      |
-| `'cielchPolar'` | wheel | Polar form of CIELch D65.                                       |
+| Value           | Shape | Description                                                    |
+| --------------- | ----- | -------------------------------------------------------------- |
+| `'cielab'`      | cube  | CIELab D65: x→a, y→b, z→L. The classic perceptual color space. |
+| `'cielch'`      | cube  | CIELab D65 in cylindrical LCH coordinates.                     |
+| `'cielchPolar'` | wheel | Polar form of CIELch D65.                                      |
 
 **CIE Lab / LCH — D50**
 
@@ -313,7 +337,11 @@ import { paletteToRGBA, randomPalette, fragmentShader } from 'palette-shader';
 
 // Get raw RGBA bytes (Uint8Array, sRGB, 4 bytes per color)
 // Useful for building your own WebGL texture or processing palette data
-const rgba = paletteToRGBA([[1, 0, 0], [0, 1, 0], [0, 0, 1]]);
+const rgba = paletteToRGBA([
+  [1, 0, 0],
+  [0, 1, 0],
+  [0, 0, 1],
+]);
 
 // Quick random palette for prototyping
 const palette = randomPalette(16);
@@ -337,7 +365,7 @@ const viz3d = new PaletteViz3D({
   palette: ['#264653', '#2a9d8f', '#e9c46a', '#f4a261', '#e76f51'].map(toRGB),
   container: document.querySelector('#app'),
   colorModel: 'okhsv',
-  position: 1.0,        // 1 = full volume, 0 = fully sliced
+  position: 1.0, // 1 = full volume, 0 = fully sliced
   outlineWidth: 2,
 });
 ```
@@ -350,7 +378,7 @@ new PaletteViz3D(options?: PaletteViz3DOptions)
 
 | Option           | Type                         | Default               | Description                                                                  |
 | ---------------- | ---------------------------- | --------------------- | ---------------------------------------------------------------------------- |
-| `palette`        | `[number, number, number][]` | random                | sRGB colors as `[r, g, b]`, each in `0–1`                                   |
+| `palette`        | `[number, number, number][]` | random                | sRGB colors as `[r, g, b]`, each in `0–1`                                    |
 | `container`      | `HTMLElement`                | `undefined`           | Element the canvas is appended to                                            |
 | `width`          | `number`                     | `512`                 | Canvas width in CSS pixels                                                   |
 | `height`         | `number`                     | `512`                 | Canvas height in CSS pixels                                                  |
@@ -358,10 +386,11 @@ new PaletteViz3D(options?: PaletteViz3DOptions)
 | `colorModel`     | `string`                     | `'okhsv'`             | Color model (see [Color models](#color-models)). Polar → cylinder mesh       |
 | `distanceMetric` | `string`                     | `'oklab'`             | Distance metric (see [Distance metrics](#distance-metrics))                  |
 | `position`       | `number`                     | `1`                   | 0–1 slice position. `1` shows the full volume; `0` slices it completely away |
-| `invertZ`        | `boolean`                    | `false`               | Flip the lightness/value axis                                                |
+| `invertAxes`     | `('x' \| 'y' \| 'z')[]`      | `[]`                  | Invert one or more axes, for example `['z']` or `['x', 'z']`                 |
 | `showRaw`        | `boolean`                    | `false`               | Bypass nearest-color matching                                                |
 | `outlineWidth`   | `number`                     | `0`                   | Transparent outline width (physical px). `0` disables                        |
-| `modelMatrix`    | `Float32Array`               | slight tilt (default) | Initial 4×4 column-major model rotation matrix                              |
+| `gamutClip`      | `boolean`                    | `false`               | Discard out-of-sRGB-gamut pixels instead of clamping                         |
+| `modelMatrix`    | `Float32Array`               | slight tilt (default) | Initial 4×4 column-major model rotation matrix                               |
 
 ### Properties (3D)
 
@@ -369,13 +398,39 @@ All constructor options except `modelMatrix` are live setter/getters (re-render
 
 Additional properties:
 
-| Property      | Type           | Description                                                     |
-| ------------- | -------------- | --------------------------------------------------------------- |
-| `canvas`      | `HTMLCanvasElement` | The canvas (read-only)                                     |
-| `modelMatrix` | `Float32Array` | Get/set the 4×4 model rotation matrix (copies on read & write) |
+| Property      | Type                | Description                                                    |
+| ------------- | ------------------- | -------------------------------------------------------------- |
+| `canvas`      | `HTMLCanvasElement` | The canvas (read-only)                                         |
+| `modelMatrix` | `Float32Array`      | Get/set the 4×4 model rotation matrix (copies on read & write) |
 
 ### Methods (3D)
 
+#### `getColorAtUV(x, y)`
+
+Returns the rendered color at normalised screen coordinates (`0–1` on both axes, y=0 is top) as `[r, g, b]` in `0–1` sRGB, or `null` if the cursor is over a transparent pixel (i.e. outside the 3D geometry). Flushes any pending rAF frame so the reading is always current.
+
+```js
+canvas.addEventListener('mousemove', (e) => {
+  const rect = canvas.getBoundingClientRect();
+  const color = viz3d.getColorAtUV(
+    (e.clientX - rect.left) / rect.width,
+    (e.clientY - rect.top) / rect.height,
+  );
+  if (color) {
+    const hex =
+      '#' +
+      color
+        .map((c) =>
+          Math.round(c * 255)
+            .toString(16)
+            .padStart(2, '0'),
+        )
+        .join('');
+    console.log(hex);
+  }
+});
+```
+
 #### `rotate(dx, dy)`
 
 Apply an incremental trackball rotation. `dx` and `dy` are in radians (screen-space). Left-multiplies incremental X/Y rotations onto the accumulated model matrix.
@@ -413,13 +468,13 @@ const model = mat4Multiply(mat4RotateX(0.4), mat4RotateY(0.6));
 viz3d.modelMatrix = model;
 ```
 
-| Function         | Signature                                              | Description                           |
-| ---------------- | ------------------------------------------------------ | ------------------------------------- |
-| `mat4Perspective`| `(fov, aspect, near, far) → Float32Array`              | Perspective projection matrix         |
-| `mat4Multiply`   | `(a, b) → Float32Array`                                | Matrix multiplication `a × b`         |
-| `mat4RotateX`    | `(angle) → Float32Array`                               | Rotation around X axis (radians)      |
-| `mat4RotateY`    | `(angle) → Float32Array`                               | Rotation around Y axis (radians)      |
-| `mat4Translate`  | `(x, y, z) → Float32Array`                             | Translation matrix                    |
+| Function          | Signature                                 | Description                      |
+| ----------------- | ----------------------------------------- | -------------------------------- |
+| `mat4Perspective` | `(fov, aspect, near, far) → Float32Array` | Perspective projection matrix    |
+| `mat4Multiply`    | `(a, b) → Float32Array`                   | Matrix multiplication `a × b`    |
+| `mat4RotateX`     | `(angle) → Float32Array`                  | Rotation around X axis (radians) |
+| `mat4RotateY`     | `(angle) → Float32Array`                  | Rotation around Y axis (radians) |
+| `mat4Translate`   | `(x, y, z) → Float32Array`                | Translation matrix               |
 
 ---
 

package/dist/palette-shader.d.ts

@@ -24,7 +24,7 @@ export declare const paletteToTexture: (palette: ColorList) => Uint8Array;
 
 export declare class PaletteViz {
     #private;
-    constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, axis, position, invertZ, showRaw, outlineWidth, gamutClip, }?: PaletteVizOptions);
+    constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, axis, position, invertAxes, showRaw, outlineWidth, gamutClip, }?: PaletteVizOptions);
     get canvas(): HTMLCanvasElement;
     get width(): number;
     get height(): number;
@@ -45,8 +45,8 @@ export declare class PaletteViz {
     get colorModel(): SupportedColorModels;
     set distanceMetric(metric: DistanceMetric);
     get distanceMetric(): DistanceMetric;
-    set invertZ(value: boolean);
-    get invertZ(): boolean;
+    set invertAxes(value: Axis[]);
+    get invertAxes(): Axis[];
     set showRaw(value: boolean);
     get showRaw(): boolean;
     set pixelRatio(value: number);
@@ -62,7 +62,13 @@ export declare class PaletteViz {
 
 export declare class PaletteViz3D {
     #private;
-    constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, invertZ, showRaw, outlineWidth, gamutClip, position, modelMatrix, }?: PaletteViz3DOptions);
+    constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, invertAxes, showRaw, outlineWidth, gamutClip, position, modelMatrix, }?: PaletteViz3DOptions);
+    /**
+     * Read the rendered colour at normalised screen coordinates (0–1, y=0 is top).
+     * Returns [r, g, b] in [0, 1], or null if the pixel is transparent (no geometry).
+     * Flushes any pending rAF frame to ensure the reading is up to date.
+     */
+    getColorAtUV(x: number, y: number): [number, number, number] | null;
     get canvas(): HTMLCanvasElement;
     get width(): number;
     get height(): number;
@@ -74,8 +80,8 @@ export declare class PaletteViz3D {
     get colorModel(): SupportedColorModels;
     set distanceMetric(metric: DistanceMetric);
     get distanceMetric(): DistanceMetric;
-    set invertZ(value: boolean);
-    get invertZ(): boolean;
+    set invertAxes(value: Axis[]);
+    get invertAxes(): Axis[];
     set showRaw(value: boolean);
     get showRaw(): boolean;
     set position(value: number);
@@ -100,7 +106,7 @@ export declare type PaletteViz3DOptions = {
     container?: HTMLElement;
     colorModel?: SupportedColorModels;
     distanceMetric?: DistanceMetric;
-    invertZ?: boolean;
+    invertAxes?: Axis[];
     showRaw?: boolean;
     outlineWidth?: number;
     gamutClip?: boolean;
@@ -118,7 +124,7 @@ export declare type PaletteVizOptions = {
     distanceMetric?: DistanceMetric;
     axis?: Axis;
     position?: number;
-    invertZ?: boolean;
+    invertAxes?: Axis[];
     showRaw?: boolean;
     outlineWidth?: number;
     gamutClip?: boolean;
@@ -126,6 +132,6 @@ export declare type PaletteVizOptions = {
 
 export declare const randomPalette: (size?: number) => ColorList;
 
-export declare type SupportedColorModels = 'rgb' | 'oklab' | 'okhsv' | 'okhsvPolar' | 'okhsl' | 'okhslPolar' | 'oklch' | 'oklchPolar' | 'hsv' | 'hsvPolar' | 'hsl' | 'hslPolar' | 'hwb' | 'hwbPolar' | 'oklrab' | 'oklrch' | 'oklrchPolar' | 'cielab' | 'cielch' | 'cielchPolar' | 'cielabD50' | 'cielchD50' | 'cielchD50Polar';
+export declare type SupportedColorModels = 'rgb' | 'rgb12bit' | 'rgb8bit' | 'rgb18bit' | 'rgb6bit' | 'rgb15bit' | 'oklab' | 'okhsv' | 'okhsvPolar' | 'okhsl' | 'okhslPolar' | 'oklch' | 'oklchPolar' | 'hsv' | 'hsvPolar' | 'hsl' | 'hslPolar' | 'hwb' | 'hwbPolar' | 'oklrab' | 'oklrch' | 'oklrchPolar' | 'cielab' | 'cielch' | 'cielchPolar' | 'cielabD50' | 'cielchD50' | 'cielchD50Polar';
 
 export { }