https://github.com/vibrant-colors/node-vibrant
🎨 Extract prominent colors from an image
https://github.com/vibrant-colors/node-vibrant
canvas color colour detection image muted picture varation vibrant
Last synced: about 2 hours ago
JSON representation
🎨 Extract prominent colors from an image
- Host: GitHub
- URL: https://github.com/vibrant-colors/node-vibrant
- Owner: Vibrant-Colors
- Created: 2015-06-04T13:30:08.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2025-04-04T14:59:21.000Z (18 days ago)
- Last Synced: 2025-04-12T22:16:32.245Z (10 days ago)
- Topics: canvas, color, colour, detection, image, muted, picture, varation, vibrant
- Language: TypeScript
- Homepage: https://vibrant.dev
- Size: 23.3 MB
- Stars: 2,207
- Watchers: 14
- Forks: 111
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# node-vibrant
Extract prominent colors from an image.
- Identical API for node.js, browser, and worker environments
## Install
```bash
$ npm install node-vibrant
```
## Usage
```typescript
// Node
import { Vibrant } from "node-vibrant/node";
// Browser
import { Vibrant } from "node-vibrant/browser";
// Web Worker
import { Vibrant } from "node-vibrant/worker";
// Using builder
Vibrant.from("path/to/image")
.getPalette()
.then((palette) => console.log(palette));
// Using constructor
let v = new Vibrant("path/to/image", opts);
v.getPalette().then((palette) => console.log(palette));
```
### Worker Usage
Quantization is the most time-consuming stage in `node-vibrant`. Luckily, the quantization can be run in the WebWorker to avoid freezing the UI thread.
Here's how to use this feature:
```typescript
import { Vibrant, WorkerPipeline } from "node-vibrant/worker";
import PipelineWorker from "node-vibrant/worker.worker?worker";
Vibrant.use(new WorkerPipeline(PipelineWorker as never));
```
This requires your bundler to handle `?worker` transforms [similar to how Vite does](https://vite.dev/guide/features.html#import-with-query-suffixes)
## Documentation
Docs can be seen currently in the [`docs`](./docs) folder. It includes reference docs and step-by-step guides.
We also have a few [`examples`](./examples) that you can reference for your needs.
PRs welcomed to expand either of these!
## Notes
### Result Consistency
The results are consistent within each user's browser instance regardless of the visible region or display size of an image, unlike the original `vibrant.js` implementation.
However, due to the nature of the HTML5 canvas element, image rendering is platform/machine-dependent. The resulting swatches may vary between browsers, Node.js versions, and between machines. See [Canvas Fingerprinting](https://en.wikipedia.org/wiki/Canvas_fingerprinting).
The test specs use CIE delta E 1994 color difference to measure inconsistencies across platforms. It compares the generated color on Node.js, Chrome, Firefox, and IE11. At `quality` == 1 (no downsampling) with no filters and the results are rather consistent. Color diffs between browsers are mostly not perceptible by the human eye. Downsampling _will_ cause perceptible inconsistent results across browsers due to differences in canvas implementations.