Package Exports
- @instruments/colorscope
- @instruments/colorscope/accessibility
- @instruments/colorscope/analysis
- @instruments/colorscope/border
- @instruments/colorscope/convert
- @instruments/colorscope/embedding
- @instruments/colorscope/extraction
- @instruments/colorscope/format
- @instruments/colorscope/harmony
- @instruments/colorscope/isolation
- @instruments/colorscope/isolation/browser
- @instruments/colorscope/match
- @instruments/colorscope/math
- @instruments/colorscope/mood
- @instruments/colorscope/naming
- @instruments/colorscope/naming/semantic
- @instruments/colorscope/naming/server
- @instruments/colorscope/palette
- @instruments/colorscope/sorting
- @instruments/colorscope/temperature
- @instruments/colorscope/tolerance
- @instruments/colorscope/types
Readme
colorscope
Color extraction, analysis, and harmony generation for Node.js and the browser.
Current release
0.13.0 is a breaking release for stored embedding indexes. paletteToEmbedding()
now emits one fixed 128D perceptual distribution vector for single colors and
palettes. Rebuild material, palette, and catalog vectors created by older
embedding layouts, and store EMBEDDING_VERSION next to each persisted vector.
Access
@instruments/colorscope is currently distributed as a private package. This README
documents the API for internal consumers and repository work, but installation
requires the appropriate registry token and private registry access.
Usage
Extract colors from an image (Node.js only)
import { extractColorsFromBuffer } from "@instruments/colorscope/extraction";
import { readFile } from "node:fs/promises";
const buffer = await readFile("photo.jpg");
const { colors, background } = await extractColorsFromBuffer(buffer);Analyze a palette (browser-safe)
import { analyzePalette } from "@instruments/colorscope/analysis";
const analysis = analyzePalette(colors);
// { temperature, vibrancy, brightness, complexity, dominantFamily, mood }Generate harmonies (browser-safe)
import { generateHarmony } from "@instruments/colorscope/harmony";
const complementary = generateHarmony({ h: 200, s: 80, l: 50 }, "complementary");Sub-path imports
The barrel export (import from "@instruments/colorscope") pulls in sharp (Node-only native module). Client/browser code must use sub-path imports:
| Import | Purpose |
|---|---|
@instruments/colorscope/extraction |
Image color extraction (Node-only, requires sharp) |
@instruments/colorscope/border |
Image border detection (Node-only, requires sharp) |
@instruments/colorscope/isolation |
Isolation detection and uniform background removal (Node-only, requires sharp) |
@instruments/colorscope/isolation/browser |
Browser background removal with optional transformers peer dependency |
@instruments/colorscope/analysis |
Palette analysis (temperature, vibrancy, mood) |
@instruments/colorscope/embedding |
128D palette embeddings and cosine similarity |
@instruments/colorscope/match |
Match targets for palettes, names, images, and gradients |
@instruments/colorscope/palette |
Anchor palettes, palette grids, palette libraries, and palette search |
@instruments/colorscope/mood |
Mood regions, sliders, and browse targets |
@instruments/colorscope/sorting |
Palette sorting by hue and perceptual lightness |
@instruments/colorscope/temperature |
Temperature and lightness adjustment helpers |
@instruments/colorscope/tolerance |
UI tolerance sliders to perceptual thresholds |
@instruments/colorscope/harmony |
Harmony generation (complementary, analogous, triadic, etc.) |
@instruments/colorscope/convert |
Color space conversions (OKLab, OKLCH, HSL, RGB, hex) |
@instruments/colorscope/accessibility |
Contrast ratios, color blindness simulation |
@instruments/colorscope/naming |
Human-readable color names, color group search |
@instruments/colorscope/naming/semantic |
Hybrid lexical/semantic color resolver |
@instruments/colorscope/naming/server |
Server-side naming library loaders |
@instruments/colorscope/format |
Export palettes as CSS, Tailwind, or SCSS |
@instruments/colorscope/math |
Low-level color math (quantization, distance, conversions) |
@instruments/colorscope/types |
TypeScript types (QuantizedColor, HSL, OKLab, etc.) |
Key features
- Perceptual color science — OKLab/OKLCH color space throughout
- Smart extraction — background detection, JPEG artifact filtering, perceptual merging
- 10 harmony types — complementary, analogous, triadic, split-complementary, tetradic, and more
- Tonal palettes — Material Design-inspired tonal generation
- Accessibility — WCAG contrast ratios and color blindness simulation (protanopia, deuteranopia, tritanopia)
- 374 tests with vitest
License
MIT