npm package: @open-kappa/colors
Description: Color library
Latest version: 0.1.2

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

```bash
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.

```typescript
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.

```typescript
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.

```mermaid
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](https://open-kappa.gitlab.io/nodejs/colors)
* **Source Code:** [GitLab](https://gitlab.com/open-kappa/nodejs/colors)
* **Open-Kappa Projects:** [Index](https://open-kappa.gitlab.io)