Skip to content

Latest commit

 

History

History

color

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

color

npm version npm downloads Twitter Follow

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

About

Array-based color ops, conversions, multi-color gradients, presets.

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).

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 (see concat()) for more efficient application.

RGBA Porter-Duff compositing

This feature has been moved to the separate @thi.ng/porter-duff package.

Cosine gradients

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

Preview Gradient ID
gradient: blue-cyan blue-cyan
gradient: blue-magenta-orange blue-magenta-orange
gradient: blue-white-red blue-white-red
gradient: cyan-magenta cyan-magenta
gradient: green-blue-orange green-blue-orange
gradient: green-cyan green-cyan
gradient: green-magenta green-magenta
gradient: green-red green-red
gradient: heat1 heat1
gradient: magenta-green magenta-green
gradient: orange-blue orange-blue
gradient: orange-magenta-blue orange-magenta-blue
gradient: purple-orange-cyan purple-orange-cyan
gradient: rainbow1 rainbow1
gradient: rainbow2 rainbow2
gradient: rainbow3 rainbow3
gradient: rainbow4 rainbow4
gradient: red-blue red-blue
gradient: yellow-green-blue yellow-green-blue
gradient: yellow-magenta-cyan yellow-magenta-cyan
gradient: yellow-purple-magenta yellow-purple-magenta
gradient: yellow-red yellow-red

Two-color gradients

The cosineCoeffs() function can be used to compute the cosine gradient coefficients between 2 start/end colors:

// compute gradient coeffs between red / green
cosineGradient(10, cosineCoeffs([1,0,0,1], [0,1,0,1])).map(rgbaCss)
// #ff0000
// #f70800
// #e11e00
// #bf4000
// #966900
// #699600
// #40bf00
// #1ee100
// #08f700
// #00ff00

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

STABLE - used in production

Installation

yarn add @thi.ng/color
// ES module
<script type="module" src="https://unpkg.com/@thi.ng/color?module" crossorigin></script>

// UMD
<script src="https://unpkg.com/@thi.ng/color/lib/index.umd.js" crossorigin></script>

Package sizes (gzipped, pre-treeshake): ESM: 7.19 KB / CJS: 7.56 KB / UMD: 7.14 KB

Dependencies

Usage examples

Several demos in this repo's /examples directory are using this package.

A selection:

Screenshot Description Live demo Source
Heatmap visualization of this mono-repo's commits Source
Visualization of different grid iterator strategies Demo Source
Fork-join worker-based raymarch renderer Demo Source

API

Generated API docs

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

© 2016 - 2020 Karsten Schmidt // Apache Software License 2.0