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, 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'.
  algorithm?: 'dbscan' | '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');

Contributing

Contributions are welcome! For detailed information on how to contribute, please refer to the CONTRIBUTING guidelines.

License

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