@dynamize/color-utilities v1.0.12

Color Utilities

Tools for all your color needs

Color utilities is a collection of tools used to work with colors.

Features

• Color conversions (ansi16, ansi256, cmy, cmyk, tsl, hsl, hsv, lab, luv, lch xyz ...)
• Color blending
• Color harmony pallet creation
• Color mixers ( such as getting shades, tints and tones)
• Performing Chromatic adaptation

Table of Contents

• Color Utilities - Tools for all your color needs
  • Features
  • Table of Contents
  • About Color Utilities
    • Limits
  • Documentation
    • Dependencies
    • Importing
  • Color
  • Conversions
  • Color Converter
    • RGB Converter
    • XYZ Converter
  • Color Blending
    • Blender
    • blend
  • Color Harmonies
    • Analogous
    • Clash
    • Complementary
    • Split Complementary
    • Four Tone
    • Five Tone
    • Six Tone
    • Neutral
    • Square
    • Tetradic
    • Triadic
  • Color Mixes
    • Tones
    • Tints
    • Shades
  • Chromatic adaptation
    • adapt
    • Adapter
  • Delta E / Color Difference
    • CIE 76
    • CIE 94
    • CIE 00

About Color Utilities

Color Utilities aims to be a one-stop shop for any work related to colors, mostly built with pure functions One can use as little or as much of it as needed or wanted, avoiding unneeded project bloating. In the future, this library will most probably grow further.

Limits

Due to the nature of color spaces, certain conversions are more computationally taxing than others. Further, certain conversions lead to data loss like RGB to Ansi16 and then back to RGB will most probably result in a significant difference in color.

Documentation

npm install --save @dynamize/color-utilities

Dependencies

This library has no dependencies and is completely self-contained.

Importing

Importing is done using the ES static import declaration. Example:

import { Color } from "@dynamize/color-utilities";

In order to use the import declaration in a source file, the file must be interpreted by the runtime as a module.

Color

A Color class is a representation of a color in Color Utilities. Use case for this is when you know you will need values for more then one color space.

Usage examples:

import { Color } from "@dynamize/color-utilities";

const color = new Color("rgb", { red: 238, green: 200, blue: 27 });

console.log(color.data);

• The first argument we pass is a string value and it represents the space in which color values will be passed.
• The second argument is the actual color values and it's passed in form of an object.
• The third argument is optional and has a form of string array or a string "all", if not passed, automatically values for hex, hvs, lab, and cmyk, will be computed, alternatively color spaces listed in the array will be computed.

The result of the above example is:

 Color {
  rgb: { red: 238, green: 200, blue: 27, inGamut: true },
  xyz: { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 },
  hex: 'EEC81B',
  hsv: { hue: 49, saturation: 89, value: 93 },
  lab: {
    luminance: 81.60296053275202,
    a: -1.2482727232548951,
    b: 79.33052440955292
 },
 cmyk: {
   cyan: 0,
   magenta: 15.96638655462185,
   yellow: 88.65546218487395,
   key: 6.666666666666665
  }
 }

Lets see an alternative use:

import { Color } from "@dynamize/color-utilities";

const color = new Color("rgb", { red: 238, green: 200, blue: 27 }, [
  "hsl",
  "luv",
  "ryb",
  "tsl",
]);

console.log(color.data);

Result from the above example would be:

Color {
  rgb: { red: 238, green: 200, blue: 27, inGamut: true },
  xyz: { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 },
  hsl: { hue: 49, saturation: 86, lightness: 52 },
  luv: { L: 81.60296053275202, u: 33.50413039331645, v: 84.4716716630059 },
  ryb: { red: 63.346820809248555, yellow: 228, blue: 17 },
  tsl: {
    tint: 0.4209301051592921,
    saturation: 0.27240784750042124,
    lightness: 0.7515294117647058
  }
}

Note: If you noticed RGB and XYZ values are returned regardless, they are needed for two main family of spaces and there for are computed by default.

If "all" is passed as a third argument, all 45 spaces will be computed (the return example is to big to show here), this option is computationally tasking and it's not a good option for color pickers or other use cases where there is a high frequency of re computation. Accidentally the default (no third argument) will return values utilized in a Photoshop color picker (rgb, hsv, lab, cmyk and hex).

Conversions

Here is a list of all color conversion methods, they are standalone, and can be utilized on their own. Some of them might have multiple conversions and that will be stated in the table.

Color Converter

In situations where you might need to covert from one space into multiple spaces, you can use a color converter. Color Converter is faster and less task-intensive than using Color. There are two prebuilt Color Converters, RGB Converter and the XYZ Converter.

RGB Converter

RGB Converter is a prebuilt Color Converter that takes a single attribute of a type: { red: number, green: number, blue: number } or { r: number, g: number, b: number }.

