palette-shader 0.13.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # palette-shader
 
-A dependency-free WebGL2 shader that maps any color palette across a 3-D perceptual color space and snaps each pixel to the nearest palette color. Visualize how a palette distributes across 20+ color models and eight distance metrics, all on the GPU. Includes 2-D cross-section views (`PaletteViz`) and an interactive 3-D cube/cylinder view (`PaletteViz3D`) with trackball rotation.
+A dependency-free WebGL2 shader that maps any color palette across a 3-D perceptual color space and snaps each pixel to the nearest palette color. Visualize how a palette distributes across 30+ color models and ten distance metrics, all on the GPU. Includes 2-D cross-section views (`PaletteViz`) and an interactive 3-D cube/cylinder view (`PaletteViz3D`) with trackball rotation.
 
 [**Live demo →**](https://meodai.github.io/color-palette-shader/)
 
@@ -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
@@ -65,21 +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). |
-| `gamutClip`      | `boolean`                    | `false`            | Discard out-of-sRGB-gamut pixels instead of clamping. Reveals the true gamut boundary of the color model.    |
+| 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.                                                              |
 
 ---
 
@@ -96,7 +109,7 @@ viz.palette = [
 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
@@ -178,14 +191,16 @@ Controls the 3-D color space the visualization is rendered in. Polar variants (`
 
 **OK — Lab / LCH**
 
-| Value           | Shape | Description                                                                          |
-| --------------- | ----- | ------------------------------------------------------------------------------------ |
-| `'oklab'`       | cube  | Raw OKLab: x→a, y→b, z→L.                                                            |
-| `'oklch'`       | cube  | OKLab in cylindrical LCH coordinates. Ideal for chroma or lightness slices.          |
-| `'oklchPolar'`  | wheel | Polar form of OKLch.                                                                 |
-| `'oklrab'`      | cube  | OKLab with toe-corrected lightness (Lr). Better perceptual uniformity in dark tones. |
-| `'oklrch'`      | cube  | OKLrab in cylindrical LCH coordinates.                                               |
-| `'oklrchPolar'` | wheel | Polar form of OKLrch.                                                                |
+| Value            | Shape    | Description                                                                          |
+| ---------------- | -------- | ------------------------------------------------------------------------------------ |
+| `'oklab'`        | cube     | Raw OKLab: x→a, y→b, z→L.                                                            |
+| `'oklch'`        | cube     | OKLab in cylindrical LCH coordinates. Ideal for chroma or lightness slices.          |
+| `'oklchPolar'`   | wheel    | Polar form of OKLch.                                                                 |
+| `'oklchDiag'`    | diagonal | Complementary hue plane: lightness on the diagonal, signed chroma on the anti-diagonal. Two opposite hues share the same view — no gray band in the middle. |
+| `'oklrab'`       | cube     | OKLab with toe-corrected lightness (Lr). Better perceptual uniformity in dark tones. |
+| `'oklrch'`       | cube     | OKLrab in cylindrical LCH coordinates.                                               |
+| `'oklrchPolar'`  | wheel    | Polar form of OKLrch.                                                                |
+| `'oklrchDiag'`   | diagonal | Complementary hue plane in OKLrch. Same diagonal layout as `oklchDiag` with toe-corrected lightness. |
 
 **CIE Lab / LCH — D65**
 
@@ -215,6 +230,22 @@ Controls the 3-D color space the visualization is rendered in. Polar variants (`
 | `'hwbPolar'` | wheel | Polar form of HWB.                                   |
 | `'rgb'`      | cube  | Raw sRGB cube. Useful as a baseline.                 |
 
+**Quantized RGB**
+
+| Value        | Shape | Description                                                      |
+| ------------ | ----- | ---------------------------------------------------------------- |
+| `'rgb6bit'`  | cube  | 2-bit per channel (64 colors). Game Boy–era palettes.            |
+| `'rgb8bit'`  | cube  | 3-3-2 bit (256 colors). CGA-style quantization.                 |
+| `'rgb12bit'` | cube  | 4-bit per channel (4096 colors). Amiga / NTSC.                  |
+| `'rgb15bit'` | cube  | 5-bit per channel (32768 colors). SVGA HiColor.                 |
+| `'rgb18bit'` | cube  | 6-bit per channel (262144 colors). VGA.                          |
+
+**Spectral**
+
+| Value        | Shape | Description                                                                                                                                                     |
+| ------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'spectrum'` | cube  | Visible light wavelengths (410–665 nm) plus purple line, modulated in OKLab. Inspired by censor's SpectroBoxWidget. X→wavelength, Y→lightness, Z→chroma scale. |
+
 The OK-variants rely on Björn Ottosson's gamut-aware implementation and produce significantly more even hue distributions than the classic variants at the same GPU cost.
 
 ### Cube vs. polar — which to use?
@@ -235,10 +266,12 @@ Controls how "nearest palette color" is determined per pixel.
 
 **OK**
 
-| Value      | Description                                                                                             | Cost |
-| ---------- | ------------------------------------------------------------------------------------------------------- | ---- |
-| `'oklab'`  | **Default.** Euclidean distance in OKLab. Fast, perceptually uniform, excellent general-purpose choice. | low  |
-| `'oklrab'` | Euclidean in OKLab with toe-corrected lightness. Slightly better uniformity in dark tones than OKLab.   | low  |
+| Value           | Description                                                                                             | Cost |
+| --------------- | ------------------------------------------------------------------------------------------------------- | ---- |
+| `'oklab'`       | **Default.** Euclidean distance in OKLab. Fast, perceptually uniform, excellent general-purpose choice. | low  |
+| `'oklrab'`      | Euclidean in OKLab with toe-corrected lightness. Slightly better uniformity in dark tones than OKLab.   | low  |
+| `'okLightness'` | Absolute lightness difference in OKLab (`|ΔL|`). Ignores hue and chroma — groups by brightness only.   | low  |
+| `'liMatch'`     | Spatially varying blend: full OKLab distance at the left edge, pure lightness match at the right. Inspired by censor's li-match. Useful for visualising tonal structure. | low  |
 
 **CIE — D65**
 
@@ -373,7 +406,7 @@ 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                        |
 | `gamutClip`      | `boolean`                    | `false`               | Discard out-of-sRGB-gamut pixels instead of clamping                         |

package/dist/palette-shader.d.ts

@@ -4,7 +4,7 @@ export declare type ColorList = ColorRGB[];
 
 export declare type ColorRGB = [number, number, number];
 
-export declare type DistanceMetric = 'rgb' | 'oklab' | 'deltaE76' | 'deltaE94' | 'deltaE2000' | 'kotsarenkoRamos' | 'oklrab' | 'cielabD50';
+export declare type DistanceMetric = 'rgb' | 'oklab' | 'deltaE76' | 'deltaE94' | 'deltaE2000' | 'kotsarenkoRamos' | 'oklrab' | 'cielabD50' | 'okLightness' | 'liMatch';
 
 export declare const fragmentShader: string;
 
@@ -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,7 @@ 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).
@@ -80,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);
@@ -106,7 +106,7 @@ export declare type PaletteViz3DOptions = {
     container?: HTMLElement;
     colorModel?: SupportedColorModels;
     distanceMetric?: DistanceMetric;
-    invertZ?: boolean;
+    invertAxes?: Axis[];
     showRaw?: boolean;
     outlineWidth?: number;
     gamutClip?: boolean;
@@ -124,7 +124,7 @@ export declare type PaletteVizOptions = {
     distanceMetric?: DistanceMetric;
     axis?: Axis;
     position?: number;
-    invertZ?: boolean;
+    invertAxes?: Axis[];
     showRaw?: boolean;
     outlineWidth?: number;
     gamutClip?: boolean;
@@ -132,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' | 'spectrum' | 'oklchDiag' | 'oklrchDiag';
 
 export { }