colors-from-image

Color Extractor

Powers the website colorsfromimage.xyz

A powerful library for extracting color palettes from images using multiple algorithms:

• Vibrant: Extracts vibrant and muted colors (inspired by Material Design)
• Material Design: Creates a palette following Material Design color principles
• Median Cut: Uses the median cut algorithm (similar to Photoshop's color reduction)
• K-Means: Applies k-means clustering in Lab color space for perceptually accurate colors

Installation

bash
npm install colors-from-image

Usage

Basic Usage

const ColorExtractor = require('colors-from-image');

const image = document.getElementById('myImage');

const colors = ColorExtractor.extractColors(image);

colors.forEach(color => {
    const formattedColor = ColorExtractor.formatColor(color.color);
    console.log(Color: ${formattedColor.hex}, Frequency: ${color.frequency});
});

Using Different Extraction Methods

// Extract using Material Design method
const materialColors = ColorExtractor.extractColors(image, 'material');

// Extract using Median Cut method with 10 colors
const medianCutColors = ColorExtractor.extractColors(image, 'mediancut', { colorCount: 10 });

// Extract using K-Means clustering with 8 colors
const kMeansColors = ColorExtractor.extractColors(image, 'kmeans', { colorCount: 8 });

Working with Canvas or ImageData

// With canvas ImageData
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');

// ... draw to canvas ...
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
const colors = ColorExtractor.extractColors(imageData);

Node.js Usage with Canvas

const { createCanvas, loadImage } = require('canvas');
const ColorExtractor = require('color-extractor');

async function extractColorsFromFile(filePath) {
    // Load the image
    const image = await loadImage(filePath);
    // Create canvas and draw image
    const canvas = createCanvas(image.width, image.height);
    const ctx = canvas.getContext('2d');
    ctx.drawImage(image, 0, 0);
    // Get image data
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    // Extract colors
    return ColorExtractor.extractColors(imageData);
}

// Usage
extractColorsFromFile('path/to/image.jpg')
    .then(colors => {
        colors.forEach(color => {
            const formattedColor = ColorExtractor.formatColor(color.color);
            console.log(Color: ${formattedColor.hex}, Frequency: ${color.frequency});
        });
    });

Formatting Colors

const rgb = [255, 100, 50];
const formattedColor = ColorExtractor.formatColor(rgb);
console.log(formattedColor.hex); // "#ff6432"
console.log(formattedColor.rgb); // "rgb(255, 100, 50)"
console.log(formattedColor.rgba); // "rgba(255, 100, 50, 1.0)"
console.log(formattedColor.hsl); // "hsl(14, 100%, 60%)"
console.log(formattedColor.values.rgb); // [255, 100, 50]
console.log(formattedColor.values.hsl); // [14, 100, 60]

API Reference

Main Functions

extractColors(image, method, options)

Extracts a color palette from an image.

• Parameters:

  • image (HTMLImageElement|ImageData): The image to extract colors from
  • method (string, optional): Extraction method to use: 'vibrant', 'material', 'mediancut', or 'kmeans'. Default: 'vibrant'
  • options (object, optional):
    • colorCount (number): Number of colors to extract (for mediancut and kmeans). Default: 8
    • maxPixels (number): Maximum number of pixels to sample for performance. Default: 10000

• Returns: Array of color objects with properties:

  • color (Array): RGB color as [r, g, b]
  • frequency (number): Frequency of the color in the image
  • name (string, optional): Name of the color (for vibrant and material methods)

formatColor(rgb)

Formats an RGB color into various color formats.

• Parameters:

  • rgb (Array): RGB color as [r, g, b]

• Returns: Object with color in different formats:

  • hex (string): HEX color code
  • rgb (string): RGB color string
  • rgba (string): RGBA color string
  • hsl (string): HSL color string
  • values (object): Raw values
    • rgb (Array): RGB values as [r, g, b]
    • hsl (Array): HSL values as [h, s, l]

Algorithm Details

Vibrant

Extracts a palette of vibrant and muted colors, categorized as:

• Vibrant
• Light Vibrant
• Dark Vibrant
• Muted
• Light Muted
• Dark Muted

Material Design

Creates a palette following Material Design principles with:

• Primary color
• Accent colors
• Light and dark neutral colors

Median Cut

Recursively divides the color space along the axis with the largest range until the desired number of colors is reached.

K-Means

Clusters colors in Lab color space (which is perceptually uniform) using the k-means++ algorithm for better initial centroids.

License

MIT