sharp-vibrant

Extract prominent colors from an image in nodejs using sharp for image loading/processing.

This is a fork of node-vibrant that reduces dependencies/complexity at the cost of absolutely no browser support. This fork was created for internal use and is not published to any package manager.

Usage

node.js

// ES5
var Vibrant = require('sharp-vibrant')
// ES6
import * as Vibrant from '@livechart/sharp-vibrant'
// TypeScript
import Vibrant = require('@livechart/sharp-vibrant')

// Using builder
Vibrant.from('path/to/image').getPalette((err, palette) => console.log(palette))
// Promise
Vibrant.from('path/to/image').getPalette()
  .then((palette) => console.log(palette))

// Using constructor
let v = new Vibrant('path/to/image', opts)
v.getPalette((err, palette) => console.log(palette))
// Promise
v.getPalette().then((palette) => console.log(palette))

Contribution Guidelines

1. Make changes
2. Write test specs if necessary
3. Pass tests
4. Commit source files only (without compiled files)

References

Vibrant

Main class of sharp-vibrant.

Vibrant.from(src: ImageSource): Builder

Make a Builder for an image. Returns a Builder instance.

constructor(src: ImageSource, opts: Partial<Options>)

ImageSource

export type ImageSource = string | Buffer

Options

export interface Options {
    colorCount: number
    quality: number
    maxDimension: number
    filters: Array<Filter>
    ImageClass: ImageClass
    quantizer: Quantizer
    generator?: Generator
}

Resolvable<T>

export type Resolvable<T> = T | Promise<T>

Quantizer

export interface Quantizer {
    (pixels: Pixels, opts: Options): Resolvable<Array<Swatch>>
}

Generator

export interface Generator {
    (swatches: Array<Swatch>, opts?: Object): Resolvable<Palette>
}

Filter

Returns true if the color is to be kept.

export interface Filter {
    (red: number, green: number, blue: number, alpha: number): boolean
}

getPalette(cb?: Callback<PaletteResult>): Promise<PaletteResult>

Callback<T>

export interface Callback<T> {
    (err?: Error, result?: T): void
}

ImageDimensions

interface ImageDimensions {
    readonly width: number
    readonly height: number
}

PaletteResult

interface PaletteResult {
    readonly pixelCount: number
    readonly imageDimensions: ImageDimensions
    readonly palette: Palette
}

Vibrant.Builder

Helper class for change configurations and create a Vibrant instance. Methods of a Builder instance can be chained like:

Vibrant.from(src)
  .quality(1)
  .clearFilters()
  // ...
  .getPalette()
  .then((paletteResult) => {})

constructor(src: ImageSource, opts: Partial<Options>)

Arguments are the same as Vibrant.constructor.

quality(q: number): Builder

Sets opts.quality to q. Returns this Builder instance.

maxColorCount(n: number): Builder

Sets opts.colorCount to n. Returns this Builder instance.

maxDimension(d: number): Builder

Sets opts.maxDimension to d. Returns this Builder instance.

addFilter(f: Filter): Builder

Adds a filter function. Returns this Builder instance.

removeFilter(f: Filter): Builder

Removes a filter function. Returns this Builder instance.

clearFilters(): Builder

Clear all filters. Returns this Builder instance.

useImageClass(imageClass: ImageClass): Builder

Specifies which Image implementation class to use. Returns this Builder instance.

useQuantizer(quantizer: Quantizer): Builder

Specifies which Quantizer implementation class to use. Returns this Builder instance.

useGenerator(generator: Generator): Builder

Sets opts.generator to generator. Returns this Builder instance.

build(): Vibrant

Builds and returns a Vibrant instance as configured.

getPalette(cb?: Callback<PaletteResult>): Promise<PaletteResult>

Builds a Vibrant instance as configured and calls its getPalette method.

Vibrant.Swatch

Represents a color swatch generated from an image's palette.

Vec3

export interface Vec3 extends Array<number> {
    0: number,
    1: number,
    2: number
}

constructor(rgb: Vec3, population: number)

Internal use.

getHsl(): Vec3

getPopulation(): number

getRgb(): Vec3

getHex(): string

getTitleTextColor(): string

Returns an appropriate color to use for any 'title' text which is displayed over this Swatch's color.

getBodyTextColor(): string

Returns an appropriate color to use for any 'body' text which is displayed over this Swatch's color.

Vibrant.Util

Utility methods. Internal usage.

hexToRgb(hex: string): Vec3

rgbToHex(r: number, g: number, b: number): string

hslToRgb(h: number, s: number, l: number): Vec3

rgbToHsl(r: number, g: number, b: number): Vec3

xyzToRgb(x: number, y: number, z: number): Vec3

rgbToXyz(r: number, g: number, b: number): Vec3

xyzToCIELab(x: number, y: number, z: number): Vec3

rgbToCIELab(l: number, a: number, b: number): Vec3

deltaE94(lab1: number, lab2: number): number

Computes CIE delta E 1994 diff between lab1 and lab2. The 2 colors are in CIE-Lab color space. Used in tests to compare 2 colors' perceptual similarity.

rgbDiff(rgb1: Vec3, rgb2: Vec3): number

Compute CIE delta E 1994 diff between rgb1 and rgb2.

hexDiff(hex1: string, hex2: string): number

Compute CIE delta E 1994 diff between hex1 and hex2.

getColorDiffStatus(d: number): string

Gets a string to describe the meaning of the color diff. Used in tests.

NPM Tasks