@OPEN-KAPPA/COLORS

@open-kappa/colors

A professional, high-precision color manipulation library for TypeScript and JavaScript. Designed for scientific accuracy, HDR workflows, and modern web standards.

Play with the showcase: https://colors-showcase-fc8b25.gitlab.io/

Features

Type-Safe: Written purely in strict TypeScript.
Universal: Supports both ESM (EcmaScript Modules) and CommonJS. Works in Node.js and Browsers.
Professional Grade: Designed with many advanced use cases in mind.
- Immutable Objects For predictable state management.
- High Precision: Uses spectral calculations and high-bit depth logic where applicable. 1 * HDR Support: Handles out-of-bound values (values > 1.0 or < 0.0) natively without clamping.
Advanced Capabilities:
- Tone Mapping: Includes industry standards like AgX, ACES (Rgb/Luminance), and Reinhard.
- Gamut Mapping: Perceptual compression using Oklch/Oklab logic.
- Chromatic Adaptation: Automatic White Point balancing (e.g., D50 D65) using Bradford matrices.
Utilities:
- Accessibility: WCAG contrast ratios and APCA.
- CVD: Color Vision Deficiency (Color Blindness) simulation and correction.
- Extraction: K-Means and Median Cut algorithms for palette generation from images.
- Generators: Palettes, scales, gradients, and statistical distributions.
Tree-Shakeable: Import only what you need.

Installation

npm install @open-kappa/colors
// Or
bun install @open-kappa/colors

Quick Start

Basic Conversion

Simple conversion between spaces. By default, high-precision mathematical conversions are used.

import {
    Hex,
    Oklch
} from "@open-kappa/colors"

// Parse a color
const red = Hex.fromRgbHexString("#FF0000")

// Convert to modern perceptual space
const oklch = red.to(Oklch)
console.log(oklch.components) // [0.627, 0.257, 29.23, 1]

Advanced HDR Pipeline

Handle complex scenarios like converting an HDR Rec.2020 color to a standard sRGB monitor, applying Tone Mapping and Gamut Mapping automatically.

import {
    Base,
    Rec2020,
    Rgb
} from "@open-kappa/colors"

// An extremely bright HDR red (unsupported by standard monitors)
const superBright = Rec2020.fromComponents([2.0, 0, 0, 1])

// "The Ultimate Conversion": White Balance -> Tone Map -> Gamut Map
const displayReady = Base.convert(superBright, Rgb, {
    "gamutMapping": true,
    // Use modern AgX filmic tone mapping
    "toneMapping": {"fn": "agX", "look": "punchy"},
    "whiteBalance": "bradford"
})

Supported Spaces

Currently supports 28 color spaces, including legacy, print, and modern HDR standards:

Standard RGB: RGB (sRGB), Linear RGB, P3 (Display P3), Adobe RGB, ProPhoto RGB (ROMM RGB), Rec.2020, Rec.709
CIE Standards: XYZ (D65), XYZ D50, xyY, Lab (CIELAB), Luv, Lch (CIELCH), Lch(uv)
Perceptual & HDR: Oklab, Oklch, ICtCp (ITU-R BT.2100), JzAzBz (IzAzBz), JzCzHz
LMS: LMS (Oklab/V3), Lms2006, LmsCat02, LmsHpe
Digital Video/Legacy: YCbCr, YUV, ACEScg
Cylindrical/Web: HSL, HSV (HSB), HWB
Print: CMYK

Architecture

To ensure maintainability and tree-shakability, the library uses a Star Topology. Every color space maps directly to/from XYZ (D65). This allows conversion between any two spaces in exactly two steps, avoiding the complexity of direct converters.

%%{init:{"theme":"dark"}}%% flowchart LR XYZ <--> AcesCg XYZ <--> aRgb[Adobe RGB] XYZ <--> CMYK XYZ <--> LinearRGB XYZ <--> HSL XYZ <--> ICtCp XYZ <--> JzAzBz XYZ <--> JzCzHz XYZ <--> Lab XYZ <--> Lch XYZ <--> LchUv XYZ <--> LMS XYZ <--> Luv XYZ <--> Lms2006 XYZ <--> LmsCat02 XYZ <--> LmsHpe XYZ <--> OKLAB XYZ <--> OKLCH XYZ <--> ProPhoto XYZ <--> Rec.2020 XYZ <--> Rec.709 XYZ <--> RGB XYZ <--> HSV XYZ <--> HWB XYZ <--> P3 XYZ <--> xyY XYZ <--> XYZ-D50 XYZ <--> YCbCr XYZ <--> YUV

%%{init:{"theme":"default"}}%% flowchart LR XYZ <--> AcesCg XYZ <--> aRgb[Adobe RGB] XYZ <--> CMYK XYZ <--> LinearRGB XYZ <--> HSL XYZ <--> ICtCp XYZ <--> JzAzBz XYZ <--> JzCzHz XYZ <--> Lab XYZ <--> Lch XYZ <--> LchUv XYZ <--> LMS XYZ <--> Luv XYZ <--> Lms2006 XYZ <--> LmsCat02 XYZ <--> LmsHpe XYZ <--> OKLAB XYZ <--> OKLCH XYZ <--> ProPhoto XYZ <--> Rec.2020 XYZ <--> Rec.709 XYZ <--> RGB XYZ <--> HSV XYZ <--> HWB XYZ <--> P3 XYZ <--> xyY XYZ <--> XYZ-D50 XYZ <--> YCbCr XYZ <--> YUV

flowchart LR
    XYZ <--> AcesCg
    XYZ <--> aRgb[Adobe RGB]
    XYZ <--> CMYK
    XYZ <--> LinearRGB
    XYZ <--> HSL
    XYZ <--> ICtCp
    XYZ <--> JzAzBz
    XYZ <--> JzCzHz
    XYZ <--> Lab
    XYZ <--> Lch
    XYZ <--> LchUv
    XYZ <--> LMS
    XYZ <--> Luv
    XYZ <--> Lms2006
    XYZ <--> LmsCat02
    XYZ <--> LmsHpe
    XYZ <--> OKLAB
    XYZ <--> OKLCH
    XYZ <--> ProPhoto
    XYZ <--> Rec.2020
    XYZ <--> Rec.709
    XYZ <--> RGB
    XYZ <--> HSV
    XYZ <--> HWB
    XYZ <--> P3
    XYZ <--> xyY
    XYZ <--> XYZ-D50
    XYZ <--> YCbCr
    XYZ <--> YUV

License

@open-kappa/colors is released under the liberal MIT License. Please refer to the LICENSE.txt project file for further details.