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

Name | Description ------- | --------------------------------------- image | Path to image file (support HTTP/HTTPs) opts | Options (optional)

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
}

Field | Default | Description -------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- colorCount | 64 | amount of colors in initial palette from which the swatches will be generated quality | 5 | Scale down factor used in downsampling stage. 1 means no downsampling. If maxDimension is set, this value will not be used. maxDimension | undefined | The max size of the image's longer side used in downsampling stage. This field will override quality. filters | [] | An array of filters ImageClass | Image.Node | An Image implementation class quantizer | Vibrant.Quantizer.MMCQ | A Quantizer implementation class generator | Vibrant.Generator.Default | An Generator instance

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>

Name | Description ---- | ----------------- cb | (Optional) callback function. Can be omitted when using Promise.

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.

Name | Description ------------ | ----------------------------------- rgb | [r, g, b] population | Population of the color in an image

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.

Delta E | Perception | Returns -------- | -------------------------------------- | ----------- <= 1.0 | Not perceptible by human eyes. | "Perfect" 1 - 2 | Perceptible through close observation. | "Close" 2 - 10 | Perceptible at a glance. | "Good" 11 - 49 | Colors are more similar than opposite | "Similar" 50 - 100 | Colors are exact opposite | Wrong

NPM Tasks

Task | Description --------------- | -------------------------------------- build:node | Build node.js target build | Build all targets clean:node | Clean node.js build clean | Clean all builds test:node | Run node.js specs (mocha) test | Run all specs