@mkbabb/value.js 0.5.0 → 0.10.0

package/dist/quantize/cluster.d.ts

@@ -0,0 +1,45 @@
+import { rawOklabToOklch, oklabToRgb255 } from '../units/color/gamut';
+export { rawOklabToOklch, oklabToRgb255 };
+/** Chroma-weighted squared distance in OKLab */
+export declare function chromaDistSq(L1: number, a1: number, b1: number, L2: number, a2: number, b2: number, kC: number): number;
+/** Format OKLCH as CSS string */
+export declare function oklchToCss(L: number, C: number, H: number): string;
+/**
+ * Median-cut quantization in OKLab space.
+ *
+ * Iteratively splits pixel buckets along the axis of greatest range
+ * until `targetBuckets` clusters are reached. Returns each bucket's
+ * centroid (mean L, a, b) and population count.
+ */
+export declare function medianCutOKLab(allPixels: Float64Array, pixelCount: number, targetBuckets: number): {
+    centroid: [number, number, number];
+    population: number;
+}[];
+/**
+ * Select k seed centroids from MMCQ output using D²-weighted sampling
+ * (Arthur & Vassilvitskii, 2007). The first seed is the most populated
+ * MMCQ bucket; subsequent seeds are chosen with probability proportional
+ * to chroma-weighted squared distance × population.
+ */
+export declare function kmeansPlusPlusInit(centroids: {
+    centroid: [number, number, number];
+    population: number;
+}[], k: number, kC: number): [number, number, number][];
+/**
+ * Standard Lloyd's algorithm with chroma-weighted distance.
+ * Runs until centroids converge (shift < 1e-10) or `maxIterations` is reached.
+ * Returns final centroids and per-cluster pixel populations.
+ */
+export declare function kmeansIterate(pixels: Float64Array, pixelCount: number, seeds: [number, number, number][], maxIterations: number, kC: number): {
+    centroids: [number, number, number][];
+    populations: number[];
+};
+/**
+ * Merge centroids whose deltaE_OK falls below `threshold` (the JND).
+ * Merged centroids are population-weighted averages. This collapses
+ * clusters that k-means settled into the same perceptual neighborhood.
+ */
+export declare function deduplicateCentroids(centroids: [number, number, number][], populations: number[], threshold: number): {
+    centroids: [number, number, number][];
+    populations: number[];
+};

package/dist/quantize/index.d.ts

@@ -0,0 +1,14 @@
+import { QuantizeOptions, QuantizedColor } from './types';
+export type { QuantizeOptions, QuantizedColor } from './types';
+/**
+ * Quantize image pixels to a palette of K colors in OKLab space.
+ *
+ * Pipeline: downsample → sRGB→OKLab → MMCQ seed → k-means++ init →
+ * k-means refine → dedupe → perceptual sort
+ */
+export declare function quantizePixels(pixels: Uint8ClampedArray, width: number, height: number, options?: Partial<QuantizeOptions>): QuantizedColor[];
+/**
+ * Extract the single dominant color from an image.
+ * Runs k=5 quantization and returns the centroid with highest OKLCH chroma.
+ */
+export declare function dominantColor(pixels: Uint8ClampedArray, width: number, height: number): QuantizedColor | null;

package/dist/quantize/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Types and defaults for OKLab-native color quantization.
+ *
+ * The quantizer operates entirely in OKLab for perceptual uniformity,
+ * then converts results to OKLCH, sRGB, and CSS on output.
+ */
+export interface QuantizeOptions {
+    /** Number of palette colors to extract (default 5, clamped to [1, 16]). */
+    k: number;
+    /** Maximum k-means refinement iterations before convergence cutoff (default 10). */
+    maxIterations: number;
+    /** Downsample target: images are subsampled to approximately this many pixels (default 20,000). */
+    targetPixels: number;
+    /**
+     * Chroma weight (kC) for the distance metric.
+     * Scales the chromatic (a, b) axes relative to lightness:
+     *   d² = ΔL² + (1 + kC·C)·(Δa² + Δb²)
+     * Higher values bias clustering toward hue/chroma distinctions (default 0.5).
+     */
+    chromaWeight: number;
+    /**
+     * Minimum deltaE_OK between centroids; pairs below this threshold are
+     * merged as perceptually indistinguishable. Defaults to the JND (~0.02).
+     */
+    dedupeThreshold: number;
+}
+export interface QuantizedColor {
+    /** OKLab triplet [L, a, b]. L ∈ [0, 1]; a, b ∈ approx [-0.4, 0.4]. */
+    oklab: [number, number, number];
+    /** OKLCH triplet [L, C, H]. L ∈ [0, 1]; C ≥ 0; H ∈ [0, 360). */
+    oklch: [number, number, number];
+    /** Gamma-encoded sRGB triplet, each channel ∈ [0, 255]. */
+    rgb: [number, number, number];
+    /** CSS `oklch()` string, ready for stylesheet injection. */
+    css: string;
+    /** Pixel count assigned to this cluster (after downsampling). */
+    population: number;
+}
+export declare const DEFAULTS: QuantizeOptions;