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 | Spectral: string[];
|
174 | RdYlGn: string[];
|
175 | RdBu: string[];
|
176 | PiYG: string[];
|
177 | PRGn: string[];
|
178 | RdYlBu: string[];
|
179 | BrBG: string[];
|
180 | RdGy: string[];
|
181 | PuOr: string[];
|
182 | Set2: string[];
|
183 | Accent: string[];
|
184 | Set1: string[];
|
185 | Set3: string[];
|
186 | Dark2: string[];
|
187 | Paired: string[];
|
188 | Pastel2: string[];
|
189 | Pastel1: string[];
|
190 | };
|
191 |
|
192 | /**
|
193 | * Helper function that computes class breaks based on data.
|
194 | * Mode:
|
195 | * <li>equidistant <code>'e'</code> breaks are computed by dividing the total range of the data into n groups
|
196 | * of equal size.
|
197 | * <li>quantile <code>'q'</code> input domain is divided by quantile ranges.
|
198 | * <li>logarithmic <code>'l'</code> breaks are equidistant breaks but on a logarithmic scale.
|
199 | * <li>k-means <code>'k'</code> breaks use the 1-dimensional
|
200 | * [k-means clustering algorithm]{@link https://en.wikipedia.org/wiki/K-means_clustering} to find (roughly) n
|
201 | * groups of "similar" values. Note that this k-means implementation does not guarantee to find exactly n groups.
|
202 | */
|
203 | limits(data: number[], mode: "e" | "q" | "l" | "k", c: number): number[];
|
204 |
|
205 | /**
|
206 | * Returns a function that
|
207 | * [bezier-interpolates]{@link https://www.vis4.net/blog/posts/mastering-multi-hued-color-scales/} between
|
208 | * colors in Lab space. The input range of the function is [0..1].
|
209 | * You can convert it to a scale instance by calling <code>chroma.bezier(...).scale()</code>
|
210 | */
|
211 | bezier(colors: string[]): { (t: number): Color; scale(): Scale };
|
212 |
|
213 | scale(name: string | Color): Scale;
|
214 |
|
215 | scale(colors?: Array<string | Color>): Scale;
|
216 |
|
217 | cubehelix(): Cubehelix;
|
218 |
|
219 | cmyk(c: number, m: number, y: number, k: number): Color;
|
220 |
|
221 | css(col: string): Color;
|
222 | }
|
223 |
|
224 | interface Color {
|
225 | /**
|
226 | * Get and set the color opacity.
|
227 | */
|
228 | alpha(a: number): Color;
|
229 | alpha(): number;
|
230 |
|
231 | darken(f?: number): Color;
|
232 |
|
233 | mix(targetColor: string | Color, f?: number, colorSpace?: keyof ColorSpaces): Color;
|
234 |
|
235 | brighten(f?: number): Color;
|
236 |
|
237 | /**
|
238 | * Changes the saturation of a color by manipulating the Lch chromacity.
|
239 | */
|
240 | saturate(s?: number): Color;
|
241 |
|
242 | /**
|
243 | * Similar to saturate, but the opposite direction.
|
244 | */
|
245 | desaturate(s?: number): Color;
|
246 |
|
247 | /**
|
248 | * Changes a single channel and returns the result a new chroma object.
|
249 | * @example
|
250 | * // half Lab lightness
|
251 | * chroma('orangered').set('lab.l', '*0.5')
|
252 | * @example
|
253 | * // double Lch saturation
|
254 | * chroma('darkseagreen').set('lch.c', '*2')
|
255 | */
|
256 | set(modechan: string, v: number | string): Color;
|
257 |
|
258 | /**
|
259 | * Returns a single channel value.
|
260 | * Also @see set
|
261 | */
|
262 | get(modechan: string): number;
|
263 |
|
264 | /**
|
265 | * Relative brightness, according to the
|
266 | * [WCAG]{@link http://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef} definition. Normalized to
|
267 | * 0 for darkest black and 1 for lightest white.
|
268 | */
|
269 | luminance(): number;
|
270 |
|
271 | /**
|
272 | * Set luminance of color. The source color will be interpolated with black or white until the correct luminance is found.
|
273 | * The color space used defaults to RGB.
|
274 | */
|
275 | luminance(l: number, colorSpace?: InterpolationMode): Color;
|
276 |
|
277 | /**
|
278 | * Get color as hexadecimal string.
|
279 | *
|
280 | * @param mode `auto` - string will include alpha channel only if it's less than 1.
|
281 | * `rgb` - string will not include alpha channel.
|
282 | * `rgba` - string will include alpha channel.
|
283 | *
|
284 | * @example
|
285 | * chroma('orange').hex() === '#ffa500'
|
286 | * chroma('orange').alpha(0.5).hex() === '#ffa50080'
|
287 | * chroma('orange').alpha(0.5).hex('rgb') === '#ffa500'
|
288 | */
|
289 | hex(mode?: "auto" | "rgb" | "rgba"): string;
|
290 |
|
291 | /**
|
292 | * Returns the named color. Falls back to hexadecimal RGB string, if the color isn't present.
|
293 | */
|
294 | name(): string;
|
295 |
|
296 | /**
|
297 | * Returns a RGB() or HSL() string representation that can be used as CSS-color definition.
|
298 | * mode defaults to <code>'rgb'</code>
|
299 | */
|
300 | css(mode?: "hsl"): string;
|
301 |
|
302 | /**
|
303 | * Estimate the temperature in Kelvin of any given color, though this makes the only sense for colors from the
|
304 | * [temperature gradient]{@link ChromaStatic.temperature} above.
|
305 | */
|
306 | temperature(): number;
|
307 |
|
308 | /**
|
309 | * Returns the numeric representation of the hexadecimal RGB color.
|
310 | *
|
311 | * @example
|
312 | * chroma('#000000').num() === 0
|
313 | * chroma('#0000ff').num() === 255
|
314 | * chroma('#00ff00').num() === 65280
|
315 | * chroma('#ff0000').num() === 16711680
|
316 | */
|
317 | num(): number;
|
318 |
|
319 | /**
|
320 | * Returns an array with the red, green, and blue component, each as
|
321 | * number within the range 0..255. Chroma internally stores RGB
|
322 | * channels as floats but rounds the numbers before returning them.
|
323 | * You can pass false to prevent the rounding.
|
324 | *
|
325 | * @example
|
326 | * chroma('orange').rgb() === [255,165,0]
|
327 | * chroma('orange').darken().rgb() === [198,118,0]
|
328 | * chroma('orange').darken().rgb(false) === [198.05,118.11,0]
|
329 | */
|
330 | rgb: (round?: boolean) => ColorSpaces["rgb"];
|
331 |
|
332 | /**
|
333 | * Just like color.rgb but adds the alpha channel to the returned array.
|
334 | *
|
335 | * @example
|
336 | * chroma('orange').rgba() === [255,165,0,1]
|
337 | * chroma('hsla(20, 100%, 40%, 0.5)').rgba() === [204,68,0,0.5]
|
338 | */
|
339 | rgba: (round?: boolean) => ColorSpaces["rgba"];
|
340 |
|
341 | /**
|
342 | * Returns an array with the `hue`, `saturation`, and `lightness`
|
343 | * component. Hue is the color angle in degree (`0..360`), saturation
|
344 | * and lightness are within `0..1`. Note that for hue-less colors
|
345 | * (black, white, and grays), the hue component will be NaN.
|
346 | *
|
347 | * @example
|
348 | * chroma('orange').hsl() === [38.82,1,0.5,1]
|
349 | * chroma('white').hsl() === [NaN,0,1,1]
|
350 | */
|
351 | hsl: () => ColorSpaces["hsl"];
|
352 |
|
353 | /**
|
354 | * Returns an array with the `hue`, `saturation`, and `value`
|
355 | * components. Hue is the color angle in degree (`0..360`),
|
356 | * saturation and value are within `0..1`. Note that for hue-less
|
357 | * colors (black, white, and grays), the hue component will be NaN.
|
358 | *
|
359 | * @example
|
360 | * chroma('orange').hsv() === [38.82,1,1]
|
361 | * chroma('white').hsv() === [NaN,0,1]
|
362 | */
|
363 | hsv: () => ColorSpaces["hsv"];
|
364 |
|
365 | /**
|
366 | * Returns an array with the `hue`, `saturation`, and `intensity`
|
367 | * components, each as number between 0 and 255. Note that for hue-less
|
368 | * colors (black, white, and grays), the hue component will be NaN.
|
369 | *
|
370 | * @example
|
371 | * chroma('orange').hsi() === [39.64,1,0.55]
|
372 | * chroma('white').hsi() === [NaN,0,1]
|
373 | */
|
374 | hsi: () => ColorSpaces["hsi"];
|
375 |
|
376 | /**
|
377 | * Returns an array with the **L**, **a**, and **b** components.
|
378 | *
|
379 | * @example
|
380 | * chroma('orange').lab() === [74.94,23.93,78.95]
|
381 | */
|
382 | lab: () => ColorSpaces["lab"];
|
383 |
|
384 | /**
|
385 | * Returns an array with the **L**, **a**, and **b** components.
|
386 | *
|
387 | * @example
|
388 | * chroma('orange').oklab() === [0.7927,0.0566,0.1614]
|
389 | */
|
390 | oklab: () => ColorSpaces["oklab"];
|
391 |
|
392 | /**
|
393 | * Returns an array with the **Lightness**, **chroma**, and **hue**
|
394 | * components.
|
395 | *
|
396 | * @example
|
397 | * chroma('skyblue').lch() === [79.21,25.94,235.11]
|
398 | */
|
399 | lch: () => ColorSpaces["lch"];
|
400 |
|
401 | /**
|
402 | * Returns an array with the **Lightness**, **chroma**, and **hue**
|
403 | * components.
|
404 | *
|
405 | * @example
|
406 | * chroma('skyblue').oklch() === [0.8148,0.0819,225.8]
|
407 | */
|
408 | oklch: () => ColorSpaces["oklch"];
|
409 |
|
410 | /**
|
411 | * Alias of [lch](#color-lch), but with the components in reverse
|
412 | * order.
|
413 | *
|
414 | * @example
|
415 | * chroma('skyblue').hcl() === [235.11,25.94,79.21]
|
416 | */
|
417 | hcl: () => ColorSpaces["hcl"];
|
418 |
|
419 | /**
|
420 | * Just like color.rgb but adds the alpha channel to the returned
|
421 | * array.
|
422 | *
|
423 | * @example
|
424 | * chroma('orange').rgba() === [255,165,0,1]
|
425 | * chroma('hsla(20, 100%, 40%, 0.5)').rgba() === [204,68,0,0.5]
|
426 | */
|
427 | cmyk: () => ColorSpaces["cmyk"];
|
428 |
|
429 | /**
|
430 | * Returns an array with the cyan, magenta, yellow, and key (black)
|
431 | * components, each as a normalized value between 0 and 1.
|
432 | *
|
433 | * @example
|
434 | * chroma('33cc00').gl() === [0.2,0.8,0,1]
|
435 | */
|
436 | gl: () => ColorSpaces["gl"];
|
437 |
|
438 | /**
|
439 | * Test if a color has been clipped or not.
|
440 | * Colors generated from CIELab color space may have their RGB
|
441 | * channels clipped to the range of [0..255].
|
442 | * Colors outside that range may exist in nature but are not
|
443 | * displayable on RGB monitors (such as ultraviolet).
|
444 | *
|
445 | * @example
|
446 | * chroma.hcl(50, 40, 20).clipped() === true
|
447 | */
|
448 | clipped: () => boolean;
|
449 |
|
450 | /**
|
451 | * The unclipped RGB components.
|
452 | *
|
453 | * @example
|
454 | * chroma.hcl(50, 40, 100)._rgb._unclipped === [322.65,235.24,196.7,1]
|
455 | */
|
456 | _rgb: { _unclipped: ColorSpaces["rgba"] };
|
457 | }
|
458 |
|
459 | interface Scale<OutType = Color> {
|
460 | (c: string[]): Scale;
|
461 |
|
462 | (value: number | null | undefined): OutType;
|
463 |
|
464 | domain(d?: number[], n?: number, mode?: string): this;
|
465 |
|
466 | mode(mode: InterpolationMode): this;
|
467 |
|
468 | gamma(g: number): this;
|
469 |
|
470 | cache(use: boolean): boolean;
|
471 |
|
472 | correctLightness(enable?: boolean): this;
|
473 |
|
474 | padding(p: number | number[]): this;
|
475 |
|
476 | /**
|
477 | * You can call scale.colors(n) to quickly grab `c` equi-distant colors from a color scale. If called with no
|
478 | * arguments, scale.colors returns the original array of colors used to create the scale.
|
479 | */
|
480 | colors(
|
481 | c: number | undefined,
|
482 | format: undefined | null | "alpha" | "darken" | "brighten" | "saturate" | "desaturate",
|
483 | ): Color[];
|
484 | colors(c: number | undefined, format: "luminance" | "temperature"): number[];
|
485 | colors<K extends keyof ColorSpaces>(c: number | undefined, format: K): Array<ColorSpaces[K]>;
|
486 | colors(c: number | undefined, format?: "hex" | "name"): string[];
|
487 |
|
488 | /**
|
489 | * If you want the scale function to return a distinct set of colors instead of a continuous gradient, you can
|
490 | * use scale.classes. If you pass a number the scale will broken into equi-distant classes.
|
491 | * You can also define custom class breaks by passing them as array
|
492 | */
|
493 | classes(c: number | number[]): this;
|
494 |
|
495 | /**
|
496 | * Set out format for scale() call. Passing null will result in a scale which outputs colors.
|
497 | */
|
498 | out(format: null): Scale;
|
499 | out<K extends keyof ColorSpaces>(format: K): Scale<ColorSpaces[K]>;
|
500 | out(format: "hex"): Scale<string>;
|
501 | }
|
502 |
|
503 | interface Cubehelix {
|
504 | /**
|
505 | * Set start color for hue rotation, default=300
|
506 | */
|
507 | start(s: number): Cubehelix;
|
508 |
|
509 | /**
|
510 | * number (and direction) of hue rotations (e.g. 1=360°, 1.5=`540°``), default=-1.5
|
511 | */
|
512 | rotations(r: number): Cubehelix;
|
513 |
|
514 | /**
|
515 | * gamma factor can be used to emphasise low or high intensity values, default=1
|
516 | */
|
517 | gamma(g: number): Cubehelix;
|
518 |
|
519 | /**
|
520 | * lightness range: default: [0,1] (black -> white)
|
521 | */
|
522 | lightness(l: number[]): Cubehelix;
|
523 |
|
524 | /**
|
525 | * You can call cubehelix.scale() to use the cube-helix through the chroma.scale interface.
|
526 | */
|
527 | scale(): Scale;
|
528 | }
|
529 | }
|
530 |
|
531 | declare var chroma: chroma.ChromaStatic;
|
532 |
|
533 | export = chroma;
|
534 | export as namespace chroma;
|