Metadata-Version: 2.4
Name: build-color
Version: 1.0.1
Summary: Python color-science workbench for HDR tone mapping, appearance models, Delta E, spectral, ICC, and LUT workflows
Author: Zain Dana Harper
License: FSL-1.1-MIT
Project-URL: Homepage, https://github.com/HarperZ9/build-color
Project-URL: Repository, https://github.com/HarperZ9/build-color
Project-URL: Issues, https://github.com/HarperZ9/build-color/issues
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Requires-Dist: numpy>=1.24
Provides-Extra: gui
Requires-Dist: PyQt6<7,>=6.5; extra == "gui"
Requires-Dist: build-ui>=1.0.0; extra == "gui"
Provides-Extra: all
Requires-Dist: scipy<2,>=1.10; extra == "all"
Requires-Dist: Pillow<11,>=10.0; extra == "all"
Requires-Dist: PyQt6<7,>=6.5; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=5; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="docs/brand/build-color-hero.png" alt="Build Color, a Python color-science workbench">
</p>
<!-- Project mark: docs/brand/build-color-mark.svg -->

# Build Color

> Python color-science workbench for perceptual spaces, HDR tone mapping, color appearance models, Delta E metrics, chromatic adaptation, spectral utilities, and ICC profile generation.

[Project Telos](https://harperz9.github.io) | [gather](https://github.com/HarperZ9/gather) | [crucible](https://github.com/HarperZ9/crucible) | [index](https://github.com/HarperZ9/index) | [forum](https://github.com/HarperZ9/forum) | [telos](https://github.com/HarperZ9/telos) | [emet](https://github.com/HarperZ9/emet) | [buildlang](https://github.com/HarperZ9/buildlang)

[![CI](https://github.com/HarperZ9/build-color/actions/workflows/ci.yml/badge.svg)](https://github.com/HarperZ9/build-color/actions/workflows/ci.yml)
![version: 1.0.1](https://img.shields.io/badge/version-1.0.1-informational.svg)
![python: 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)
![core dep: numpy](https://img.shields.io/badge/core%20dep-numpy-success.svg)
[![license: fair-source](https://img.shields.io/badge/license-fair--source-blue.svg)](LICENSE)
[![part of: Project Telos](https://img.shields.io/badge/part_of-Project_Telos-4636e8.svg)](https://harperz9.github.io)

Build Color is a Python color-science workbench for people who need more than
hex conversion. It covers perceptual spaces, HDR tone mapping, color appearance
models, Delta E metrics, chromatic adaptation, spectral utilities, ICC profile
generation, and an optional GUI.

## Quick Start

```bash
pip install ".[all]"
build-color
```

Launch the GUI, or use the CLI:

```bash
build-color info ff6030
build-color convert ff6030 --to oklab
build-color difference ff0000 00ff00 --metric all
build-color harmony ff6030 --scheme triadic
build-color spectrum --temp 6500
build-color icc --gamma 2.2 --output display.icc
```

## Features

### Color Spaces (15+)
sRGB, Linear RGB, XYZ, xyY, CIELAB, LCH, Oklab, Oklch, JzAzBz, JzCzhz, ICtCp, HSV, Display P3, BT.2020, Adobe RGB, ACEScg

### Tone Mapping (12 operators)
ACES (Narkowicz + Hill), AgX (neutral/punchy/golden), Reinhard (simple + extended), Hable/Uncharted 2, Lottes, Uchimura/Gran Turismo, PBR Neutral (Khronos glTF), BT.2390 EETF, BT.2446 Method A, custom knee function

### HDR Processing
PQ (ST.2084) encode/decode, HLG (BT.2100) encode/decode, BT.2390 EETF tone mapping, BT.2446 HDR-to-SDR

### Color Appearance Models
CIECAM02 forward/inverse (machine-epsilon roundtrip), CAM16, CAM16-UCS uniform color space, hue quadrature

### Color Difference (7 metrics)
CIE76, CIE94 (graphics/textiles), CIEDE2000, CMC(l:c), JzAzBz Delta E, Oklab Delta E, HyAB

### Chromatic Adaptation (9 methods)
Bradford, CAT16, CAT02, Sharp, Von Kries, CMCCAT2000, Fairchild, Bianco-Schettini, XYZ Scaling

### Additional
- **Spectral rendering** - Planck blackbody, CIE 1931 CMFs, daylight illuminants, SPD-to-XYZ integration
- **ICC profiles** - Generate ICC v4 display profiles from primaries + gamma
- **CVD simulation** - Protanopia, deuteranopia, tritanopia, achromatopsia (Brettel et al.)
- **Gamut mapping** - Clip, soft compression, Oklab chroma reduction
- **Color harmony** - Complementary, triadic, tetradic, analogous, split complementary, monochromatic

## GUI

Interactive workbench with 5 tools:

- **Color Inspector** - Pick a color, see it in every space with luminance, wavelength, contrast
- **Palette Generator** - Generate harmonious palettes, copy as CSS
- **Color Difference** - Compare two colors across all metrics with visual grades
- **Tone Mapping** - Preview all 12 operators with curve visualization
- **CVD Simulator** - See how colors appear to color-blind viewers

```bash
build-color gui
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `build-color` | Launch GUI (default) |
| `build-color info <color>` | Show color in all spaces + metadata |
| `build-color convert <color> --to <space>` | Convert between color spaces |
| `build-color difference <c1> <c2>` | Compute color difference |
| `build-color harmony <color> --scheme <type>` | Generate palette |
| `build-color adapt <xyz> --from D65 --to D50` | Chromatic adaptation |
| `build-color spectrum --temp <K>` | Blackbody spectral data |
| `build-color icc --gamma 2.2` | Create ICC profile |
| `build-color gui` | Launch GUI workbench |

## Installation

```bash
pip install ".[all]"    # Everything (numpy + scipy + PyQt6)
pip install .           # Core only (numpy)
```

## Python API

```python
import numpy as np
from build_color.spaces import srgb_to_oklab, oklab_to_srgb
from build_color.tonemap import aces_filmic, pq_eotf
from build_color.difference import delta_e_2000
from build_color.adaptation import adapt, ILLUMINANTS
from build_color.appearance import ciecam02_forward, ViewingConditions

# Color space conversion
oklab = srgb_to_oklab(np.array([0.8, 0.2, 0.1]))

# Tone mapping
hdr = np.array([0.0, 0.18, 1.0, 4.0, 10.0])
sdr = aces_filmic(hdr)

# Color difference
lab1 = np.array([50.0, 25.0, -10.0])
lab2 = np.array([60.0, 20.0, -5.0])
de = delta_e_2000(lab1, lab2)

# Chromatic adaptation (adapt XYZ from D65 to D50)
d65 = ILLUMINANTS["D65"]
d50 = ILLUMINANTS["D50"]
xyz = np.array([0.4596, 0.2985, 0.0614])
adapted = adapt(xyz, d65, d50, method="cat16")

# CIECAM02
vc = ViewingConditions(white_point=d65)
appearance = ciecam02_forward(xyz, vc)
print(f"J={appearance.J:.1f}, C={appearance.C:.1f}, h={appearance.h:.0f}")
```

## Architecture

```
build_color/
  spaces.py       15+ color space conversions
  tonemap.py      12 tone mapping operators + PQ/HLG
  appearance.py   CIECAM02, CAM16, CAM16-UCS
  difference.py   7 color difference metrics
  adaptation.py   9 chromatic adaptation methods
  spectral.py     Planck, CIE CMFs, daylight
  icc.py          ICC v4 profile generation
  blindness.py    CVD simulation (4 types)
  gamut.py        Gamut mapping
  harmony.py      6 color harmony schemes
  cli.py          Command-line interface (8 commands)
  gui/            PyQt6 interactive workbench
```

See [USAGE.md](USAGE.md) for an install/build line, the full command and API
reference, and worked examples with expected output.

## License

Build Color is released under the FSL-1.1-MIT.
The source is source-available: you may read, run, modify, and build on it for
any purpose other than a competing commercial use, which is reserved to the
Licensor to fund continued development. Copyright (c) 2022-2026 Zain Dana Harper.
All rights reserved. See [LICENSE](LICENSE).
