Skip to main content

Getting Started

Color utilities for Node.js.

The purpose of this library is to:

  • Simplify conversion between multiple color spaces, including RGB (at any bit depth), HSV, HSL, HSI, HSP, CYMK, YIQ, XYZ, xyY, L*a*b*, L*u*v*, Y'PbPr, Y'CbCr, and more.
  • Allow basic color modifications (e.g. lighten, darken, saturate) on any color type.
  • Allow for easy generation of color schemes and gradients based on a variety of methods.

Installation​

npm i chromaticity-color-utilities

Basic Usage​

Javascript​

const Color = require('chromaticity-color-utilities')

const color1 = Color.from('rgb', [255, 128, 0]).to('hsv')
// color1 = hsv: { h: 34, s: 100, v: 88, a: 100 }

TypeScript​

import Color from 'chromaticity-color-utilites'

const color1: Color.hsv = Color.from('rgb', [255, 128, 0]).to('hsv')
// color1 = hsv: { h: 34, s: 100, v: 88, a: 100 }

Immutability​

This library follows the rule of immutability. That is, each conversion or modification returns a new object rather than modifying the existing object. Properties can be accessed via get?() methods.

const color1: Color.rgb = Color.from('rgb', [255, 128, 0])
const color2: Color.hsv = color1.to('hsv')
const red: number = color1.getR()
const hue: number = color2.getH()

Further Example Usage​

Converting a HEX string to 10-bit Rec. 709 RGB at video levels​

const color2 = Color.from('hex', 'ff3201').to('rec709rgb', { bitRate: 10 })
// rec709rgb { r: 940, g: 298, b: 67, a: 1023, bitDepth: 10, max: 1023 }

Converting a HEX string/integer to L*a*b*​

const color6 = Color.from('hex', '#f0f').to('lab')
// defaulting to sRGB color space with a D65 standard illuminant reference white
// lab { l: 60, a: 98, b: -61 }

const color6 = Color.from('hex', 0xff00ff).to('lab', {
  colorSpace: 'AdobeRGB',
  referenceWhite: 'D50',
})
// lab { l: 68, a: 101, b: -51 }

Converting an HSL color to a Y'PbPr analog video signal​

const color7 = Color.from('hsl', [300, 100, 50]).to('ypbpr', {
  kb: 0.0722,
  kr: 0.2126,
})
// ypbpr { y: 0.2848, pb: 0.3854278939426601, pr: 0.45415290830581667 }

Blending two colors together​

const blend1 = Color.from('rgb', [255, 0, 0]).modify('blend', {
  with: Color.from('rgb', [0, 255, 0]),
})
// rgb { r: 128, g: 128, b: 0, a: 255, bitDepth: 8, max: 255 }

const blend2 = Color.from('hex', 'ee5432')
  .modify('blend', {
    with: Color.from('rgb', [234, 100, 20, 64]),
    amount: 1 / 3,
  })
  .to('hsv')
// hsv { h: 15, s: 83, v: 93, a: 75 }

Generating color schemes​

const scheme1 = Color.from('rgb', [200, 180, 0]).scheme('splitComplement')
// [
//   rgb { r: 200, g: 180, b: 0, a: 255, bitDepth: 8, max: 255 },
//   rgb { r: 0, g: 120, b: 200, a: 255, bitDepth: 8, max: 255 },
//   rgb { r: 80, g: 0, b: 200, a: 255, bitDepth: 8, max: 255 }
// ]

const scheme2 = Color.from('hsl', [180, 80, 48]).scheme('tetradic', {
  angle: 40,
})
// [
//   hsl { h: 180, s: 80, l: 48, a: 100 },
//   hsl { h: 220, s: 80, l: 48, a: 100 },
//   hsl { h: 40, s: 80, l: 48, a: 100 },
//   hsl { h: 0, s: 80, l: 48, a: 100 }
// ]

Converting an RGB color to HSV, darkening it 20%, and generating a tetradic color scheme​

const scheme1 = Color.from('rgb', [200, 100, 150])
  .to('hsl')
  .modify('darken', { amount: 0.2 })
  .scheme('tetradic')
// [
//   hsl { h: 330, s: 48, l: 47, a: 100 },
//   hsl { h: 15, s: 48, l: 47, a: 100 },
//   hsl { h: 195, s: 48, l: 47, a: 100 },
//   hsl { h: 150, s: 48, l: 47, a: 100 }
// ]