palette-shader 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +30 -17
  2. package/dist/palette-shader.d.ts +9 -9
  3. package/dist/palette-shader.js +525 -408
  4. package/dist/palette-shader.js.map +1 -1
  5. package/dist/palette-shader.umd.cjs +110 -39
  6. package/dist/palette-shader.umd.cjs.map +1 -1
  7. package/package.json +1 -1
  8. package/src/PaletteViz.ts +49 -30
  9. package/src/PaletteViz3D.ts +55 -31
  10. package/src/mesh.ts +4 -4
  11. package/src/shaderSrc.ts +124 -44
  12. package/src/types.ts +7 -2
package/README.md CHANGED
@@ -16,6 +16,19 @@ So if one of your palette colors only claims a tiny sliver, it lives very close
16
16
  - **How balanced** the palette is overall — even regions mean even coverage
17
17
  - **Whether a new color is worth adding** — if it doesn't carve out its own space, it's probably not pulling its weight
18
18
 
19
+ ### Common questions → recommended settings
20
+
21
+ | I want to know… | Color model | Distance metric |
22
+ | ----------------------------------------- | ------------------------------- | --------------- |
23
+ | How my hue distribution looks | `okhslPolar` | `oklab` |
24
+ | Which two colors are most similar | `okhsl` or `oklab` | `deltaE2000` |
25
+ | Whether a new color is worth adding | `okhslPolar` | `oklab` |
26
+ | How my palette reads on print | `cielabD50` or `cielchD50Polar` | `cielabD50` |
27
+ | How close the colors look to a human eye | `oklchPolar` | `deltaE2000` |
28
+ | What the palette looks like to a computer | `hslPolar` or `rgb` | `rgb` |
29
+
30
+ For a deeper breakdown of every color model and metric, see [docs/use-cases.md](docs/use-cases.md).
31
+
19
32
  ---
20
33
 
21
34
  ## Install
@@ -65,21 +78,21 @@ new PaletteViz(options?: PaletteVizOptions)
65
78
 
66
79
  All options are optional. The palette defaults to a random 20-color set.
67
80
 
