Getting Started

Installation

npm install extract-colors

Usage

import { extractColors } from "extract-colors"

const src = "my-image.jpg"

extractColors(src)
  .then(console.log)
  .catch(console.error)

essentials

Output

Array of colors object with the followed properties

[
  {
    hex: "#858409",
    red: 133,
    green: 132,
    blue: 9,
    hue: 0.16532258064516128,
    intensity: 0.4862745098039216,
    lightness: 0.2784313725490196,
    saturation: 0.8732394366197184,
    area: 0.0004
  },
  // ...
]

Field	Example	Type	Description
hex	#858409	String	Hexadecimal RGB string
red	133	Integer	red amount from 0 to 255
green	132	Integer	green amount from 0 to 255
blue	9	Integer	blue amount from 0 to 255
hue	0.1653	Number	color tone from 0 to 1
intensity	0.4862	Number	color intensity from 0 to 1
lightness	0.2784	Number	color lightness from 0 to 1
saturation	0.8732	Number	color saturation from 0 to 1
area	0.0004	Number	Abundance of the color and his neighbouring colors from 0 to 1

advanced

Module usage

import { extractColors } from "extract-colors/lib/extract-colors.mjs"

const src = "my-image.jpg"

extractColors(src)
  .then(console.log)
  .catch(console.error)

The NodeJs example use get-pixels but you can change the lib.
Just send the ImageData object to extractColors(imageData) for NodeJs.

Web Workers (browser only)

import { extractColors } from "extract-colors/lib/worker-wrapper"

const src = "my-image.jpg"

extractColors(src)
  .then(console.log)
  .catch(console.error)

Options

Example of custom options

import { extractColors } from "extract-colors/lib/extract-colors.mjs"

const src = "my-image.jpg"

const options = {
  pixels: 64000,
  distance: 0.22,
  colorValidator: (red, green, blue, alpha = 255) => alpha > 250,
  saturationDistance: 0.2,
  lightnessDistance: 0.2,
  hueDistance: 0.083333333
}

extractColors(src, options)
  .then(console.log)
  .catch(console.error)

With browser you can use different types for src param (String for a path of image or ImageData).
NodeJs support only ImageData input.

pixels

Total pixel number of the resized picture for calculation. Fewer pixels will produce a rougher but faster result. More pixels will produce a more accurate but slower result.

Type	Min	Max	Default
Integer	1	2^53 - 1	10000

distance

Color distance to not have near colors (1 distance is between white and black). Less distance will produce a faster result with less colors. More distance will produce more precise colors but slower result.

Type	Min	Max	Default
Number	0	1	0.22

colorValidator

Test function to enable only some colors.

Type	Function
Signature	`(red: number, green: number, blue: number, alpha?: number) => boolean`
Default	(red, green, blue, alpha = 255) => alpha > 250

crossOrigin (browser)

Only for browser, can be 'Anonymous' to avoid client side CORS. (the server side images need authorizations too).

Type	Default
String	""

requestMode (Web Workers in browser)

Only for Web Workers in browser: it's used to determine if cross-origin requests lead to valid responses, and which properties of the response are readable

Type	Default
String	cors

saturationDistance

Minimum saturation value between two colors otherwise the colors will be merged.

Type	Min	Max	Default
String	0	1	0.2

lightnessDistance

Minimum lightness value between two colors otherwise the colors will be merged.

Type	Min	Max	Default
String	0	1	0.2

hueDistance

Minimum hue value between two colors otherwise the colors will be merged.

Type	Min	Max	Default
String	0	1	0.083333333