UNPKG

8.99 kBMarkdownView Raw
1# Fast Average Color
2[![NPM version](https://img.shields.io/npm/v/fast-average-color.svg)](https://www.npmjs.com/package/fast-average-color)
3[![NPM Downloads](https://img.shields.io/npm/dm/fast-average-color.svg?style=flat)](https://www.npmjs.org/package/fast-average-color)
4[![Dependency Status](https://img.shields.io/david/fast-average-color/fast-average-color.svg)](https://david-dm.org/fast-average-color/fast-average-color)
5[![Build Status](https://img.shields.io/travis/fast-average-color/fast-average-color.svg?style=flat)](https://travis-ci.org/fast-average-color/fast-average-color)
6
7A simple library that calculates the average color of any images or videos in browser environment.
8<img width="100%" style="max-width: 640px;" src="https://raw.githubusercontent.com/fast-average-color/fast-average-color/master/img/title.png" />
9
10## [Examples](https://fast-average-color.github.io/examples/background.html)
11- [Background](https://fast-average-color.github.io/examples/background.html)
12- [Box shadow](https://fast-average-color.github.io/examples/box-shadow.html)
13- [Box shadow, 4 sides](https://fast-average-color.github.io/examples/box-shadow-4-sides.html)
14- [Border](https://fast-average-color.github.io/examples/border.html)
15- [Gallery](https://fast-average-color.github.io/examples/gallery.html)
16- [Gradient](https://fast-average-color.github.io/examples/gradient.html)
17- [Gradient as stripes](https://fast-average-color.github.io/examples/gradient_stripes.html)
18- [Canvas](https://fast-average-color.github.io/examples/canvas.html)
19- [Text photo](https://fast-average-color.github.io/examples/text-photo.html)
20- [Ambilight](https://fast-average-color.github.io/examples/ambilight.html)
21- [Define the average color for your images](https://fast-average-color.github.io/examples/define.html)
22
23[See code](https://github.com/fast-average-color/examples)
24
25## [Storing an image from a foreign origin](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#Storing_an_image_from_a_foreign_origin)
26
27## Using
28```
29npm i fast-average-color
30```
31
32### Simple
33```html
34<html>
35<body>
36 ...
37 <div class="image-container">
38 <img src="image.png" />
39 <div>
40 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
41 sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
42 </div>
43 </div>
44 <script src="https://unpkg.com/fast-average-color/dist/index.min.js"></script>
45 <script>
46 window.addEventListener('load', function() {
47 var
48 fac = new FastAverageColor(),
49 container = document.querySelector('.image-container'),
50 color = fac.getColor(container.querySelector('img'));
51
52 container.style.backgroundColor = color.rgba;
53 container.style.color = color.isDark ? '#fff' : '#000';
54
55 console.log(color);
56 // {
57 // error: null,
58 // rgb: 'rgb(255, 0, 0)',
59 // rgba: 'rgba(255, 0, 0, 1)',
60 // hex: '#ff0000',
61 // hexa: '#ff0000ff',
62 // value: [255, 0, 0, 255],
63 // isDark: true,
64 // isLight: false
65 // }
66 }, false);
67 </script>
68</body>
69</html>
70```
71
72or
73
74```html
75<html>
76<body>
77 ...
78 <div class="image-container">
79 <img src="image.png" />
80 <div>
81 Lorem ipsum dolor sit amet, consectetur adipiscing elit,
82 sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
83 </div>
84 </div>
85 <script src="https://unpkg.com/fast-average-color/dist/index.min.js"></script>
86 <script>
87 var
88 fac = new FastAverageColor(),
89 container = document.querySelector('.image-container');
90
91 fac.getColorAsync(container.querySelector('img'))
92 .then(function(color) {
93 container.style.backgroundColor = color.rgba;
94 container.style.color = color.isDark ? '#fff' : '#000';
95 })
96 .catch(function(e) {
97 console.log(e);
98 });
99 </script>
100</body>
101</html>
102```
103
104### CommonJS
105[Details](./dist/README.md)
106
107```js
108'use strict';
109
110const FastAverageColor = require('fast-average-color');
111const fac = new FastAverageColor();
112const color = fac.getColor(document.querySelector('img'));
113
114console.log(color);
115```
116
117### ES Modules
118[Details](./dist/README.md)
119
120```js
121import FastAverageColor from 'fast-average-color';
122
123const fac = new FastAverageColor();
124const color = fac.getColor(document.querySelector('img'));
125
126console.log(color);
127```
128
129### TypeScript
130```ts
131import * as FastAverageColor from 'fast-average-color';
132
133const fac = new FastAverageColor();
134const color = fac.getColor(document.querySelector('img'));
135
136console.log(color);
137```
138
139## API
140### `.getColor(resource, [options])`
141```js
142/**
143 * Get synchronously the average color from images, videos and canvas.
144 *
145 * @param {HTMLImageElement | HTMLVideoElement | HTMLCanvasElement | null} resource
146 * @param {Object} [options]
147 * @param {Array} [options.defaultColor=[255, 255, 255, 255]]
148 * @param {string} [options.mode="speed"] "precision" or "speed"
149 * @param {string} [options.algorithm="sqrt"] "simple", "sqrt" or "dominant"
150 * @param {number} [options.step=1]
151 * @param {number} [options.left=0]
152 * @param {number} [options.top=0]
153 * @param {number} [options.width=width of resource]
154 * @param {number} [options.height=height of resource]
155 * @param {boolean} [options.silent] Disable error output via console.error
156 *
157 * @returns {Object}
158 */
159```
160
161Get the average color from a resource (loaded images, videos or canvas).
162
163```js
164const fac = new FastAverageColor();
165let color;
166
167// From loaded image (HTMLImageElement)
168color = fac.getColor(image);
169
170// From loaded image with default color
171color = fac.getColor({
172 // Set default color - red.
173 defaultColor: [255, 0, 0, 255]
174});
175
176// From loaded image with precision
177color = fac.getColor({
178 // Modes: 'speed' (by default) or 'precision'.
179 // Current mode is precision.
180 mode: 'precision'
181});
182
183// From canvas (HTMLCanvasElement)
184color = fac.getColor(canvas);
185
186// From video (HTMLVideoElement)
187color = fac.getColor(video);
188```
189
190### `.getColorAsync(resource, [options])`
191```js
192/**
193 * Get asynchronously the average color from not loaded image.
194 *
195 * @param {HTMLImageElement | null} resource
196 * @param {Object} [options]
197 * @param {string} [options.mode="speed"] "precision" or "speed"
198 * @param {string} [options.algorithm="sqrt"] "simple", "sqrt" or "dominant"
199 * @param {number} [options.step=1]
200 * @param {number} [options.left=0]
201 * @param {number} [options.top=0]
202 * @param {number} [options.width=width of resource]
203 * @param {number} [options.height=height of resource]
204 * @param {boolean} [options.silent] Disable error output via console.error
205 *
206 * @returns {Promise}
207 */
208```
209Get asynchronously the average color from a resource (not loaded images, videos or canvas).
210```js
211const fac = new FastAverageColor();
212
213// From not loaded image (HTMLImageElement)
214fac.getColorAsync(image, { algorithm: 'dominant' })
215 .then(function(color) {
216 console.log(color);
217 // {
218 // rgb: 'rgb(255, 0, 0)',
219 // rgba: 'rgba(255, 0, 0, 1)',
220 // hex: '#ff0000',
221 // hexa: '#ff0000ff',
222 // value: [255, 0, 0, 255],
223 // isDark: true,
224 // isLight: false
225 // }
226 })
227 .catch(function(e) {
228 console.error(e);
229 });
230```
231
232### `.getColorFromArray4(array, options)`
233```js
234/**
235 * Get the average color from a array when 1 pixel is 4 bytes.
236 *
237 * @param {Array|Uint8Array} arr
238 * @param {Object} [options]
239 * @param {string} [options.algorithm="sqrt"] "simple", "sqrt" or "dominant"
240 * @param {Array} [options.defaultColor=[255, 255, 255, 255]]
241 * @param {number} [options.step=1]
242 *
243 * @returns {Array} [red (0-255), green (0-255), blue (0-255), alpha (0-255)]
244 */
245```
246
247Get the average color from a array when 1 pixel is 4 bytes.
248```js
249const fac = new FastAverageColor();
250const buffer = [
251 // red, green, blue, alpha
252 200, 200, 200, 255,
253 100, 100, 100, 255
254];
255const color = fac.getColorFromArray4(buffer);
256console.log(color);
257// [150, 150, 150, 255]
258```
259
260
261### `.destroy()`
262```js
263const fac = new FastAverageColor();
264const color = fac.getColor(document.querySelector('img'));
265
266//...
267
268// The instance is no longer needed.
269fac.destroy();
270```
271
272## Algorithms
273- `simple`
274- `sqrt` (default)
275- `dominant`
276
277[Comparison of algorithms for photos](https://fast-average-color.github.io/examples/algorithms.html)
278[Comparison of algorithms for 2 colors](https://fast-average-color.github.io/compare/)
279
280```js
281const fac = new FastAverageColor();
282console.log(fac.getColor(image, {algorithm: 'dominant'});
283```
284
285## [Different Builds](./dist/README.md)
286
287## Development
288```
289git clone git@github.com:fast-average-color/fast-average-color.git ./fast-average-color
290cd ./fast-average-color
291
292npm i
293npm test
294```
295
296## [License](LICENSE)
297MIT License