Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dist 🌀 Aug 19, 2018
img Move examples Aug 1, 2018
src Added dominant algorithm Aug 19, 2018
test Added dominant algorithm Aug 19, 2018
typings Add typings Aug 5, 2018
.babelrc 🚧 Feb 10, 2018
.eslintignore Move examples Aug 1, 2018
.eslintrc Add tests and update deps Feb 25, 2018
.gitattributes 🚧 Feb 10, 2018
.gitignore Add tests and update deps Feb 25, 2018
.travis.yml 🚧 Feb 10, 2018
CHANGELOG.md Added dominant algorithm Aug 19, 2018
LICENSE Add LICENSE Feb 10, 2018
README.md Update README.md Aug 19, 2018
gulpfile.js Update deps and Gulp Jul 5, 2018
package-lock.json 🌀 Aug 19, 2018
package.json 🌀 Aug 19, 2018
tsconfig.json Add typings Aug 5, 2018

README.md

Fast Average Color

NPM version NPM Downloads Dependency Status Build Status

A simple library that calculates the average color of any images or videos in browser environment.

Examples

See code

Using

npm i fast-average-color

Simple

<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>
<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'), function(color) {
            container.style.backgroundColor = color.rgba;
            container.style.color = color.isDark ? '#fff' : '#000';
        });
    </script>
</body>
</html>

CommonJS

'use strict';

const FastAverageColor = require('fast-average-color');
const fac = new FastAverageColor();
const color = fac.getColor(document.querySelector('img'));

console.log(color);

ES6

import FastAverageColor from 'fast-average-color/dist/index.es6';

const fac = new FastAverageColor();
const color = fac.getColor(document.querySelector('img'));

console.log(color);

API

.getColor(resource, [options])

/**
 * Get synchronously the average color from images, videos and canvas.
 *
 * @param {HTMLImageElement|HTMLVideoElement|HTMLCanvasElement} resource
 * @param {Object|null} [options]
 * @param {Array}  [options.defaultColor=[255, 255, 255, 255]]
 * @param {*}      [options.data]
 * @param {string} [options.mode="speed"] "precision" or "speed"
 * @param {string} [options.algorithm="sqrt"] "simple" or "sqrt"
 * @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).

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

.getColorAsync(resource, callback, [options])

/**
 * Get asynchronously the average color from not loaded image.
 *
 * @param {HTMLImageElement} resource
 * @param {Function} callback
 * @param {Object|null} [options]
 * @param {Array}  [options.defaultColor=[255, 255, 255, 255]]
 * @param {*}      [options.data]
 * @param {string} [options.mode="speed"] "precision" or "speed"
 * @param {string} [options.algorithm="sqrt"] "simple" or "sqrt"
 * @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]
 */

Get asynchronously the average color from a resource (not loaded images, videos or canvas).

const fac = new FastAverageColor();

// From not loaded image (HTMLImageElement)
fac.getColorAsync(image1, function(color) {
    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
    // }
});

// Advanced example
fac.getColorAsync(image2, function(color, data) {
    console.log(this);
    // this = image2

    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
    // }

    console.log(data);
    // {
    //     myProp: 1
    // }
}, {
    // red 0-255, green 0-255, blue 0-255, alpha 0-255
    defaultColor: [255, 100, 100, 200],
    data: { myProp: 1 }
});

.getColorFromArray4(array, options)

/**
 * 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" or "sqrt"
 * @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.

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]

.destroy()

const fac = new FastAverageColor();
const color = fac.getColor(document.querySelector('img'));

//...

// The instance is no longer needed.
fac.destroy();

Algorithms

  • simple
  • sqrt (default)
  • dominant

Comparison of algorithms for photos
Comparison of algorithms for 2 colors

const fac = new FastAverageColor();
console.log(fac.getColor(image, {algorithm: 'dominant'});

Different Builds

In the dist/ directory of the NPM package you will find many different builds.

Type Filename
Development index.js
Production index.min.js
ES6 index.es6.js

Development

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/

License

MIT License