Auto Palette

Auto Palette is a library that automatically extracts a prominent color palette from your image.

Features

[!NOTE] Photo by Pixabay from Pexels: https://www.pexels.com/photo/yellow-pink-and-violet-tulips-52508/

❯ Automatically extracts color palette from image
❯ Provides detailed color information color, name, position and population
❯ Supports multiple color extraction algorithms (dbscan, kmeans )
❯ Supports multiple image sources (HTMLImageElement, HTMLCanvasElement, ImageData)
❯ Supports both Browser and Node.js
❯ Zero dependencies

Installation

Using npm:

$ npm install auto-palette

Using yarn:

$ yarn add auto-palette

Using pnpm:

$ pnpm add auto-palette

Usage

// ESM
import { Palette } from 'auto-palette';

// CJS
const { Palette } = require('auto-palette');

const palette = Palette.extract(image);
const swatches = palette.findSwatches(8, 'vivid');
for (const swatch of swatches) {
  console.log({
    name: swatch.name,              // The similar color name of the swatch
    color: swatch.color.toString(), // The color of the swatch
    position: swatch.position,      // The position of the swatch in the image
    population: swatch.population,  // The pixel count of the swatch
  });
}

Examples

Source Image	Default	Vivid	Muted

API

For more detailed information, please refer to the documentations in the docs directory.

Palette

extract(image: ImageSource, options?: Options): Palette

Extracts a color palette from the given image source(HTMLImageElement, HTMLCanvasElement or ImageData).
It takes an image source and an optional Options object as parameters.

const options: Options = {
  algorithm: 'dbscan',
  samplingRate: 0.5,
  maxSwatches: 16,
  filters: [luminanceFilter(0.2, 0.8)],
};
const palette = Palette.extract(image, options);

The Options can include properties such as algorithm, samplingRate, maxSwatches, and filters.

interface Options {
  // The color extraction algorithm to use. Default is 'dbscan'.
  algotithm?: 'dbscan' | 'kmeans';
  // The sampling rate of the image. Default is 1.0.
  samplingRate?: number;
  // The maximum number of swatches to extract. Default is 256.
  maxSwatches?: number;
  // The color filters to apply. Default is [opacityFilter()].
  filters?: ColorFilter[];
}

findSwatches(n: number, theme?: Theme): Swatch[]

Finds the best n swatches in the palette.
The “best” swatches are determined based on their population and optionally a theme. The theme can be basic, vivid, muted, light or dark. Default is basic.

const swatches = palette.findSwatches(5, 'light');

Development

Follow these steps to get started with development:

1. Fork and clone this repository
2. Install the latest LTS version of Node.js
3. Enable Corepack using corepack enable
4. Install dependencies using pnpm install
5. Run unit tests and watch for changes using pnpm dev

License

This library is distributed under the MIT License.See the LICENSE.