sharp-vibrant
v0.4.0
Published
Extract prominent colors from an image in a node environment using sharp.
Downloads
190
Maintainers
Readme
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
- Make changes
- Write test specs if necessary
- Pass tests
- 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