68
- | Option | Type | Default | Description |
69
- | ---------------- | ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
70
- | `palette` | `[number, number, number][]` | random | sRGB colors as `[r, g, b]` arrays, each component in the `0–1` range |
71
- | `container` | `HTMLElement` | `undefined` | Element the canvas is appended to. Omit and use `viz.canvas` to place it yourself |
72
- | `width` | `number` | `512` | Canvas width in CSS pixels |
73
- | `height` | `number` | `512` | Canvas height in CSS pixels |
74
- | `pixelRatio` | `number` | `devicePixelRatio` | Renderer pixel ratio |
75
- | `colorModel` | `string` | `'okhsv'` | Color space for the visualization (see [Color models](#color-models)) |
76
- | `distanceMetric` | `string` | `'oklab'` | Distance function for nearest-color matching (see [Distance metrics](#distance-metrics)) |
77
- | `axis` | `'x' \| 'y' \| 'z'` | `'y'` | Which axis the `position` value controls |
78
- | `position` | `number` | `0` | 0–1 position along the chosen axis |
79
- | `invertZ` | `boolean` | `false` | Flip the lightness/value axis |
80
- | `showRaw` | `boolean` | `false` | Bypass nearest-color matching (shows the raw color space) |
81
- | `outlineWidth` | `number` | `0` | Draw a transparent outline where palette regions meet. Width in physical pixels. `0` disables (no overhead). |
82
- | `gamutClip` | `boolean` | `false` | Discard out-of-sRGB-gamut pixels instead of clamping. Reveals the true gamut boundary of the color model. |
81
+ | Option | Type | Default | Description |
82
+ | ---------------- | ---------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
83
+ | `palette` | `[number, number, number][]` | random | sRGB colors as `[r, g, b]` arrays, each component in the `0–1` range |
84
+ | `container` | `HTMLElement` | `undefined` | Element the canvas is appended to. Omit and use `viz.canvas` to place it yourself |
85
+ | `width` | `number` | `512` | Canvas width in CSS pixels |
86
+ | `height` | `number` | `512` | Canvas height in CSS pixels |
87
+ | `pixelRatio` | `number` | `devicePixelRatio` | Renderer pixel ratio |
88
+ | `colorModel` | `string` | `'okhsv'` | Color space for the visualization (see [Color models](#color-models)) |
89
+ | `distanceMetric` | `string` | `'oklab'` | Distance function for nearest-color matching (see [Distance metrics](#distance-metrics)) |
90
+ | `axis` | `'x' \| 'y' \| 'z'` | `'y'` | Which axis the `position` value controls |
91
+ | `position` | `number` | `0` | 0–1 position along the chosen axis |
92
+ | `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. |
93
+ | `showRaw` | `boolean` | `false` | Bypass nearest-color matching (shows the raw color space) |
94
+ | `outlineWidth` | `number` | `0` | Draw a transparent outline where palette regions meet. Width in physical pixels. `0` disables (no overhead). |
95
+ | `gamutClip` | `boolean` | `false` | Discard out-of-sRGB-gamut pixels instead of clamping. Reveals the true gamut boundary of the color model. |
83
96
 
84
97
  ---
85
98
 
@@ -96,7 +109,7 @@ viz.palette = [
96
109
  viz.position = 0.5;
97
110
  viz.colorModel = 'okhslPolar';
98
111
  viz.distanceMetric = 'deltaE2000';
99
- viz.invertZ = true;
112
+ viz.invertAxes = ['z'];
100
113
  viz.showRaw = true;
101
114
  viz.outlineWidth = 2; // transparent border between regions, in physical pixels
102
115
  viz.gamutClip = true; // discard out-of-gamut pixels
@@ -373,7 +386,7 @@ new PaletteViz3D(options?: PaletteViz3DOptions)
373
386
  | `colorModel` | `string` | `'okhsv'` | Color model (see [Color models](#color-models)). Polar → cylinder mesh |
374
387
  | `distanceMetric` | `string` | `'oklab'` | Distance metric (see [Distance metrics](#distance-metrics)) |
375
388
  | `position` | `number` | `1` | 0–1 slice position. `1` shows the full volume; `0` slices it completely away |
376
- | `invertZ` | `boolean` | `false` | Flip the lightness/value axis |
389
+ | `invertAxes` | `('x' \| 'y' \| 'z')[]` | `[]` | Invert one or more axes, for example `['z']` or `['x', 'z']` |
377
390
  | `showRaw` | `boolean` | `false` | Bypass nearest-color matching |
378
391
  | `outlineWidth` | `number` | `0` | Transparent outline width (physical px). `0` disables |
379
392
  | `gamutClip` | `boolean` | `false` | Discard out-of-sRGB-gamut pixels instead of clamping |
package/dist/palette-shader.d.ts CHANGED
@@ -24,7 +24,7 @@ export declare const paletteToTexture: (palette: ColorList) => Uint8Array;
24
24
 
25
25
  export declare class PaletteViz {
26
26
  #private;
27
- constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, axis, position, invertZ, showRaw, outlineWidth, gamutClip, }?: PaletteVizOptions);
27
+ constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, axis, position, invertAxes, showRaw, outlineWidth, gamutClip, }?: PaletteVizOptions);
28
28
  get canvas(): HTMLCanvasElement;
29
29
  get width(): number;
30
30
  get height(): number;
@@ -45,8 +45,8 @@ export declare class PaletteViz {
45
45
  get colorModel(): SupportedColorModels;
46
46
  set distanceMetric(metric: DistanceMetric);
47
47
  get distanceMetric(): DistanceMetric;
48
- set invertZ(value: boolean);
49
- get invertZ(): boolean;
48
+ set invertAxes(value: Axis[]);
49
+ get invertAxes(): Axis[];
50
50
  set showRaw(value: boolean);
51
51
  get showRaw(): boolean;
52
52
  set pixelRatio(value: number);
@@ -62,7 +62,7 @@ export declare class PaletteViz {
62
62
 
63
63
  export declare class PaletteViz3D {
64
64
  #private;
65
- constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, invertZ, showRaw, outlineWidth, gamutClip, position, modelMatrix, }?: PaletteViz3DOptions);
65
+ constructor({ palette, width, height, pixelRatio, container, colorModel, distanceMetric, invertAxes, showRaw, outlineWidth, gamutClip, position, modelMatrix, }?: PaletteViz3DOptions);
66
66
  /**
67
67
  * Read the rendered colour at normalised screen coordinates (0–1, y=0 is top).
68
68
  * Returns [r, g, b] in [0, 1], or null if the pixel is transparent (no geometry).
@@ -80,8 +80,8 @@ export declare class PaletteViz3D {
80
80
  get colorModel(): SupportedColorModels;
81
81
  set distanceMetric(metric: DistanceMetric);
82
82
  get distanceMetric(): DistanceMetric;
83
- set invertZ(value: boolean);
84
- get invertZ(): boolean;
83
+ set invertAxes(value: Axis[]);
84
+ get invertAxes(): Axis[];
85
85
  set showRaw(value: boolean);
86
86
  get showRaw(): boolean;
87
87
  set position(value: number);
@@ -106,7 +106,7 @@ export declare type PaletteViz3DOptions = {
106
106
  container?: HTMLElement;
107
107
  colorModel?: SupportedColorModels;
108
108
  distanceMetric?: DistanceMetric;
109
- invertZ?: boolean;
109
+ invertAxes?: Axis[];
110
110
  showRaw?: boolean;
111
111
  outlineWidth?: number;
112
112
  gamutClip?: boolean;
@@ -124,7 +124,7 @@ export declare type PaletteVizOptions = {
124
124
  distanceMetric?: DistanceMetric;
125
125
  axis?: Axis;
126
126
  position?: number;
127
- invertZ?: boolean;
127
+ invertAxes?: Axis[];
128
128
  showRaw?: boolean;
129
129
  outlineWidth?: number;
130
130
  gamutClip?: boolean;
@@ -132,6 +132,6 @@ export declare type PaletteVizOptions = {
132
132
 
133
133
  export declare const randomPalette: (size?: number) => ColorList;
134
134
 
135
- 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';
135
+ 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';
136
136
 
137
137
  export { }