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

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.

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.

Links

• Project Homepage: GitLab Pages
• Source Code: GitLab
• Open-Kappa Projects: Index