Metadata-Version: 2.4
Name: cielab-gamut-tools
Version: 0.1.0
Summary: Calculate and visualize CIELab colour gamuts of displays
Project-URL: Homepage, https://github.com/CIELab-gamut-tools/cielab-gamut-tools-py
Project-URL: Repository, https://github.com/CIELab-gamut-tools/cielab-gamut-tools-py
Project-URL: Issues, https://github.com/CIELab-gamut-tools/cielab-gamut-tools-py/issues
Author-email: Euan Smith <euan1971@yahoo.co.uk>
License-Expression: MIT
License-File: LICENSE
Keywords: CIELab,color,color-science,colorimetry,display,gamut
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.5
Requires-Dist: numba>=0.57
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# cielab-gamut-tools

Calculate and visualize CIELab colour gamuts of displays.

This is a Python port of the [gamut-volume-m](https://github.com/CIELab-gamut-tools/gamut-volume-m) MATLAB library.

## Features

- Load gamut data from CGATS.17 ASCII files or RGB/XYZ matrices
- Support for emissive and reflective displays (IDMS v1.3 format)
- Calculate gamut volumes via cylindrical integration in CIELab space
- Compute gamut intersections for coverage analysis
- Generate synthetic reference gamuts (sRGB, BT.2020, DCI-P3, etc.)
- Visualize gamuts as 3D surfaces or 2D rings

## Installation

```bash
pip install cielab-gamut-tools
```

Or install from source:

```bash
git clone https://github.com/CIELab-gamut-tools/cielab-gamut-tools-py.git
cd cielab-gamut-tools-py
pip install -e .
```

## Quick Start

```python
from cielab_gamut_tools import Gamut, SyntheticGamut

# Load measured display gamut from CGATS file
display = Gamut.from_cgats("measurements.txt")

# Create standard reference gamuts
srgb = SyntheticGamut.srgb()
bt2020 = SyntheticGamut.bt2020()

# Calculate volumes
print(f"Display volume: {display.volume():.0f}")
print(f"sRGB volume: {srgb.volume():.0f}")

# Calculate sRGB coverage
intersection = display.intersect(srgb)
coverage = intersection.volume() / srgb.volume() * 100
print(f"sRGB coverage: {coverage:.1f}%")

# Visualize
display.plot_rings(reference=srgb)
```

## Reference Gamuts

The library includes built-in reference gamuts:

```python
srgb = SyntheticGamut.srgb()        # sRGB (D65, gamma 2.2)
bt2020 = SyntheticGamut.bt2020()    # BT.2020 (D65, gamma 2.4)
dci_p3 = SyntheticGamut.dci_p3()    # DCI-P3 (DCI white, gamma 2.6)
display_p3 = SyntheticGamut.display_p3()  # Display P3 (D65, gamma 2.2)
```

Or create custom gamuts:

```python
custom = SyntheticGamut(
    primaries_xy=[[0.68, 0.32], [0.265, 0.69], [0.15, 0.06]],
    white_xy=[0.3127, 0.329],
    gamma=2.2
)
```

## Development

```bash
# Clone and install with dev dependencies
git clone https://github.com/CIELab-gamut-tools/cielab-gamut-tools-py.git
cd cielab-gamut-tools-py
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=cielab_gamut_tools --cov-report=term-missing

# Type checking
mypy src

# Linting
ruff check src tests
```

## Citation

If you use this software in academic work, please cite:

> Smith, E., et al. (2020). "Gamut volume calculation for display color characterization."
> Journal of the Society for Information Display.

## License

MIT License - see [LICENSE](LICENSE) for details.
