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 |
|
7 | A 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 | ```
|
29 | npm 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 |
|
72 | or
|
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 |
|
110 | const FastAverageColor = require('fast-average-color');
|
111 | const fac = new FastAverageColor();
|
112 | const color = fac.getColor(document.querySelector('img'));
|
113 |
|
114 | console.log(color);
|
115 | ```
|
116 |
|
117 | ### ES Modules
|
118 | [Details](./dist/README.md)
|
119 |
|
120 | ```js
|
121 | import FastAverageColor from 'fast-average-color';
|
122 |
|
123 | const fac = new FastAverageColor();
|
124 | const color = fac.getColor(document.querySelector('img'));
|
125 |
|
126 | console.log(color);
|
127 | ```
|
128 |
|
129 | ### TypeScript
|
130 | ```ts
|
131 | import * as FastAverageColor from 'fast-average-color';
|
132 |
|
133 | const fac = new FastAverageColor();
|
134 | const color = fac.getColor(document.querySelector('img'));
|
135 |
|
136 | console.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 |
|
161 | Get the average color from a resource (loaded images, videos or canvas).
|
162 |
|
163 | ```js
|
164 | const fac = new FastAverageColor();
|
165 | let color;
|
166 |
|
167 | // From loaded image (HTMLImageElement)
|
168 | color = fac.getColor(image);
|
169 |
|
170 | // From loaded image with default color
|
171 | color = fac.getColor({
|
172 | // Set default color - red.
|
173 | defaultColor: [255, 0, 0, 255]
|
174 | });
|
175 |
|
176 | // From loaded image with precision
|
177 | color = fac.getColor({
|
178 | // Modes: 'speed' (by default) or 'precision'.
|
179 | // Current mode is precision.
|
180 | mode: 'precision'
|
181 | });
|
182 |
|
183 | // From canvas (HTMLCanvasElement)
|
184 | color = fac.getColor(canvas);
|
185 |
|
186 | // From video (HTMLVideoElement)
|
187 | color = 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 | ```
|
209 | Get asynchronously the average color from a resource (not loaded images, videos or canvas).
|
210 | ```js
|
211 | const fac = new FastAverageColor();
|
212 |
|
213 | // From not loaded image (HTMLImageElement)
|
214 | fac.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 |
|
247 | Get the average color from a array when 1 pixel is 4 bytes.
|
248 | ```js
|
249 | const fac = new FastAverageColor();
|
250 | const buffer = [
|
251 | // red, green, blue, alpha
|
252 | 200, 200, 200, 255,
|
253 | 100, 100, 100, 255
|
254 | ];
|
255 | const color = fac.getColorFromArray4(buffer);
|
256 | console.log(color);
|
257 | // [150, 150, 150, 255]
|
258 | ```
|
259 |
|
260 |
|
261 | ### `.destroy()`
|
262 | ```js
|
263 | const fac = new FastAverageColor();
|
264 | const color = fac.getColor(document.querySelector('img'));
|
265 |
|
266 | //...
|
267 |
|
268 | // The instance is no longer needed.
|
269 | fac.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
|
281 | const fac = new FastAverageColor();
|
282 | console.log(fac.getColor(image, {algorithm: 'dominant'});
|
283 | ```
|
284 |
|
285 | ## [Different Builds](./dist/README.md)
|
286 |
|
287 | ## Development
|
288 | ```
|
289 | git clone git@github.com:fast-average-color/fast-average-color.git ./fast-average-color
|
290 | cd ./fast-average-color
|
291 |
|
292 | npm i
|
293 | npm test
|
294 | ```
|
295 |
|
296 | ## [License](LICENSE)
|
297 | MIT License
|