It has a single method, "get" and it takes an attribute of type string which represents a color space you would like back. Supported conversion are: adobe_98_rgb, apple_rgb, ansi16, ansi256, best_rgb, beta_rgb, bruce_rgb, cie_rgb, color_match_rgb, cmy, cmyk, don_rgb_4, etka_space_ps5, eci_rgb_v2, hcy, hex, hsi, hsl, hsv, hwb, lab, lch_ab, lch_uv, luv, ntsc_rgb, pal_secam_rgb, pro_photo_rgb, ryb, smpte_c_rgb, tsl, uvw, wide_gamut_rgb, ycbcr_BT601, ycbcr_BT709, ycbcr_BT2020, ydbdr, ypbpr, yccbccrc, ycocg, yiq, xvycc, xyz.

Usage example:

import { RgbConverter } from "@dynamize/color-utilities";

const rgbCon = new RgbConverter({ red: 238, green: 200, blue: 27 });

console.log(rgbCon.get("hsv"));

This will return HSV values for the above-given color.

XYZ Converter

XYZ Converter is a prebuilt Color Converter that takes a single attribute of a type: { x: number, y: number, z: number }.

It has a single method, "get" and it takes an attribute of type string which represents a color space you would like back. Supported conversion are: lab, lch_ab, lch_uv, luv, uvw, rgb, adobe_98_rgb, apple_rgb, best_rgb, beta_rgb, bruce_rgb, cie_rgb, color_match_rgb, don_rgb_4, etka_space_ps5, eci_rgb_v2, ntsc_rgb, pal_secam_rgb, pro_photo_rgb, smpte_c_rgb, wide_gamut_rgb, xyy, lms, hunters_lab.

Usage example:

import { XyzConverter } from "@dynamize/color-utilities";

const xyzCon = new XyzConverter({ red: 238, green: 200, blue: 27 });

console.log(xyzCon.get("luv"));

This will return LUV values for the above-given color.

Color Blending

In Color Utilities, there are two ways you can blend colors: either by using the standalone method "blend" or by using a Color Blender.

Blender

Color Blender is quite powerful, it allows you to blend two colors in rgb ,cmyk, hex, hsl ,hsv, hwb, hex, ryb and xyz formats. The two colors do not have to be in the same format to blend them, and the returned color can have any of the following formats: rgb ,cmyk, hex, hsl ,hsv, hwb, hex, ryb, xyz.

Usage example:

import { Blender } from "@dynamize/color-utilities";

const color = new Blender(
  { c: 0, m: 7, y: 100, k: 0 },
  { h: 0, s: 100, v: 100 },
  { weight: 0.67, returnType: "hex" }
);

console.log(color.color);

Color Blender can return two things: color or blend data. Color will just be a color value in the format that was requested, blend data will give you more information. Below, you can see the blend data for the above example:

{
    color1: {
      data: { cyan: 0, magenta: 7, yellow: 100, key: 0 },
      rgb: { red: 255, green: 237.14999999999998, blue: 0, inGamut: true },
      amount: 0.67,
    },
    color2: {
      data: { hue: 0, saturation: 100, value: 100 },
      rgb: { red: 255, green: 0, blue: 0, inGamut: true },
      amount: 0.32999999999999996,
    },
    resultColor: "FF9F00",
  }

blend

Using the blend method is pretty straight-forward. It takes three parameters, the first two being the RGB values of colors to blend, and the last one is a percentage of the first color, the remaining percentage will be allocated to the second one.

Usage example:

import { blend } from "@dynamize/color-utilities";

const blended = blend(
  { red: 255, green: 237, blue: 0 },
  { red: 255, green: 0, blue: 0 },
  0.67
);

console.log(blended);

Color Harmonies

With Color utilities, you can also generate a number of Harmony pallets. For more information about Harmonies, visit: https://simplified.com/blog/colors/color-harmony All Harmonies are a standalone functions and they all the a color in a HSL format ({ hue: number, saturation: number, lightness: number }) and return an array of hex values. In addition, in addition the second optional parameter is a boolean, which represents if returned hex values should start with a #.

Analogous

Usage example:

import { analogousHarmony } from "@dynamize/color-utilities";

const pallet = analogousHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Clash

Usage example:

import { clashHarmony } from "@dynamize/color-utilities";

const pallet = clashHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Complementary

Usage example:

import { complementaryHarmony } from "@dynamize/color-utilities";

const pallet = complementaryHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Split Complementary

Usage example:

import { splitComplementaryHarmony } from "@dynamize/color-utilities";

const pallet = splitComplementaryHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { splitComplementaryCWHarmony } from "@dynamize/color-utilities";

const pallet = splitComplementaryCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { splitComplementaryCCWHarmony } from "@dynamize/color-utilities";

const pallet = splitComplementaryCCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Four Tone

Usage example:

import { fourToneCWHarmony } from "@dynamize/color-utilities";

const pallet = fourToneCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fourToneCCWHarmony } from "@dynamize/color-utilities";

const pallet = fourToneCCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Five Tone

Usage example:

import { fiveToneAHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneAHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneBHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneBHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneCHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneCHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneDHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneDHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { fiveToneEHarmony } from "@dynamize/color-utilities";

const pallet = fiveToneEHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Six Tone

Usage example:

import { sixToneCWHarmony } from "@dynamize/color-utilities";

const pallet = sixToneCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Usage example:

import { sixToneCCWHarmony } from "@dynamize/color-utilities";

const pallet = sixToneCCWHarmony(
  { hue: 49, saturation: 86, lightness: 52 },
  true
);

console.log(pallet);

Neutral

Usage example:

import { neutralHarmony } from "@dynamize/color-utilities";

const pallet = neutralHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Square

import { squareHarmony } from "@dynamize/color-utilities";

const pallet = squareHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Tetradic

import { tetradicHarmony } from "@dynamize/color-utilities";

const pallet = tetradicHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Triadic

import { triadicHarmony } from "@dynamize/color-utilities";

const pallet = triadicHarmony({ hue: 49, saturation: 86, lightness: 52 }, true);

console.log(pallet);

Color Mixes

Color Utilities also provides three types of color mixes you can get: Shades, Tints and Tones. All of these are generated by a standalone function that receives two arguments, the first being a base color in RGB format, and the second one is an optional options object that can have two values: size (number of colors generated in the pallet) and prefixed (boolean stating if the colors should start with a #). The return value is an array of strings representing hex values.

Tones

import { getTones } from "@dynamize/color-utilities";

const tones = getTones(
  { red: 238, green: 200, blue: 27 },
  { size: 10, prefixed: true }
);

console.log(pallet);

Tints

import { getTints } from "@dynamize/color-utilities";

const tones = getTints(
  { red: 238, green: 200, blue: 27 },
  { size: 10, prefixed: true }
);

console.log(pallet);

Shades

import { getShades } from "@dynamize/color-utilities";

const tones = getShades(
  { red: 238, green: 200, blue: 27 },
  { size: 10, prefixed: true }
);

console.log(pallet);

Chromatic adaptation

Chromatic adaptation can be preformed in two ways, either by using a standalone "adapt" function or by using an Adapter class.

adapt

"adapt" function which takes two arguments, first being XYZ values 0f the color to be adapted, and a string value representing reference illuminant and a destination illuminant.

import { adapt } from "@dynamize/color-utilities";

const adapted = adapt({ x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 }, 'A_B');

console.log(adapted);

The above example will adapt from a from reference illuminant A to destination illuminant B.

Adapter

The Adapter class is a little bit more powerful but slower, it takes two optional arguments, first being color values, second is the color space of those values, if not passed default values will be for color white in XYZ format.

Here is a table of all available formats and values:

Example 1:

import { Adapter } from "@dynamize/color-utilities";

const adapted = new Adapter(
  { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 }
).adapt('A_B');

console.log(adapted);

Example 2:

import { Adapter } from "@dynamize/color-utilities";

const adapter = new Adapter();
const adapted = adapter.set(
  { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 }
).adapt('A_B');

console.log(adapted);

The above example is using the "adapt" method with in the Adapter. The difference being that it takes an optional second argument, which is the desired color space of returned color values.

Example 3:

import { Adapter } from "@dynamize/color-utilities";

const adapter = new Adapter();
const adapted = adapter.set(
  { x: 56.11537464609447, y: 59.56827248834963, z: 9.578873171265526 }
).adapt(
  'A_B', 
  'adobe_98_rgb'
);

console.log(adapted);

Delta E / Color Difference

There are multiple ways to calculate the color difference or color distance. More information about color difference: https://en.wikipedia.org/wiki/Color_difference

Usage examples:

import { comparativeDistance } from "@dynamize/color-utilities";

const diff = comparativeDistance(
  { red: 238, green: 200, blue: 27 },
  { red: 217, green: 122, blue: 37 }
  );

console.log(diff);

CIE 76

import { deltaECIE76Lab } from "@dynamize/color-utilities";

const diff = deltaECIE76Lab(
  { luminance: 81.60296053275202, a: -1.2482727232548951, b: 79.33052440955292 } ,
  { luminance: 60.61218950864361, a: 31.243719367882505, b: 58.52164206596838 }
  );

console.log(diff);

import { deltaECIE76Rgb } from "@dynamize/color-utilities";

const diff =  deltaECIE76Rgb(
  { red: 238, green: 200, blue: 27 },
  { red: 217, green: 122, blue: 37 }
  );

console.log(diff);

CIE 94

import { deltaECIE94Lab } from "@dynamize/color-utilities";

const diff = deltaECIE94Lab(
  { luminance: 81.60296053275202, a: -1.2482727232548951, b: 79.33052440955292 } ,
  { luminance: 60.61218950864361, a: 31.243719367882505, b: 58.52164206596838 }
  );

console.log(diff);

CIE 00

import { deltaECIE00Lab } from "@dynamize/color-utilities";

const diff = deltaECIE00Lab(
  { luminance: 81.60296053275202, a: -1.2482727232548951, b: 79.33052440955292 } ,
  { luminance: 60.61218950864361, a: 31.243719367882505, b: 58.52164206596838 }
  );

console.log(diff);

import { deltaECIE00Rgb } from "@dynamize/color-utilities";

const diff = deltaECIE00Rgb(
  { red: 238, green: 200, blue: 27 },
  { red: 217, green: 122, blue: 37 }
  );

console.log(diff);