Comparison

Compare material palettes — find tiles that match a leather, sort a collection by similarity, or get a detailed breakdown of how two materials differ.

Reference Material

Sorted by Similarity

import { paletteDistance, sortByDistance, compareImages } from "colorscope/analysis";

Functions

paletteDistance

Calculate perceptual distance between two palettes.

function paletteDistance(
  a: readonly QuantizedColor[],
  b: readonly QuantizedColor[]
): number

Combines color distance (60% — symmetric min OKLab matching) and distribution distance (40% — proportion-weighted centroid difference). Returns ≥ 0, typical range 0-1.

paletteDistance(leatherPalette, walnutPalette); // 0.08 — very similar
paletteDistance(leatherPalette, slatePalette);  // 0.45 — quite different

sortByDistance

Sort palettes by distance to a target.

function sortByDistance(
  target: readonly QuantizedColor[],
  palettes: readonly (readonly QuantizedColor[])[]
): Array<{ palette: readonly QuantizedColor[]; distance: number }>

Returns: New array sorted closest-first with distance values.

const matches = sortByDistance(leatherPalette, [
  walnutPalette, marblePalette, slatePalette, tilePalette,
]);
// → [{ palette: walnut, distance: 0.08 }, { palette: tile, distance: 0.18 }, ...]

compareImages

Compare two images' color palettes with a multi-dimensional similarity report.

function compareImages(
  colorsA: readonly QuantizedColor[],
  colorsB: readonly QuantizedColor[]
): ImageComparisonResult

Returns: Overall distance, mood matching, brightness and vibrancy differences.

const comparison = compareImages(leatherPalette, slatePalette);
// {
//   distance: 0.45,
//   moodMatch: false,       // muted vs monochrome
//   brightnessDiff: 0.27,
//   vibrancyDiff: 0.57,
// }

Types

ImageComparisonResult

interface ImageComparisonResult {
  distance: number;       // Overall perceptual distance (0 = identical)
  moodMatch: boolean;     // Whether palettes share similar mood
  brightnessDiff: number; // Brightness difference (0-1)
  vibrancyDiff: number;   // Vibrancy difference (0-1)
}