color

@thi.ng/color

This project is part of the @thi.ng/umbrella monorepo.

• About
  • Color spaces / modes
  • RGBA transformations
  • RGBA Porter-Duff compositing
  • Cosine gradients
  • Multi-stop gradients
• Status
• Installation
• Dependencies
• Usage examples
• Authors
• License

About

Raw, array-based, color operations, color space conversions, optional type wrappers, multi-color gradients, based on @thi.ng/vectors.

Color spaces / modes

Fast color space conversions (any direction) between:

• CSS (string, hex3/hex4/hex6/hex8, rgba(), hsla(), named colors)
• HCYA (float4)
• HSIA (float4)
• HSLA (float4)
• HSVA (float4)
• Int32 (uint32, 0xaarrggbb)
• RGBA (float4)
• XYZA (float4, aka CIE 1931)
• YCbCr (float4)

Apart from CSS and Int32 colors, all others can be stored as plain arrays, typed array or custom array-like types of (mostly) normalized values ([0,1] interval). Where applicable, the hue too is stored in that range, NOT in degrees.

Apart from conversions, most other operations provided by this package are currently only supporting RGBA colors. These can also be converted to / from sRGB (i.e. linear vs gamma corrected). Additionally, RGBA colors can be pre-multiplied (and post-multiplied) with their alpha channel (see Porter-Duff section below).

Class wrappers

The package provides lightweight class wrappers for each color mode / space. These wrappers act similarly to the Vec2/3/4 wrappers in @thi.ng/vectors, support striding (for mapped memory views), named channel accessor aliases (in addition to array indexing) and are fully compatible with all functions (and act as syntax sugar for generic conversion functions). Wrapper factory functions are provided for convenience.

RGBA transformations

RGBA color matrix transformations, including parametric preset transforms:

• brightness
• contrast
• exposure
• saturation (luminance aware)
• hue rotation
• color temperature (warm / cold)
• sepia (w/ fade amount)
• tint (green / magenta)
• grayscale (luminance aware)
• subtraction/inversion (also available as non-matrix op)
• luminance to alpha

Transformation matrices can be combined using matrix multiplication / concatenation (concat()) for more efficient application.

RGBA Porter-Duff compositing

The package provides all 12 basic Porter-Duff compositing / blending operators, both for colors with pre-multiplied alpha and without.

(Image source)

Cosine gradients

• Original article
• Gradient generator

The following presets are bundled (in cosine-gradients.ts):

rainbow1	rainbow2
rainbow3	rainbow4
yellow-magenta-cyan preset	orange-blue
green-magenta	green-red
green-cyan	blue-cyan
yellow-red	red-blue
yellow-green-blue	blue-white-red
cyan-magenta	yellow-purple-magenta
green-blue-orange	orange-magenta-blue
blue-magenta-orange	magenta-green

Multi-stop gradients

The multiCosineGradient() function returns an iterator of raw RGBA colors based on given gradient stops. This iterator computes a cosine gradient between each color stop and yields a sequence of RGBA values.

col.multiCosineGradient(
    // num colors to produce
    10,
    // gradient stops (normalized positions, only RGBA colors supported)
    [0.1, col.RED], [0.5, col.GREEN], [0.9, col.BLUE]
)
// convert to CSS
.map(col.rgbaCss)

// [
//   "#ff0000",
//   "#ff0000",
//   "#da2500",
//   "#807f00",
//   "#25da00",
//   "#00ff00",
//   "#00da25",
//   "#00807f",
//   "#0025da",
//   "#0000ff",
//   "#0000ff",
// ]

Status

ALPHA - work in progress

• @thi.ng/geom - 2D/3D geometry types & operations
• @thi.ng/matrices - 2x2, 2x3, 3x3, 4x4 matrix & quaternion ops
• @thi.ng/vectors - optimized 2d/3d/4d and arbitrary length vector ops
• @thi.ng/vector-pools - operations on memory mapped data

Installation

yarn add @thi.ng/color

Dependencies

• @thi.ng/api
• @thi.ng/compose
• @thi.ng/defmulti
• @thi.ng/errors
• @thi.ng/strings
• @thi.ng/transducers
• @thi.ng/vectors

Usage examples

import * as col from "@thi.ng/color";

// route #1: asXXX() converters: string -> CSS -> ARGB (int) -> RGBA
const a = col.asRGBA(col.css("#3cf"));
// [0.2, 0.8, 1, 1]

// route #2: parseCSS(): string -> RGBA
const b = col.parseCss("hsla(30,100%,50%,0.75)");
// [ 1, 0.5, 0, 0.75 ]

// route #3: convert() multi-method: CSS -> RGBA -> HSVA
// (see convert.ts)
const c = col.convert("rgb(0,255,255)", col.ColorMode.HSVA, col.ColorMode.CSS);
// [ 0.4999999722222268, 0.9999990000010001, 1, 1 ]

// route #4: direct conversion RGBA -> HSLA -> CSS
// first arg is output color (same calling convention as @thi.ng/vectors)
// (use `null` to mutate the input color)
col.hslaCss(col.rgbaHsla([], [1, 0.5, 0.5, 1]))
// "hsl(0.00,100.00%,75.00%)"

col.luminance(col.css("white"))
col.luminance(0xffffff, col.ColorMode.INT32)
// 1

// apply color matrix (RGBA only)
col.transform([], col.saturation(1.25), a)
// [ 0.07835000000000002, 0.82835, 1, 1 ]

// combine matrix transformations
filter = col.concat(
    col.saturation(0.5), // 50% saturation
    col.brightness(0.1), // +10% brightness
);

col.transform([], filter, col.RED);
// [ 0.7065, 0.2065, 0.2065, 1 ]

Authors

• Karsten Schmidt

License

© 2018 Karsten Schmidt // Apache Software License 2.0