0
# Colormath
1
2
A comprehensive Python library for color mathematics and conversions between different color spaces. It implements extensive color operations including color space conversions (RGB, Lab, XYZ, etc.), Delta E calculations for measuring color differences, density to spectral conversions, and chromatic adaptation algorithms. The library is designed for scientific and technical applications requiring precise color calculations.
3
4
## Package Information
5
6
- **Package Name**: colormath
7
- **Language**: Python
8
- **Installation**: `pip install colormath`
9
- **Dependencies**: numpy, networkx
10
11
## Core Imports
12
13
```python
14
import colormath
15
```
16
17
Common for working with color objects:
18
19
```python
20
from colormath.color_objects import LabColor, XYZColor, sRGBColor, SpectralColor
21
from colormath.color_conversions import convert_color
22
from colormath.color_diff import delta_e_cie2000
23
```
24
25
## Basic Usage
26
27
```python
28
from colormath.color_objects import LabColor, XYZColor, sRGBColor
29
from colormath.color_conversions import convert_color
30
from colormath.color_diff import delta_e_cie2000
31
32
# Create a Lab color
33
lab = LabColor(lab_l=0.9, lab_a=16.3, lab_b=-2.22)
34
35
# Convert to XYZ color space
36
xyz = convert_color(lab, XYZColor)
37
38
# Convert to RGB for display
39
rgb = convert_color(lab, sRGBColor)
40
print(f"RGB: {rgb.rgb_r:.3f}, {rgb.rgb_g:.3f}, {rgb.rgb_b:.3f}")
41
42
# Get RGB as hex string
43
hex_color = rgb.get_rgb_hex()
44
print(f"Hex: {hex_color}")
45
46
# Calculate color difference
47
lab2 = LabColor(lab_l=0.7, lab_a=14.2, lab_b=-1.80)
48
diff = delta_e_cie2000(lab, lab2)
49
print(f"Delta E: {diff:.2f}")
50
51
# Work with RGB colors
52
rgb_color = sRGBColor(255, 128, 0, is_upscaled=True) # 0-255 values
53
hex_from_rgb = rgb_color.get_rgb_hex() # "#ff8000"
54
rgb_from_hex = sRGBColor.new_from_rgb_hex("#ff8000")
55
```
56
57
## Architecture
58
59
Colormath follows a structured hierarchy for color science operations:
60
61
- **Color Objects**: Individual color space representations (Lab, XYZ, RGB, etc.) with illuminant and observer support
62
- **Color Conversions**: Graph-based conversion engine supporting direct and multi-step transformations between 14+ color spaces
63
- **Color Differences**: Perceptual difference calculations using multiple Delta E algorithms
64
- **Constants & Standards**: Comprehensive collections of illuminants, observers, and industry standards
65
- **Spectral Processing**: Full spectral power distribution support with density calculations
66
- **Color Appearance Models**: Advanced models for sophisticated color science applications
67
68
This design enables precise color calculations for professional applications in computer graphics, printing, textiles, and scientific research.
69
70
## Capabilities
71
72
### Color Objects and Spaces
73
74
Create and manipulate colors in 14+ different color spaces including CIE Lab, XYZ, RGB variants, spectral data, and more. Each color space supports appropriate illuminants and observers.
75
76
```python { .api }
77
class LabColor:
78
def __init__(self, lab_l, lab_a, lab_b, observer='2', illuminant='d50'): ...
79
80
class XYZColor:
81
def __init__(self, xyz_x, xyz_y, xyz_z, observer='2', illuminant='d50'): ...
82
83
class sRGBColor:
84
def __init__(self, rgb_r, rgb_g, rgb_b, is_upscaled=False): ...
85
86
class SpectralColor:
87
def __init__(self, spec_340nm=0.0, spec_350nm=0.0, ..., spec_830nm=0.0, observer='2', illuminant='d50'): ...
88
```
89
90
[Color Objects and Spaces](./color-objects.md)
91
92
### Color Space Conversions
93
94
Convert between any supported color spaces using a comprehensive conversion engine that handles illuminant adaptation and multi-step transformations.
95
96
```python { .api }
97
def convert_color(color, target_cs, through_rgb_type=sRGBColor, target_illuminant=None):
98
"""
99
Convert color from one space to another.
100
101
Parameters:
102
- color: Source color object
103
- target_cs: Target color space class
104
- through_rgb_type: RGB color space for intermediate conversions
105
- target_illuminant: Target illuminant for conversion
106
107
Returns:
108
Color object in target color space
109
"""
110
```
111
112
[Color Space Conversions](./color-conversions.md)
113
114
### Color Difference Calculations
115
116
Calculate perceptual color differences using industry-standard Delta E algorithms including CIE 1976, CIE 1994, CIE 2000, and CMC.
117
118
```python { .api }
119
def delta_e_cie2000(color1, color2, Kl=1, Kc=1, Kh=1):
120
"""
121
Calculate CIE 2000 Delta E difference.
122
123
Parameters:
124
- color1, color2: Color objects to compare
125
- Kl, Kc, Kh: Weighting factors for lightness, chroma, hue
126
127
Returns:
128
float: Delta E difference value
129
"""
130
131
def delta_e_cie1976(color1, color2): ...
132
def delta_e_cie1994(color1, color2, K_L=1, K_C=1, K_H=1, K_1=0.045, K_2=0.015): ...
133
def delta_e_cmc(color1, color2, pl=2, pc=1): ...
134
```
135
136
[Color Difference Calculations](./color-diff.md)
137
138
### Spectral Color and Density
139
140
Work with spectral power distributions and calculate color densities using industry standards for applications in printing and color reproduction.
141
142
```python { .api }
143
def auto_density(color):
144
"""
145
Automatically calculate density for spectral color.
146
147
Parameters:
148
- color: SpectralColor object
149
150
Returns:
151
float: Calculated density value
152
"""
153
154
def ansi_density(color, density_standard): ...
155
```
156
157
[Spectral Color and Density](./spectral-density.md)
158
159
### Constants and Standards
160
161
Access comprehensive collections of illuminants, observers, density standards, and other color science constants used throughout the library.
162
163
```python { .api }
164
# Illuminant constants
165
ILLUMINANTS: dict # Illuminant XYZ values by observer angle
166
OBSERVERS: list # Available observer angles ('2', '10')
167
168
# Color constants
169
CIE_E: float # CIE epsilon constant
170
CIE_K: float # CIE kappa constant
171
172
# Density standards
173
ANSI_STATUS_T_RED: dict
174
ISO_VISUAL: dict
175
VISUAL_DENSITY_THRESH: float
176
```
177
178
[Constants and Standards](./constants-standards.md)
179
180
### Color Appearance Models
181
182
Advanced color appearance models for sophisticated color science applications including CIE CAM02, RLAB, LLAB, and others.
183
184
```python { .api }
185
class CIECAM02:
186
def __init__(self, xyz, **viewing_conditions): ...
187
188
class RLAB:
189
def __init__(self, xyz, **parameters): ...
190
```
191
192
[Color Appearance Models](./color-appearance-models.md)
193
194
### Chromatic Adaptation
195
196
Low-level chromatic adaptation functions for precise color transformations between different illuminants using Bradford, Von Kries, and other adaptation methods.
197
198
```python { .api }
199
def apply_chromatic_adaptation(val_x, val_y, val_z, orig_illum, targ_illum, adaptation='bradford'):
200
"""
201
Apply chromatic adaptation to XYZ values.
202
203
Parameters:
204
- val_x, val_y, val_z: XYZ color values
205
- orig_illum: Original illuminant name
206
- targ_illum: Target illuminant name
207
- adaptation: Adaptation method ('bradford', 'von_kries', etc.)
208
209
Returns:
210
tuple: Adapted XYZ values
211
"""
212
```
213
214
[Chromatic Adaptation](./chromatic-adaptation.md)
215
216
## Error Handling
217
218
Colormath defines custom exceptions for color-specific error handling:
219
220
```python { .api }
221
class ColorMathException(Exception):
222
"""Base exception class for colormath errors."""
223
224
class UndefinedConversionError(ColorMathException):
225
"""Raised when conversion doesn't exist."""
226
227
class InvalidIlluminantError(ColorMathException):
228
"""Raised for invalid illuminants."""
229
230
class InvalidObserverError(ColorMathException):
231
"""Raised for invalid observer angles."""
232
```