Skip to content
πŸπŸŠπŸ… Fast Average Color
JavaScript
Branch: master
Clone or download
Latest commit b7cd10f Nov 17, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist Changed to arrow functions. Oct 25, 2019
img Move examples Aug 1, 2018
src new Error β†’ Error Nov 9, 2019
test new Error β†’ Error Nov 9, 2019
typings Add a check when resource is null May 25, 2019
.babelrc Update dev deps Jan 11, 2019
.eslintignore Move examples Aug 1, 2018
.eslintrc Updated ESLint rules. Oct 25, 2019
.gitattributes 🚧 Feb 10, 2018
.gitignore Update dev deps in package.json Apr 27, 2019
.travis.yml 🚧 Feb 10, 2018
CHANGELOG.md Update dev deps Oct 3, 2019
LICENSE πŸŒ€ Apr 27, 2019
README.md Update README.md Nov 17, 2019
gulpfile.js Changed to arrow functions. Oct 25, 2019
package-lock.json Update deps Nov 9, 2019
package.json Update deps Nov 9, 2019
tsconfig.json Add typings Aug 5, 2018

README.md

Fast Average Color

NPM version NPM Downloads Dependency Status Build Status bundlephobia

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

Examples

See code

Storing an image from a foreign origin

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

CommonJS

Details

'use strict';

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

console.log(color);

ES Modules

Details

import FastAverageColor from 'fast-average-color';

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

console.log(color);

TypeScript

import * as FastAverageColor from 'fast-average-color';

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 | null} 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]
 * @param {boolean} [options.silent] Disable error output via console.error
 *
 * @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, [options])

/**
 * Get asynchronously the average color from not loaded image.
 *
 * @param {HTMLImageElement | null} 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]
 * @param {boolean} [options.silent] Disable error output via console.error
 * 
 * @returns {Promise}
 */

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

.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", "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.

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

Development

git clone git@github.com:fast-average-color/fast-average-color.git ./fast-average-color
cd ./fast-average-color

npm i
npm test

License

MIT License

You can’t perform that action at this time.