palette-shader 0.16.0 → 0.18.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 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.
+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 eleven 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/)
 
@@ -59,6 +59,7 @@ const viz = new PaletteViz({
   container: document.querySelector('#app'),
   width: 512,
   height: 512,
+  observeResize: false,
 });
 
 // option B — no container, place the canvas yourself
@@ -78,21 +79,22 @@ 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                                                                                                                                     |
-| `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.                                                              |
+| 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                                                                                                                                                                                 |
+| `observeResize`  | `boolean`                    | `false`            | When `true`, a `ResizeObserver` tracks the laid-out canvas size and updates the backing resolution to match CSS layout. When `false`, `width` and `height` are treated as the explicit display size. |
+| `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.                                                                                            |
 
 ---
 
@@ -116,6 +118,12 @@ viz.gamutClip = true; // discard out-of-gamut pixels
 viz.pixelRatio = window.devicePixelRatio; // update after display changes
 ```
 
+Sizing model:
+
+- By default, `width` and `height` are the explicit display size and backing resolution source.
+- If you want normal CSS layout to control the canvas size, set `observeResize: true` and style the canvas or its container in CSS.
+- `pixelRatio` only affects backing resolution, not layout size.
+
 Additional read-only properties:
 
 | Property | Type                | Description                   |
@@ -174,6 +182,33 @@ Returns the current shader result at normalized UV coordinates (`0–1` on both
 const color = viz.getColorAtUV(0.5, 0.5); // center
 ```
 
