Skip to content

mezzario/color-math

Repository files navigation

🤹 color-math

ColorMath is an expression parser and evaluator dealing with color representations. Using special grammar it supports various color models, mixing, blending, channels manipulation, scaling, bezier interpolation and more. It also supports transpiling most of the expressions to less.js.

Install

npm i color-math -S

Usage Example

import * as ColorMath from "color-math"

// will return color which is result of mixing red and green colors
const result = ColorMath.evaluate("red | green")
// prints "#804000" ('result.result' is a chroma.js instance; see link below)
console.log(result.result.hex())

// set color's alpha channel to 30%
result = ColorMath.evaluate("red @a 30%")
console.log(result.result.css()) // prints "rgba(255, 0, 0, 0.3)"

// arithmetic operations with colors and numbers
result = ColorMath.evaluate("(#222 + #444) / 2")
console.log(result.resultStr) // prints "#333333"

// transpile to Less
result = ColorMath.evaluate("rgb 165 42 42 >> .2", { evaluator: new ColorMath.Evaluators.LessEvaluator() })
console.log(result.result) // prints "saturate(rgb(165, 42, 42), 20%, relative)"

chroma.js color library is used internally to manipulate colors and wrap results.

Expressions Cheatsheet

Click on expression to visualize result in ColorMath online parser.

Use parenthesis to control evaluation order and build complex expressions.

Ways to Define Color

Expression Description
#ffcc00 hexadecimal color representation
ffcc00 hexadecimal color representation without hash symbol
#fc0 short hexadecimal color representation
fc0 short hexadecimal color representation without hash symbol
skyblue color literals from W3C/X11 specification
rand generate random color
num 33023 color from number
temp 3500 color by temperature in Kelvin
wl 560 color from wavelength value

Color Models

Expression Description
rgb 127 255 212 RGB color model
rgba 135 206 235 75% RGB color model with alpha channel
argb .7 255 99 71 RGB color model with alpha channel (first)
cmyk .43 .12 0 .8 CMYK color model
cmyka 0 .61 .72 0 60% CMYK color model with alpha channel
cmy .5 0 .17 CMY color model
cmya 0 .61 .72 .65 CMY color model with alpha channel
hsl 159.8 100% 75% HSL color model
hsla 197 .71 .73 55% HSL color model with alpha channel
hsv 160 .5 1 HSV (also known as HSB) color model
hsb 197 .43 .92 HSB color model (alias for HSV)
hsva 9 .72 1 50% HSV color model with alpha channel
hsi 161 .36 .78 HSI color model
hsia 196 .30 .75 45% HSI color model with alpha channel
lab 92 (-46) 9.7 LAB color model
laba 79 (-14.8) (-21) 40% LAB color model with alpha channel
lch 92 46.5 168 LCH color model
lcha 79 26 235 35% LCH color model with alpha channel
hcl 168 46.5 92 HCL color model (reversed LCH)
hcla 235 26 79 35% HCL color model with alpha channel

Color Operations

Expression Description
#444 * 2 arithmetic operations with numbers
skyblue - 0xf arithmetic operations with numbers
~red invert color
red | green mix colors
red | {25%} green mix colors in variable proportion
red | {25% hsl} green mix colors in variable proportion and specific color model
red | {hsl} green mix colors in specific color model
hotpink << 50% desaturate color
rgb 165 42 42 >> .2 saturate color
temp 4000 <<< 30% darken color
#fc0 >>> 70% lighten color
pink %% hotpink compute WCAG contrast ratio between two colors

Color Blending

Expression Description
#222 + #444 add
#ccc - #111 subtract
#ff6600 * #ccc multiply
#222 / #444 divide
skyblue <<< tomato darken
skyblue >>> tomato lighten
#ff6600 !* #00ff00 screen
#ff6600 ** #999 overlay
olive <* pink hard light
olive *> pink soft light
ffcc00 ^* ccc difference
ffcc00 ^^ ccc exclusion
ffcc00 !^ ccc negate
indigo << red burn
indigo >> red dodge

Color Channels Manipulation

Expression Description
brown @red get channel's value using its name or synonym
#ffcc00 @g get channel's value using its name or synonym
t 5000 @cmyk.y get channel's value using its name or synonym
aquamarine @a = .3 set channel's absolute value
rgb 5 7 9 @hsl.h 90 set channel's absolute value
#000 @lightness 50% set channel's absolute value
red @a /= 2 set relative channel's value
ffcc00 @rgb.r -= 50 set relative channel's value
tomato @s *= 30% set relative channel's value
olive @n get color's numeric value
fff @n 0 set color's absolute numeric value
#0080ff @n /= 2 set color's relative numeric value
#ffe3cd @t get color's temperature in Kelvin
red @t 3500 set color's absolute temperature
ffe3cd @t += 500 set color's relative temperature

Color Scales

Expression Description
scale (red 0f0 blue) scale list of colors (make gradient)
scale (yellow 008ae5) -> 20 grab n equi-distant colors from a color scale
scale (t 2000 t 6000) scale list of colors
bezier (ff0 red #000) perform bezier interpolate of list of colors
bezier (red 0f0) perform bezier interpolate of list of colors
scale (red:.2 0f0:50%) set position of each color (inline)
scale (red 0f0) @domain (.2 .5) set position of each color (as a parameter)
scale (red 0f0) @pad .25 cut off a fraction of the gradient on both sides
bezier (red 0f0) @pad (.1 .3) cut off a fraction of the gradient on both sides
cubehelix Dave Green's cubehelix scaled color scheme
cubehelix @pad (0 .2) cut off a fraction of the gradient on both sides
cubehelix @start 200 start for hue rotation
cubehelix @rot (-.5) number of rotations
cubehelix @hue .5 controls how saturated colors of all hues are
cubehelix @hue (1 0) controls how saturated colors of all hues are
cubehelix @gamma .7 emphasize low or high intensity values
cubehelix @lt (.3 .8) adjust lightness (black to white)
cubehelix @start 200 @rot .5 parameters can be chained
+scale (black red yellow) auto-correct lightness of a scale
+bezier (yellow 0f0 blue) -> 10 auto-correct lightness and grab n equi-distant colors

Numbers

Expression Description
0b01101001 binary
0o151 octal
105 decinal
0x69 hexadecimal
55% percent value
5 + 10 add numbers
-360 * 0.5 + (100 - 40) arithmetic operations
0xf / 0b1010 division
4 ^ (2 / 4) take expression to a specified power

Lists

Expression Description
red 0f0 blue define list of three colors
(pink >> .5) gold define list of two colors

Brewer Constants

OrRd, PuBu, BuPu, Oranges, BuGn, YlOrBr, YlGn, Reds, RdPu, Greens, YlGnBu, Purples, GnBu, Greys, YlOrRd, PuRd, Blues, PuBuGn, Spectral, RdYlGn, RdBu, PiYG, PRGn, RdYlBu, BrBG, RdGy, PuOr, Set2, Accent, Set1, Set3, Dark2, Paired, Pastel2, Pastel1

Variables and Statements

Expression Description
$col = rgb 255 204 0 assign color value to a variable
$num = 2^8 - 1 assign number value to a variable
$lst = #444 #888 assign list value to a variable
$my = yellow black; bezier $my separate statements with semicolon

A read–eval–print loop (REPL)

npm start

Interpreter will start. Now you can type your expressions.

Demo and documentation

Please go to http://colormath.net/ to test your expressions, visualize results and read about all available features with examples.