Dominant Color

This is a JavaScript library that allows you to extract the dominant color from images. It provides an easy-to-use interface to get started quickly.

Installation

To install the library, use the following command:

npm i @rtcoder/dominant-color

Usage

Import the getDominantColor or getDominantColorAsync function from @rtcoder/dominant-color in your JavaScript file:

import { getDominantColor, getDominantColorAsync } from "@rtcoder/dominant-color";

Select an image source:

const img = document.querySelector('img');

Call the getDominantColor function with the image element and configuration options:

getDominantColor(img, {
    downScaleFactor: 1,
    skipPixels: 0,
    colorsPaletteLength: 5,
    colorBucketSize: 24,
    colorGroupingThreshold: 0,
    colorQuantization: 'exact',
    paletteWithCountOfOccurrences: false,
    colorFormat: 'rgb',
    callback: (color, palette) => {
        // Your code here
    },
    errorCallback: (error) => {
        // Handle image loading or canvas errors here
    }
});

You can also use the Promise-based API:

const { dominant, colorsPalette } = await getDominantColorAsync(img, {
    colorFormat: 'hex',
    colorQuantization: 'median-cut'
});

Image sources can be an HTMLImageElement, HTMLCanvasElement, ImageBitmap, image URL string, Blob, or File.

Configuration Options

The getDominantColor and getDominantColorAsync functions accept the following configuration options:

| Name | Type | Default Value | Description | | --------------------------- | -------- | ------------- | ------------------------------------------------------------ | | downScaleFactor | number | 1 | Factor of scale down for the image. Recommended for large images. | | skipPixels | number | 0 | Skips every n pixels while determining the dominant color. Recommended for large images. | | colorsPaletteLength | number | 5 | Length of the returned color palette. | | colorBucketSize | number | 24 | RGB bucket size used when colorQuantization is 'bucket'. Smaller values keep more detail; larger values merge more colors. | | colorGroupingThreshold | number | 0 | Groups similar RGB colors before sorting. Use 0 for exact pixel matching, or a larger value such as 10-30 for photos. | | colorQuantization | string | 'exact' | Defines the color counting algorithm. Use 'exact' for exact RGB matching, 'bucket' for fast grouped palettes, or 'median-cut' for more balanced photo palettes. | | paletteWithCountOfOccurrences | boolean | false | Determines whether to return colors with the number of occurrences. | | colorFormat | string | 'rgb' | Defines the format of the returned dominant color and palette colors. Available values are 'rgb', 'hsl', and 'hex'. | | callback | function | [empty function] | Callback function that receives the dominant color and the colors palette. | | errorCallback | function | [empty function] | Callback function that receives image loading, canvas, and processing errors. |

Interfaces

The library provides the following interfaces for type checking:

type ColorFormat = 'rgb' | 'hsl' | 'hex';
type ColorQuantization = 'exact' | 'bucket' | 'median-cut';
type DominantColorSource = HTMLImageElement | HTMLCanvasElement | ImageBitmap | string | Blob;

interface PrimaryColor {
  color: string;
  count: number;
}

interface DominantColorOptions {
  downScaleFactor: number;
  skipPixels: number;
  colorsPaletteLength: number;
  colorBucketSize: number;
  colorGroupingThreshold: number;
  colorQuantization: ColorQuantization;
  paletteWithCountOfOccurrences: boolean;
  colorFormat: ColorFormat;
  callback: DominantColorCallback;
  errorCallback: DominantColorErrorCallback;
}

type DominantColorCallback = (dominant: string, colorsPalette: string[] | PrimaryColor[]) => void;
type DominantColorErrorCallback = (error: Error) => void;

interface DominantColorResult {
  dominant: string;
  colorsPalette: string[] | PrimaryColor[];
}

function getDominantColor(source: DominantColorSource, options?: Partial<DominantColorOptions>): void;
function getDominantColorAsync(source: DominantColorSource, options?: Partial<DominantColorOptions>): Promise<DominantColorResult>;

Feel free to explore and utilize these interfaces for better code development.

Remember to replace your code here in the usage example with your own code to handle the dominant color and colors palette.