1 | /**
|
2 | * Chroma.js is a tiny library for all kinds of color conversions and color scales.
|
3 | */
|
4 | declare namespace chroma {
|
5 | interface ColorSpaces {
|
6 | rgb: [number, number, number];
|
7 | rgba: [number, number, number, number];
|
8 | hsl: [number, number, number];
|
9 | hsv: [number, number, number];
|
10 | hsi: [number, number, number];
|
11 | lab: [number, number, number];
|
12 | oklab: [number, number, number];
|
13 | lch: [number, number, number];
|
14 | oklch: [number, number, number];
|
15 | hcl: [number, number, number];
|
16 | cmyk: [number, number, number, number];
|
17 | gl: [number, number, number, number];
|
18 | }
|
19 |
|
20 | type InterpolationMode = "rgb" | "hsl" | "hsv" | "hsi" | "lab" | "oklab" | "lch" | "oklch" | "hcl" | "lrgb";
|
21 |
|
22 | interface ChromaStatic {
|
23 | /**
|
24 | * Creates a color from a string representation (as supported in CSS).
|
25 | * Creates a color from a number representation [0; 16777215]
|
26 | *
|
27 | * @param color The string to convert to a color.
|
28 | * @return the color object.
|
29 | */
|
30 | (color: string | number | Color): Color;
|
31 |
|
32 | /**
|
33 | * Create a color in the specified color space using a, b and c as values.
|
34 | *
|
35 | * @param colorSpace The color space to use. Defaults to "rgb".
|
36 | * @return the color object.
|
37 | */
|
38 | (a: number, b: number, c: number, colorSpace?: keyof ColorSpaces): Color;
|
39 |
|
40 | (a: number, b: number, c: number, d: number, colorSpace?: keyof ColorSpaces): Color;
|
41 |
|
42 | /**
|
43 | * Create a color in the specified color space using values.
|
44 | *
|
45 | * @param values An array of values (e.g. [r, g, b, a?]).
|
46 | * @param colorSpace The color space to use. Defaults to "rgb".
|
47 | * @return the color object.
|
48 | */
|
49 | (values: number[], colorSpace?: keyof ColorSpaces): Color;
|
50 |
|
51 | /**
|
52 | * Create a color from a hex or string representation (as supported in CSS).
|
53 | *
|
54 | * This is an alias of chroma.css().
|
55 | *
|
56 | * @param color The string to convert to a color.
|
57 | * @return the color object.
|
58 | */
|
59 | hex(color: string): Color;
|
60 |
|
61 | valid(color: any, mode?: string): boolean;
|
62 |
|
63 | hsl(h: number, s: number, l: number, alpha?: number): Color;
|
64 |
|
65 | hsv(h: number, s: number, v: number, alpha?: number): Color;
|
66 |
|
67 | lab(lightness: number, a: number, b: number, alpha?: number): Color;
|
68 |
|
69 | oklab(lightness: number, a: number, b: number, alpha?: number): Color;
|
70 |
|
71 | lch(l: number, c: number, h: number, alpha?: number): Color;
|
72 |
|
73 | oklch(l: number, c: number, h: number, alpha?: number): Color;
|
74 |
|
75 | /**
|
76 | * Same meaning as lch(), but in different order.
|
77 | */
|
78 | hcl(h: number, c: number, l: number, alpha?: number): Color;
|
79 |
|
80 | rgb(r: number, g: number, b: number, alpha?: number): Color;
|
81 |
|
82 | /**
|
83 | * GL is a variant of RGB(A), with the only difference that the components are normalized to the range of 0..1.
|
84 | */
|
85 | gl(red: number, green: number, blue: number, alpha?: number): Color;
|
86 |
|
87 | /**
|
88 | * Returns a color from the color temperature scale.
|
89 | * light 2000K, bright sunlight 6000K.
|
90 | * Based on Neil Bartlett's implementation.
|
91 | * https://github.com/neilbartlett/color-temperature
|
92 | */
|
93 | temperature(t: number): Color;
|
94 |
|
95 | /**
|
96 | * Mixes two colors. The mix ratio is a value between 0 and 1.
|
97 | * The color mixing produces different results based the color space used for interpolation. Defaults to LRGB.
|
98 | * @example chroma.mix('red', 'blue', 0.25) // => #bf0040
|
99 | * @example chroma.mix('red', 'blue', 0.5, 'hsl') // => #ff00ff
|
100 | */
|
101 | mix(color1: string | Color, color2: string | Color, f?: number, colorSpace?: InterpolationMode): Color;
|
102 |
|
103 | /**
|
104 | * Alias for {@see mix}.
|
105 | */
|
106 | interpolate(color1: string | Color, color2: string | Color, f?: number, colorSpace?: InterpolationMode): Color;
|
107 |
|
108 | /**
|
109 | * Similar to {@link mix}, but accepts more than two colors. Simple averaging of R,G,B components and the alpha
|
110 | * channel.
|
111 | */
|
112 | average(colors: Array<string | Color>, colorSpace?: InterpolationMode, weights?: number[]): Color;
|
113 |
|
114 | /**
|
115 | * Blends two colors using RGB channel-wise blend functions.
|
116 | */
|
117 | blend(
|
118 | color1: string | Color,
|
119 | color2: string | Color,
|
120 | blendMode: "multiply" | "darken" | "lighten" | "screen" | "overlay" | "burn" | "dodge",
|
121 | ): Color;
|
122 |
|
123 | /**
|
124 | * Returns a random color.
|
125 | */
|
126 | random(): Color;
|
127 |
|
128 | /**
|
129 | * Computes the WCAG contrast ratio between two colors.
|
130 | * A minimum contrast of 4.5:1 is recommended {@link https://www.w3.org/TR/WCAG20-TECHS/G18.html}
|
131 | * to ensure that text is still readable against a background color.
|
132 | */
|
133 | contrast(color1: string | Color, color2: string | Color): number;
|
134 |
|
135 | /**
|
136 | * Computes the eucledian distance between two colors in a given color space (default is 'lab').
|
137 | * {@link https://en.wikipedia.org/wiki/Euclidean_distance#Three_dimensions}
|
138 | */
|
139 | distance(color1: string | Color, color2: string | Color, colorSpace?: keyof ColorSpaces): number;
|
140 |
|
141 | /**
|
142 | * Computes color difference {@link https://en.wikipedia.org/wiki/Color_difference#CMC_l:c_.281984.29} as
|
143 | * developed by the Colour Measurement Committee of the Society of Dyers and Colourists (CMC) in 1984.
|
144 | * The implementation is adapted from Bruce Lindbloom.
|
145 | * {@link https://web.archive.org/web/20160306044036/http://www.brucelindbloom.com/javascript/ColorDiff.js}
|
146 | * The parameters L (default 1) and C (default 1) are weighting factors for lightness and chromacity.
|
147 | */
|
148 | deltaE(color1: string | Color, color2: string | Color, L?: number, C?: number): number;
|
149 |
|
150 | /**
|
151 | * chroma.brewer is an map of ColorBrewer scales that are included in chroma.js for convenience.
|
152 | * chroma.scale uses the colors to construct.
|
153 | */
|
154 | brewer: {
|
155 | OrRd: string[];
|
156 | PuBu: string[];
|
157 | BuPu: string[];
|
158 | Oranges: string[];
|
159 | BuGn: string[];
|
160 | YlOrBr: string[];
|
161 | YlGn: string[];
|
162 | Reds: string[];
|
163 | RdPu: string[];
|
164 | Greens: string[];
|
165 | YlGnBu: string[];
|
166 | Purples: string[];
|
167 | GnBu: string[];
|
168 | Greys: string[];
|
169 | YlOrRd: string[];
|
170 | PuRd: string[];
|
171 | Blues: string[];
|
172 | PuBuGn: string[];
|
173 | Viridis: string[];
|
174 | Spectral: string[];
|
175 | RdYlGn: string[];
|
176 | RdBu: string[];
|
177 | PiYG: string[];
|
178 | PRGn: string[];
|
179 | RdYlBu: string[];
|
180 | BrBG: string[];
|
181 | RdGy: string[];
|
182 | PuOr: string[];
|
183 | Set2: string[];
|
184 | Accent: string[];
|
185 | Set1: string[];
|
186 | Set3: string[];
|
187 | Dark2: string[];
|
188 | Paired: string[];
|
189 | Pastel2: string[];
|
190 | Pastel1: string[];
|
191 | };
|
192 |
|
193 | /**
|
194 | * Helper function that computes class breaks based on data.
|
195 | * Mode:
|
196 | * <li>equidistant <code>'e'</code> breaks are computed by dividing the total range of the data into n groups
|
197 | * of equal size.
|
198 | * <li>quantile <code>'q'</code> input domain is divided by quantile ranges.
|
199 | * <li>logarithmic <code>'l'</code> breaks are equidistant breaks but on a logarithmic scale.
|
200 | * <li>k-means <code>'k'</code> breaks use the 1-dimensional
|
201 | * [k-means clustering algorithm]{@link https://en.wikipedia.org/wiki/K-means_clustering} to find (roughly) n
|
202 | * groups of "similar" values. Note that this k-means implementation does not guarantee to find exactly n groups.
|
203 | */
|
204 | limits(data: number[], mode: "e" | "q" | "l" | "k", c: number): number[];
|
205 |
|
206 | /**
|
207 | * Returns a function that
|
208 | * [bezier-interpolates]{@link https://www.vis4.net/blog/posts/mastering-multi-hued-color-scales/} between
|
209 | * colors in Lab space. The input range of the function is [0..1].
|
210 | * You can convert it to a scale instance by calling <code>chroma.bezier(...).scale()</code>
|
211 | */
|
212 | bezier(colors: string[]): { (t: number): Color; scale(): Scale };
|
213 |
|
214 | scale(name: string | Color): Scale;
|
215 |
|
216 | scale(colors?: Array<string | Color>): Scale;
|
217 |
|
218 | cubehelix(): Cubehelix;
|
219 |
|
220 | cmyk(c: number, m: number, y: number, k: number): Color;
|
221 |
|
222 | css(col: string): Color;
|
223 | }
|
224 |
|
225 | interface Color {
|
226 | /**
|
227 | * Get and set the color opacity.
|
228 | */
|
229 | alpha(a: number): Color;
|
230 | alpha(): number;
|
231 |
|
232 | darken(f?: number): Color;
|
233 |
|
234 | mix(targetColor: string | Color, f?: number, colorSpace?: keyof ColorSpaces): Color;
|
235 |
|
236 | brighten(f?: number): Color;
|
237 |
|
238 | /**
|
239 | * Changes the saturation of a color by manipulating the Lch chromacity.
|
240 | */
|
241 | saturate(s?: number): Color;
|
242 |
|
243 | /**
|
244 | * Similar to saturate, but the opposite direction.
|
245 | */
|
246 | desaturate(s?: number): Color;
|
247 |
|
248 | /**
|
249 | * Changes a single channel and returns the result a new chroma object.
|
250 | * @example
|
251 | * // half Lab lightness
|
252 | * chroma('orangered').set('lab.l', '*0.5')
|
253 | * @example
|
254 | * // double Lch saturation
|
255 | * chroma('darkseagreen').set('lch.c', '*2')
|
256 | */
|
257 | set(modechan: string, v: number | string): Color;
|
258 |
|
259 | /**
|
260 | * Returns a single channel value.
|
261 | * Also @see set
|
262 | */
|
263 | get(modechan: string): number;
|
264 |
|
265 | /**
|
266 | * Relative brightness, according to the
|
267 | * [WCAG]{@link http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef} definition. Normalized to
|
268 | * 0 for darkest black and 1 for lightest white.
|
269 | */
|
270 | luminance(): number;
|
271 |
|
272 | /**
|
273 | * Set luminance of color. The source color will be interpolated with black or white until the correct luminance is found.
|
274 | * The color space used defaults to RGB.
|
275 | */
|
276 | luminance(l: number, colorSpace?: InterpolationMode): Color;
|
277 |
|
278 | /**
|
279 | * Get color as hexadecimal string.
|
280 | *
|
281 | * @param mode `auto` - string will include alpha channel only if it's less than 1.
|
282 | * `rgb` - string will not include alpha channel.
|
283 | * `rgba` - string will include alpha channel.
|
284 | *
|
285 | * @example
|
286 | * chroma('orange').hex() === '#ffa500'
|
287 | * chroma('orange').alpha(0.5).hex() === '#ffa50080'
|
288 | * chroma('orange').alpha(0.5).hex('rgb') === '#ffa500'
|
289 | */
|
290 | hex(mode?: "auto" | "rgb" | "rgba"): string;
|
291 |
|
292 | /**
|
293 | * Returns the named color. Falls back to hexadecimal RGB string, if the color isn't present.
|
294 | */
|
295 | name(): string;
|
296 |
|
297 | /**
|
298 | * Returns a RGB() or HSL() string representation that can be used as CSS-color definition.
|
299 | * mode defaults to <code>'rgb'</code>
|
300 | */
|
301 | css(mode?: "hsl"): string;
|
302 |
|
303 | /**
|
304 | * Estimate the temperature in Kelvin of any given color, though this makes the only sense for colors from the
|
305 | * [temperature gradient]{@link ChromaStatic.temperature} above.
|
306 | */
|
307 | temperature(): number;
|
308 |
|
309 | /**
|
310 | * Returns the numeric representation of the hexadecimal RGB color.
|
311 | *
|
312 | * @example
|
313 | * chroma('#000000').num() === 0
|
314 | * chroma('#0000ff').num() === 255
|
315 | * chroma('#00ff00').num() === 65280
|
316 | * chroma('#ff0000').num() === 16711680
|
317 | */
|
318 | num(): number;
|
319 |
|
320 | /**
|
321 | * Returns an array with the red, green, and blue component, each as
|
322 | * number within the range 0..255. Chroma internally stores RGB
|
323 | * channels as floats but rounds the numbers before returning them.
|
324 | * You can pass false to prevent the rounding.
|
325 | *
|
326 | * @example
|
327 | * chroma('orange').rgb() === [255,165,0]
|
328 | * chroma('orange').darken().rgb() === [198,118,0]
|
329 | * chroma('orange').darken().rgb(false) === [198.05,118.11,0]
|
330 | */
|
331 | rgb: (round?: boolean) => ColorSpaces["rgb"];
|
332 |
|
333 | /**
|
334 | * Just like color.rgb but adds the alpha channel to the returned array.
|
335 | *
|
336 | * @example
|
337 | * chroma('orange').rgba() === [255,165,0,1]
|
338 | * chroma('hsla(20, 100%, 40%, 0.5)').rgba() === [204,68,0,0.5]
|
339 | */
|
340 | rgba: (round?: boolean) => ColorSpaces["rgba"];
|
341 |
|
342 | /**
|
343 | * Returns an array with the `hue`, `saturation`, and `lightness`
|
344 | * component. Hue is the color angle in degree (`0..360`), saturation
|
345 | * and lightness are within `0..1`. Note that for hue-less colors
|
346 | * (black, white, and grays), the hue component will be NaN.
|
347 | *
|
348 | * @example
|
349 | * chroma('orange').hsl() === [38.82,1,0.5,1]
|
350 | * chroma('white').hsl() === [NaN,0,1,1]
|
351 | */
|
352 | hsl: () => ColorSpaces["hsl"];
|
353 |
|
354 | /**
|
355 | * Returns an array with the `hue`, `saturation`, and `value`
|
356 | * components. Hue is the color angle in degree (`0..360`),
|
357 | * saturation and value are within `0..1`. Note that for hue-less
|
358 | * colors (black, white, and grays), the hue component will be NaN.
|
359 | *
|
360 | * @example
|
361 | * chroma('orange').hsv() === [38.82,1,1]
|
362 | * chroma('white').hsv() === [NaN,0,1]
|
363 | */
|
364 | hsv: () => ColorSpaces["hsv"];
|
365 |
|
366 | /**
|
367 | * Returns an array with the `hue`, `saturation`, and `intensity`
|
368 | * components, each as number between 0 and 255. Note that for hue-less
|
369 | * colors (black, white, and grays), the hue component will be NaN.
|
370 | *
|
371 | * @example
|
372 | * chroma('orange').hsi() === [39.64,1,0.55]
|
373 | * chroma('white').hsi() === [NaN,0,1]
|
374 | */
|
375 | hsi: () => ColorSpaces["hsi"];
|
376 |
|
377 | /**
|
378 | * Returns an array with the **L**, **a**, and **b** components.
|
379 | *
|
380 | * @example
|
381 | * chroma('orange').lab() === [74.94,23.93,78.95]
|
382 | */
|
383 | lab: () => ColorSpaces["lab"];
|
384 |
|
385 | /**
|
386 | * Returns an array with the **L**, **a**, and **b** components.
|
387 | *
|
388 | * @example
|
389 | * chroma('orange').oklab() === [0.7927,0.0566,0.1614]
|
390 | */
|
391 | oklab: () => ColorSpaces["oklab"];
|
392 |
|
393 | /**
|
394 | * Returns an array with the **Lightness**, **chroma**, and **hue**
|
395 | * components.
|
396 | *
|
397 | * @example
|
398 | * chroma('skyblue').lch() === [79.21,25.94,235.11]
|
399 | */
|
400 | lch: () => ColorSpaces["lch"];
|
401 |
|
402 | /**
|
403 | * Returns an array with the **Lightness**, **chroma**, and **hue**
|
404 | * components.
|
405 | *
|
406 | * @example
|
407 | * chroma('skyblue').oklch() === [0.8148,0.0819,225.8]
|
408 | */
|
409 | oklch: () => ColorSpaces["oklch"];
|
410 |
|
411 | /**
|
412 | * Alias of [lch](#color-lch), but with the components in reverse
|
413 | * order.
|
414 | *
|
415 | * @example
|
416 | * chroma('skyblue').hcl() === [235.11,25.94,79.21]
|
417 | */
|
418 | hcl: () => ColorSpaces["hcl"];
|
419 |
|
420 | /**
|
421 | * Just like color.rgb but adds the alpha channel to the returned
|
422 | * array.
|
423 | *
|
424 | * @example
|
425 | * chroma('orange').rgba() === [255,165,0,1]
|
426 | * chroma('hsla(20, 100%, 40%, 0.5)').rgba() === [204,68,0,0.5]
|
427 | */
|
428 | cmyk: () => ColorSpaces["cmyk"];
|
429 |
|
430 | /**
|
431 | * Returns an array with the cyan, magenta, yellow, and key (black)
|
432 | * components, each as a normalized value between 0 and 1.
|
433 | *
|
434 | * @example
|
435 | * chroma('33cc00').gl() === [0.2,0.8,0,1]
|
436 | */
|
437 | gl: () => ColorSpaces["gl"];
|
438 |
|
439 | /**
|
440 | * Test if a color has been clipped or not.
|
441 | * Colors generated from CIELab color space may have their RGB
|
442 | * channels clipped to the range of [0..255].
|
443 | * Colors outside that range may exist in nature but are not
|
444 | * displayable on RGB monitors (such as ultraviolet).
|
445 | *
|
446 | * @example
|
447 | * chroma.hcl(50, 40, 20).clipped() === true
|
448 | */
|
449 | clipped: () => boolean;
|
450 |
|
451 | /**
|
452 | * The unclipped RGB components.
|
453 | *
|
454 | * @example
|
455 | * chroma.hcl(50, 40, 100)._rgb._unclipped === [322.65,235.24,196.7,1]
|
456 | */
|
457 | _rgb: { _unclipped: ColorSpaces["rgba"] };
|
458 | }
|
459 |
|
460 | interface Scale<OutType = Color> {
|
461 | (c: string[]): Scale;
|
462 |
|
463 | (value: number | null | undefined): OutType;
|
464 |
|
465 | domain(d?: number[], n?: number, mode?: string): this;
|
466 |
|
467 | mode(mode: InterpolationMode): this;
|
468 |
|
469 | gamma(g: number): this;
|
470 |
|
471 | cache(use: boolean): boolean;
|
472 |
|
473 | correctLightness(enable?: boolean): this;
|
474 |
|
475 | padding(p: number | number[]): this;
|
476 |
|
477 | /**
|
478 | * You can call scale.colors(n) to quickly grab `c` equi-distant colors from a color scale. If called with no
|
479 | * arguments, scale.colors returns the original array of colors used to create the scale.
|
480 | */
|
481 | colors(
|
482 | c: number | undefined,
|
483 | format: undefined | null | "alpha" | "darken" | "brighten" | "saturate" | "desaturate",
|
484 | ): Color[];
|
485 | colors(c: number | undefined, format: "luminance" | "temperature"): number[];
|
486 | colors<K extends keyof ColorSpaces>(c: number | undefined, format: K): Array<ColorSpaces[K]>;
|
487 | colors(c: number | undefined, format?: "hex" | "name"): string[];
|
488 |
|
489 | /**
|
490 | * If you want the scale function to return a distinct set of colors instead of a continuous gradient, you can
|
491 | * use scale.classes. If you pass a number the scale will broken into equi-distant classes.
|
492 | * You can also define custom class breaks by passing them as array
|
493 | */
|
494 | classes(c: number | number[]): this;
|
495 |
|
496 | /**
|
497 | * Set out format for scale() call. Passing null will result in a scale which outputs colors.
|
498 | */
|
499 | out(format: null): Scale;
|
500 | out<K extends keyof ColorSpaces>(format: K): Scale<ColorSpaces[K]>;
|
501 | out(format: "hex"): Scale<string>;
|
502 | }
|
503 |
|
504 | interface Cubehelix {
|
505 | /**
|
506 | * Set start color for hue rotation, default=300
|
507 | */
|
508 | start(s: number): Cubehelix;
|
509 |
|
510 | /**
|
511 | * number (and direction) of hue rotations (e.g. 1=360°, 1.5=`540°``), default=-1.5
|
512 | */
|
513 | rotations(r: number): Cubehelix;
|
514 |
|
515 | /**
|
516 | * gamma factor can be used to emphasise low or high intensity values, default=1
|
517 | */
|
518 | gamma(g: number): Cubehelix;
|
519 |
|
520 | /**
|
521 | * lightness range: default: [0,1] (black -> white)
|
522 | */
|
523 | lightness(l: number[]): Cubehelix;
|
524 |
|
525 | /**
|
526 | * You can call cubehelix.scale() to use the cube-helix through the chroma.scale interface.
|
527 | */
|
528 | scale(): Scale;
|
529 | }
|
530 | }
|
531 |
|
532 | declare var chroma: chroma.ChromaStatic;
|
533 |
|
534 | export = chroma;
|
535 | export as namespace chroma;
|