+### `getColorAtUV_float(x, y)`
+
+Returns the color at normalized UV coordinates as `[r, g, b]` in **unclamped linear RGB** with full float precision. Unlike `getColorAtUV`, values are not quantized to 8-bit and are not clamped to `[0, 1]` — out-of-gamut colors preserve their original value. The sRGB transfer function is bypassed so the consumer receives linear-light values suitable for further color-space conversions without double-gamma.
+
+Renders a single pixel on demand into a 1×1 `RGBA16F` framebuffer — zero per-frame cost.
+
+```js
+const [r, g, b] = viz.getColorAtUV_float(0.5, 0.5);
+// r, g, b are linear RGB — may be < 0 or > 1 for out-of-gamut colors
+```
+
+Converting to OKLab (or any other color space) with [culori](https://culorijs.org/):
+
+```js
+import { converter, formatCss } from 'culori';
+
+const toOklab = converter('oklab');
+const [r, g, b] = viz.getColorAtUV_float(0.5, 0.5);
+
+// Feed linear RGB directly into culori's linear-sRGB mode
+const oklab = toOklab({ mode: 'lrgb', r, g, b });
+// → { mode: 'oklab', l: 0.72, a: 0.08, b: 0.12 }
+
+formatCss(oklab);
+// → 'oklab(0.72 0.08 0.12)'
+```
+
 ---
 
 ## Color models
@@ -218,6 +253,13 @@ Controls the 3-D color space the visualization is rendered in. Polar variants (`
 | `'cielchD50'`      | cube  | CIELab D50 in cylindrical LCH coordinates.               |
 | `'cielchD50Polar'` | wheel | Polar form of CIELch D50.                                |
 
+**CAM16-UCS — D65**
+
+| Value                | Shape | Description                                                                            |
+| -------------------- | ----- | -------------------------------------------------------------------------------------- |
+| `'cam16ucsD65'`      | cube  | CAM16-UCS under fixed D65 CAT16 viewing conditions, rendered with an analytic inverse. |
+| `'cam16ucsD65Polar'` | wheel | Polar CAM16-UCS view under the same fixed D65 conditions.                              |
+
 **Classic**
 
 | Value        | Shape | Description                                          |
@@ -264,14 +306,15 @@ A practical starting point: use a **polar** model to get an intuitive read on hu
 
 Controls how "nearest palette color" is determined per pixel.
 
-**OK**
+**OK / appearance-inspired**
 
-| 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  |
+| 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, so regions are grouped 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.           | low  |
+| `'cam16ucsD65'` | Euclidean distance in CAM16-UCS under fixed D65 CAT16 viewing conditions. Useful when you want a full appearance-model metric like censor. | high |
 
 **CIE — D65**
 

package/dist/palette-shader.d.ts

@@ -1,10 +1,66 @@
 export declare type Axis = 'x' | 'y' | 'z';
 
+declare abstract class BasePaletteRenderer {
+    protected paletteState: ColorList;
+    protected cssWidth: number;
+    protected cssHeight: number;
+    protected pixelRatioState: number;
+    protected readonly canvasElement: HTMLCanvasElement;
+    protected readonly glContext: WebGL2RenderingContext;
+    protected readonly paletteTexture: WebGLTexture;
+    protected readonly metricTexture: WebGLTexture;
+    protected metricPaletteDirty: boolean;
+    protected animationFrameId: number | null;
+    protected destroyed: boolean;
+    protected readonly containerElement?: HTMLElement;
+    protected readonly observeResize: boolean;
+    protected resizeObserver: ResizeObserver | null;
+    protected constructor({ palette, width, height, pixelRatio, observeResize, container, canvasClassName, }: BaseRendererOptions);
+    protected normalizeInvertAxes(axes: Axis[]): Axis[];
+    protected syncCanvasSize(width: number, height: number): {
+        pw: number;
+        ph: number;
+    };
+    protected syncCanvasSizeFromLayout(): {
+        pw: number;
+        ph: number;
+        width: number;
+        height: number;
+    };
+    protected schedulePaint(): void;
+    protected flushScheduledPaint(): void;
+    protected uploadMetricPalette(paletteSizeUniform: WebGLUniformLocation | null): void;
+    protected attachCanvas(): void;
+    protected beginDestroy(): boolean;
+    protected destroyBaseResources(): void;
+    protected onSurfaceResized(_pw: number, _ph: number): void;
+    protected abstract currentMetricCode(): number;
+    protected abstract renderFrame(): void;
+    get canvas(): HTMLCanvasElement;
+    get width(): number;
+    get height(): number;
+    resize(width: number, height?: number | null): void;
+    set palette(palette: ColorList);
+    get palette(): ColorList;
+    set pixelRatio(value: number);
+    get pixelRatio(): number;
+}
+
+declare type BaseRendererOptions = {
+    palette: ColorList;
+    width: number;
+    height: number;
+    pixelRatio: number;
+    observeResize: boolean;
+    container?: HTMLElement;
+    canvasClassName: string;
+};
+
 export declare type ColorList = ColorRGB[];
 
 export declare type ColorRGB = [number, number, number];
 
-export declare type DistanceMetric = 'rgb' | 'oklab' | 'deltaE76' | 'deltaE94' | 'deltaE2000' | 'kotsarenkoRamos' | 'oklrab' | 'cielabD50' | 'okLightness' | 'liMatch';
+export declare type DistanceMetric = 'rgb' | 'oklab' | 'deltaE76' | 'deltaE94' | 'deltaE2000' | 'kotsarenkoRamos' | 'oklrab' | 'cielabD50' | 'okLightness' | 'liMatch' | 'cam16ucsD65';
 
 export declare const fragmentShader: string;
 
@@ -22,21 +78,19 @@ export declare const paletteToRGBA: (palette: ColorList) => Uint8Array;
 
 export declare const paletteToTexture: (palette: ColorList) => Uint8Array;
 
-export declare class PaletteViz {
+export declare class PaletteViz extends BasePaletteRenderer {
     #private;
-    constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, axis, position, invertAxes, showRaw, outlineWidth, gamutClip, }?: PaletteVizOptions);
-    get canvas(): HTMLCanvasElement;
-    get width(): number;
-    get height(): number;
-    resize(width: number, height?: number | null): void;
+    constructor({ palette, width, height, pixelRatio, observeResize, container, colorModel, distanceMetric, axis, position, invertAxes, showRaw, outlineWidth, gamutClip, }?: PaletteVizOptions);
+    protected currentMetricCode(): number;
+    protected onSurfaceResized(pw: number, ph: number): void;
+    protected renderFrame(): void;
     destroy(): void;
-    set palette(palette: ColorList);
-    get palette(): ColorList;
     setColor(color: ColorRGB, index: number): void;
     addColor(color: ColorRGB, index?: number): void;
     removeColor(index: number): void;
     removeColor(color: ColorRGB): void;
     getColorAtUV(x: number, y: number): ColorRGB;
+    getColorAtUV_float(x: number, y: number): ColorRGB;
     set position(value: number);
     get position(): number;
     set axis(axis: Axis);
@@ -49,8 +103,6 @@ export declare class PaletteViz {
     get invertAxes(): Axis[];
     set showRaw(value: boolean);
     get showRaw(): boolean;
-    set pixelRatio(value: number);
-    get pixelRatio(): number;
     set gamutClip(value: boolean);
     get gamutClip(): boolean;
     set outlineWidth(value: number);
@@ -60,22 +112,15 @@ export declare class PaletteViz {
     static paletteToTexture: (palette: ColorList) => Uint8Array;
 }
 
-export declare class PaletteViz3D {
+export declare class PaletteViz3D extends BasePaletteRenderer {
     #private;
-    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.
-     */
+    constructor({ palette, width, height, pixelRatio, observeResize, container, colorModel, distanceMetric, invertAxes, showRaw, outlineWidth, gamutClip, position, modelMatrix, }?: PaletteViz3DOptions);
+    protected currentMetricCode(): number;
+    protected onSurfaceResized(pw: number, ph: number): void;
+    protected renderFrame(): void;
     getColorAtUV(x: number, y: number): [number, number, number] | null;
-    get canvas(): HTMLCanvasElement;
-    get width(): number;
-    get height(): number;
     resize(width: number, height?: number | null): void;
     destroy(): void;
-    set palette(palette: ColorList);
-    get palette(): ColorList;
     set colorModel(model: SupportedColorModels);
     get colorModel(): SupportedColorModels;
     set distanceMetric(metric: DistanceMetric);
@@ -86,9 +131,8 @@ export declare class PaletteViz3D {
     get showRaw(): boolean;
     set position(value: number);
     get position(): number;
-    /** Apply an incremental spherical rotation (screen-space dx/dy in radians). */
     rotate(dx: number, dy: number): void;
-    set modelMatrix(m: Float32Array);
+    set modelMatrix(matrix: Float32Array);
     get modelMatrix(): Float32Array;
     set gamutClip(value: boolean);
     get gamutClip(): boolean;
@@ -103,6 +147,7 @@ export declare type PaletteViz3DOptions = {
     width?: number;
     height?: number;
     pixelRatio?: number;
+    observeResize?: boolean;
     container?: HTMLElement;
     colorModel?: SupportedColorModels;
     distanceMetric?: DistanceMetric;
@@ -119,6 +164,7 @@ export declare type PaletteVizOptions = {
     width?: number;
     height?: number;
     pixelRatio?: number;
+    observeResize?: boolean;
     container?: HTMLElement;
     colorModel?: SupportedColorModels;
     distanceMetric?: DistanceMetric;
@@ -132,6 +178,6 @@ export declare type PaletteVizOptions = {
 
 export declare const randomPalette: (size?: number) => ColorList;
 
-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 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' | 'cam16ucsD65' | 'cam16ucsD65Polar' | 'spectrum' | 'oklchDiag' | 'oklrchDiag';
 
 export { }