Skip to content

Namide/extract-colors

Repository files navigation

Extract Colors

package version npm min bundle size npm gzip bundle size zero dependency CI code coverage GNU GPL software License Downloaded

Extract color palettes from images.
Simple use, < 6kB minified, gzip ≈ 2kB, fast process and no dependencies for browser.
Need image reader dependence for node.js

Website | Demo | Guide

3 examples of colors extraction

Requirements

Browsers

  • Firefox: 29+
  • Chrome: 33+
  • Edge: 12+
  • Opera: 19+
  • Safari: 8+
  • Webview Android: 4.4.3+
  • Samsung Internet: 2.0+
  • Internet Explorer

Node

  • Node.js: 6.0+

Install

For browser

npm install --save extract-colors

For node.js

Need to install an ImageData extractor like get-pixels

npm install --save extract-colors get-pixels

Usage

Browser example

import { extractColors } from "extract-colors";

const src = "my-image.jpg";

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

You can use different types for src param (String for a path of image, HTMLImageElement or ImageData).

Node.js example

const path = require("path");
const getPixels = require("get-pixels");
const { extractColors } = require("extract-colors");

const src = path.join(__dirname, "./my-image.jpg");

getPixels(src, (err, pixels) => {
  if (!err) {
    const data = [...pixels.data];
    const [width, height] = pixels.shape;

    extractColors({ data, width, height }).then(console.log).catch(console.log);
  }
});

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

ExtractorOptions

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);

pixels
Total pixel number of the resized picture for calculation
Type: Integer
Default: 64000

distance
From 0 to 1 is the color distance to not have near colors (1 distance is between white and black)
Type: Number
Default: 0.22

colorValidator
Test function to enable only some colors
Type: Function
Default: (red, green, blue, alpha = 255) => alpha > 250

crossOrigin
Only for browser, can be 'Anonymous' to avoid client side CORS (the server side images need authorizations too)
Type: String
Default: ""

requestMode
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: String
Default: cors

saturationDistance
Minimum saturation value between two colors otherwise the colors will be merged (from 0 to 1) Type: String
Default: 0.2

lightnessDistance
Minimum lightness value between two colors otherwise the colors will be merged (from 0 to 1) Type: String
Default: 0.2

hueDistance
Minimum hue value between two colors otherwise the colors will be merged (from 0 to 1) Type: String
Default: 0.083333333

Return of the promise

Array of colors 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 color in hexadecimal string
red 133 Integer red canal from 0 to 255
green 132 Integer green canal from 0 to 255
blue 9 Integer blue canal 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 area of the color and his neighbouring colors from 0 to 1

License

Copyright (C) 2019-present Damien Doussaud

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.