fast-average-color
Version:
A simple library that calculates the average color of images, videos and canvas in browser environment.
292 lines (248 loc) • 8.94 kB
Markdown
[](https://www.npmjs.com/package/fast-average-color)
[](https://www.npmjs.org/package/fast-average-color)
[](https://david-dm.org/fast-average-color/fast-average-color)
[](https://travis-ci.org/fast-average-color/fast-average-color)
A simple library that calculates the average color of any images or videos in browser environment.
<img width="100%" style="max-width: 640px;" src="https://raw.githubusercontent.com/fast-average-color/fast-average-color/master/img/title.png" />
- [Background](https://fast-average-color.github.io/examples/background.html)
- [Box shadow](https://fast-average-color.github.io/examples/box-shadow.html)
- [Box shadow, 4 sides](https://fast-average-color.github.io/examples/box-shadow-4-sides.html)
- [Border](https://fast-average-color.github.io/examples/border.html)
- [Gallery](https://fast-average-color.github.io/examples/gallery.html)
- [Gradient](https://fast-average-color.github.io/examples/gradient.html)
- [Gradient as stripes](https://fast-average-color.github.io/examples/gradient_stripes.html)
- [Canvas](https://fast-average-color.github.io/examples/canvas.html)
- [Text photo](https://fast-average-color.github.io/examples/text-photo.html)
- [Ambilight](https://fast-average-color.github.io/examples/ambilight.html)
- [Define the average color for your images](https://fast-average-color.github.io/examples/define.html)
[](https://github.com/fast-average-color/examples)
```
npm i fast-average-color
```
```html
<html>
<body>
...
<div class="image-container">
<img src="image.png" />
<div>
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</div>
</div>
<script src="https://unpkg.com/fast-average-color/dist/index.min.js"></script>
<script>
window.addEventListener('load', function() {
var
fac = new FastAverageColor(),
container = document.querySelector('.image-container'),
color = fac.getColor(container.querySelector('img'));
container.style.backgroundColor = color.rgba;
container.style.color = color.isDark ? '#fff' : '#000';
console.log(color);
// {
// error: null,
// rgb: 'rgb(255, 0, 0)',
// rgba: 'rgba(255, 0, 0, 1)',
// hex: '#ff0000',
// hexa: '#ff0000ff',
// value: [255, 0, 0, 255],
// isDark: true,
// isLight: false
// }
}, false);
</script>
</body>
</html>
```
or
```html
<html>
<body>
...
<div class="image-container">
<img src="image.png" />
<div>
Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
</div>
</div>
<script src="https://unpkg.com/fast-average-color/dist/index.min.js"></script>
<script>
var
fac = new FastAverageColor(),
container = document.querySelector('.image-container');
fac.getColorAsync(container.querySelector('img'))
.then(function(color) {
container.style.backgroundColor = color.rgba;
container.style.color = color.isDark ? '#fff' : '#000';
})
.catch(function(e) {
console.log(e);
});
</script>
</body>
</html>
```
```js
'use strict';
const FastAverageColor = require('fast-average-color');
const fac = new FastAverageColor();
const color = fac.getColor(document.querySelector('img'));
console.log(color);
```
```js
import FastAverageColor from 'fast-average-color/dist/index.es6';
const fac = new FastAverageColor();
const color = fac.getColor(document.querySelector('img'));
console.log(color);
```
```js
/**
* Get synchronously the average color from images, videos and canvas.
*
* @param {HTMLImageElement|HTMLVideoElement|HTMLCanvasElement} resource
* @param {Object} [options]
* @param {Array} [options.defaultColor=[255, 255, 255, 255]]
* @param {string} [options.mode="speed"] "precision" or "speed"
* @param {string} [options.algorithm="sqrt"] "simple", "sqrt" or "dominant"
* @param {number} [options.step=1]
* @param {number} [options.left=0]
* @param {number} [options.top=0]
* @param {number} [options.width=width of resource]
* @param {number} [options.height=height of resource]
*
* @returns {Object}
*/
```
Get the average color from a resource (loaded images, videos or canvas).
```js
const fac = new FastAverageColor();
let color;
// From loaded image (HTMLImageElement)
color = fac.getColor(image);
// From loaded image with default color
color = fac.getColor({
// Set default color - red.
defaultColor: [255, 0, 0, 255]
});
// From loaded image with precision
color = fac.getColor({
// Modes: 'speed' (by default) or 'precision'.
// Current mode is precision.
mode: 'precision'
});
// From canvas (HTMLCanvasElement)
color = fac.getColor(canvas);
// From video (HTMLVideoElement)
color = fac.getColor(video);
```
```js
/**
* Get asynchronously the average color from not loaded image.
*
* @param {HTMLImageElement} resource
* @param {Object} [options]
* @param {string} [options.mode="speed"] "precision" or "speed"
* @param {string} [options.algorithm="sqrt"] "simple", "sqrt" or "dominant"
* @param {number} [options.step=1]
* @param {number} [options.left=0]
* @param {number} [options.top=0]
* @param {number} [options.width=width of resource]
* @param {number} [options.height=height of resource]
*
* @returns {Promise}
*/
```
Get asynchronously the average color from a resource (not loaded images, videos or canvas).
```js
const fac = new FastAverageColor();
// From not loaded image (HTMLImageElement)
fac.getColorAsync(image, { algorithm: 'dominant' })
.then(function(color) {
console.log(color);
// {
// rgb: 'rgb(255, 0, 0)',
// rgba: 'rgba(255, 0, 0, 1)',
// hex: '#ff0000',
// hexa: '#ff0000ff',
// value: [255, 0, 0, 255],
// isDark: true,
// isLight: false
// }
})
.catch(function(e) {
console.error(e);
});
```
```js
/**
* Get the average color from a array when 1 pixel is 4 bytes.
*
* @param {Array|Uint8Array} arr
* @param {Object} [options]
* @param {string} [options.algorithm="sqrt"] "simple", "sqrt" or "dominant"
* @param {Array} [options.defaultColor=[255, 255, 255, 255]]
* @param {number} [options.step=1]
*
* @returns {Array} [red (0-255), green (0-255), blue (0-255), alpha (0-255)]
*/
```
Get the average color from a array when 1 pixel is 4 bytes.
```js
const fac = new FastAverageColor();
const buffer = [
// red, green, blue, alpha
200, 200, 200, 255,
100, 100, 100, 255
];
const color = fac.getColorFromArray4(buffer);
console.log(color);
// [150, 150, 150, 255]
```
```js
const fac = new FastAverageColor();
const color = fac.getColor(document.querySelector('img'));
//...
// The instance is no longer needed.
fac.destroy();
```
- `simple`
- `sqrt` (default)
- `dominant`
[](https://fast-average-color.github.io/examples/algorithms.html)
[](https://fast-average-color.github.io/compare/)
```js
const fac = new FastAverageColor();
console.log(fac.getColor(image, {algorithm: 'dominant'});
```
In the `dist/` directory of [the NPM package](https://unpkg.com/fast-average-color/dist/) you will find many different builds.
|Type |Filename |
|------------------|-------------------------|
|Development |`index.js` |
|Production |`index.min.js` |
|ES6 |`index.es6.js` |
```
git clone git@github.com:fast-average-color/fast-average-color.git ./fast-average-color
cd ./fast-average-color
npm i
npm test
open ./examples/
```
MIT License