Image Palette

Extract color palettes from images using different algorithms. Works in both browser and Node.js.

Installation

npm install @jimmyclchu/image-palette

For Node.js, you'll also need canvas:

npm install canvas

Quick Start

import { extractPalette } from '@jimmyclchu/image-palette';

// Basic usage
const colors = await extractPalette('path/to/image.jpg');
console.log(colors); // ['#ff5733', '#33ff57', '#3357ff', ...]

// With options
const palette = await extractPalette(imageFile, {
  colorCount: 8,
  algorithm: 'k-means',
  format: 'rgb'
});

Algorithms

• median-cut (default) - Fast and reliable
• k-means - Higher quality, slower
• octree - Good color diversity
• dominant - Simple frequency-based extraction

Options

{
  colorCount: 5,           // Number of colors to extract
  algorithm: 'median-cut', // Algorithm to use
  format: 'hex',           // 'hex', 'rgb', or 'hsl'
  preset: 'custom',        // 'fast', 'quality', or 'custom'
  
  // K-means specific
  seed: 42,                // For reproducible results
  iterations: 50,          // Number of iterations
  
  // Filtering
  filters: {
    minDistance: 0.1,      // Minimum color difference (0-1)
    excludeDark: 0.2,      // Exclude colors darker than threshold
    excludeLight: 0.8,     // Exclude colors lighter than threshold
    excludeGrayscale: true // Remove grayscale colors
  },
  
  // Output
  includeMetadata: false   // Include frequency and pixel count data
}

Input Types

Browser:

• HTMLImageElement
• HTMLCanvasElement
• File / Blob
• Base64 strings
• Image URLs

Node.js:

• File paths
• Buffer objects
• Base64 strings

Examples

Different Output Formats

// Hex colors (default)
const hex = await extractPalette(image, { format: 'hex' });
// ['#ff5733', '#33ff57', '#3357ff']

// RGB objects
const rgb = await extractPalette(image, { format: 'rgb' });
// [{ r: 255, g: 87, b: 51 }, { r: 51, g: 255, b: 87 }]

// HSL objects
const hsl = await extractPalette(image, { format: 'hsl' });
// [{ h: 9, s: 100, l: 60 }, { h: 129, s: 100, l: 60 }]

With Metadata

const palette = await extractPalette(image, { 
  includeMetadata: true,
  colorCount: 5
});

console.log(palette);
// [
//   { color: '#ff5733', frequency: 0.34, pixels: 1247 },
//   { color: '#33ff57', frequency: 0.28, pixels: 1031 },
//   ...
// ]

Performance Presets

// Fast extraction
const fastColors = await extractPalette(image, { preset: 'fast' });

// Higher quality
const qualityColors = await extractPalette(image, { preset: 'quality' });

Advanced Filtering

const filtered = await extractPalette(image, {
  colorCount: 10,
  filters: {
    minDistance: 0.15,     // Colors must be 15% different
    excludeDark: 0.1,      // No very dark colors
    excludeLight: 0.9,     // No very light colors
    excludeGrayscale: true // No gray colors
  }
});

Browser File Upload

const input = document.querySelector('input[type="file"]');
input.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const colors = await extractPalette(file, { colorCount: 6 });
  console.log(colors);
});

Node.js File Processing

import { extractPalette } from '@jimmyclchu/image-palette';
import fs from 'fs';

// From file path
const colors1 = await extractPalette('./photo.jpg');

// From buffer
const buffer = fs.readFileSync('./photo.png');
const colors2 = await extractPalette(buffer);

License

MIT