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