0
# Color Space Conversions
1

2
The color conversions module provides comprehensive functionality for converting colors between any supported color spaces. It uses a graph-based conversion engine that handles direct conversions where possible and multi-step transformations when needed.
3

4
## Capabilities
5

6
### Primary Conversion Function
7

8
The main conversion function that handles transformations between any color spaces.
9

10
```python { .api }
11
def convert_color(color, target_cs, through_rgb_type=sRGBColor, target_illuminant=None):
12
    """
13
    Convert color from one space to another.
14
    
15
    Parameters:
16
    - color: Source color object (any ColorBase subclass)
17
    - target_cs: Target color space class (e.g., XYZColor, LabColor)
18
    - through_rgb_type: RGB color space for intermediate conversions (default: sRGBColor)
19
    - target_illuminant: Target illuminant for conversion (default: None, uses source illuminant)
20
    
21
    Returns:
22
    Color object in target color space
23
    
24
    Raises:
25
    - UndefinedConversionError: If conversion path doesn't exist
26
    - InvalidIlluminantError: If illuminant is invalid
27
    """
28
```
29

30
### Matrix Operations
31

32
Low-level matrix operations for RGB color space transformations.
33

34
```python { .api }
35
def apply_RGB_matrix(var1, var2, var3, rgb_type, convtype="xyz_to_rgb"):
36
    """
37
    Apply RGB conversion matrix to convert between XYZ and RGB.
38
    
39
    Parameters:
40
    - var1: X coordinate (XYZ) or R coordinate (RGB)
41
    - var2: Y coordinate (XYZ) or G coordinate (RGB)  
42
    - var3: Z coordinate (XYZ) or B coordinate (RGB)
43
    - rgb_type: RGB color space class (sRGBColor, AdobeRGBColor, etc.)
44
    - convtype: Conversion type ("xyz_to_rgb" or "rgb_to_xyz")
45
    
46
    Returns:
47
    tuple: Transformed color coordinates
48
    """
49
```
50

51
## Supported Color Space Conversions
52

53
The conversion engine supports the following color spaces:
54

55
### CIE Color Spaces
56
- **XYZ** ↔ **Lab** ↔ **Luv** ↔ **xyY**
57
- **Lab** ↔ **LCHab**
58
- **Luv** ↔ **LCHuv**
59

60
### RGB Color Spaces  
61
- **sRGB** ↔ **Adobe RGB**
62
- **RGB** ↔ **XYZ** (with appropriate matrices)
63

64
### Device Color Spaces
65
- **HSL** ↔ **HSV** ↔ **RGB**
66
- **CMY** ↔ **CMYK** ↔ **RGB**
67

68
### Spectral and Advanced
69
- **Spectral** → **XYZ** (via integration)
70
- **IPT** ↔ **XYZ**
71

72
### Conversion Paths
73

74
The conversion engine automatically determines the optimal path between color spaces:
75

76
1. **Direct conversions** when mathematical relationships exist
77
2. **Multi-step conversions** through intermediate color spaces
78
3. **Illuminant adaptation** when source and target illuminants differ
79
4. **RGB intermediate** conversions for device color spaces
80

81
## Usage Examples
82

83
### Basic Conversions
84

85
```python
86
from colormath.color_objects import LabColor, XYZColor, sRGBColor
87
from colormath.color_conversions import convert_color
88

89
# Lab to XYZ
90
lab = LabColor(lab_l=50.0, lab_a=20.0, lab_b=-30.0)
91
xyz = convert_color(lab, XYZColor)
92

93
# XYZ to RGB
94
rgb = convert_color(xyz, sRGBColor)
95

96
# Direct Lab to RGB (automatic multi-step conversion)
97
rgb_direct = convert_color(lab, sRGBColor)
98
```
99

100
### Illuminant Conversion
101

102
```python
103
from colormath.color_objects import LabColor, XYZColor
104
from colormath.color_conversions import convert_color
105

106
# Lab color with D65 illuminant
107
lab_d65 = LabColor(lab_l=50, lab_a=0, lab_b=0, illuminant='d65')
108

109
# Convert to XYZ with different illuminant
110
xyz_a = convert_color(lab_d65, XYZColor, target_illuminant='a')
111

112
# The conversion automatically applies chromatic adaptation
113
```
114

115
### RGB Color Space Conversions
116

117
```python
118
from colormath.color_objects import sRGBColor, AdobeRGBColor
119
from colormath.color_conversions import convert_color
120

121
# sRGB to Adobe RGB
122
srgb = sRGBColor(rgb_r=0.8, rgb_g=0.4, rgb_b=0.2)
123
adobe_rgb = convert_color(srgb, AdobeRGBColor)
124
```
125

126
### Complex Multi-Step Conversions
127

128
```python
129
from colormath.color_objects import HSLColor, LabColor
130
from colormath.color_conversions import convert_color
131

132
# HSL to Lab (automatic path: HSL → RGB → XYZ → Lab)
133
hsl = HSLColor(hsl_h=120, hsl_s=0.8, hsl_l=0.6)
134
lab = convert_color(hsl, LabColor)
135
```
136

137
### Spectral to XYZ Conversion
138

139
```python
140
from colormath.color_objects import SpectralColor, XYZColor
141
from colormath.color_conversions import convert_color
142

143
# Create spectral color
144
spectral = SpectralColor(
145
    spec_400nm=0.064,
146
    spec_410nm=0.065,
147
    # ... wavelength data
148
    spec_700nm=0.108,
149
    observer='2',
150
    illuminant='d65'
151
)
152

153
# Convert to XYZ via integration
154
xyz = convert_color(spectral, XYZColor)
155
```
156

157
### Batch Conversions
158

159
```python
160
from colormath.color_objects import LabColor, sRGBColor
161
from colormath.color_conversions import convert_color
162

163
# Convert multiple colors
164
lab_colors = [
165
    LabColor(50, 20, -30),
166
    LabColor(60, -10, 40),
167
    LabColor(40, 0, 0)
168
]
169

170
rgb_colors = [convert_color(lab, sRGBColor) for lab in lab_colors]
171
```
172

173
## Conversion Performance
174

175
The conversion engine optimizes performance through:
176

177
- **Caching**: Frequently used conversion matrices and constants
178
- **Direct paths**: Shortest mathematical paths between color spaces
179
- **Batch operations**: Efficient handling of multiple conversions
180
- **Lazy loading**: Constants loaded only when needed
181

182
## Error Handling
183

184
The conversion system provides specific error handling:
185

186
```python
187
from colormath.color_exceptions import UndefinedConversionError, InvalidIlluminantError
188
from colormath.color_conversions import convert_color
189

190
try:
191
    result = convert_color(color, target_space)
192
except UndefinedConversionError:
193
    # Handle missing conversion path
194
    pass
195
except InvalidIlluminantError:
196
    # Handle invalid illuminant specification
197
    pass
198
```
199

200
## Illuminant Handling
201

202
The conversion engine automatically handles illuminant differences:
203

204
1. **Same illuminant**: Direct conversion without adaptation
205
2. **Different illuminants**: Automatic chromatic adaptation applied
206
3. **Target illuminant**: Explicitly specify target illuminant
207
4. **Default behavior**: Preserve source illuminant when possible
208

209
## Color Space Support Matrix
210

211
| From/To | XYZ | Lab | Luv | RGB | HSL | HSV | CMY | CMYK | Spectral | IPT |
212
|---------|-----|-----|-----|-----|-----|-----|-----|------|----------|-----|
213
| XYZ     | ✓   | ✓   | ✓   | ✓   | ✓*  | ✓*  | ✓*  | ✓*   | ✗        | ✓   |
214
| Lab     | ✓   | ✓   | ✓*  | ✓*  | ✓*  | ✓*  | ✓*  | ✓*   | ✗        | ✓*  |
215
| Luv     | ✓   | ✓*  | ✓   | ✓*  | ✓*  | ✓*  | ✓*  | ✓*   | ✗        | ✓*  |
216
| RGB     | ✓   | ✓*  | ✓*  | ✓   | ✓   | ✓   | ✓   | ✓    | ✗        | ✓*  |
217
| HSL     | ✓*  | ✓*  | ✓*  | ✓   | ✓   | ✓   | ✓*  | ✓*   | ✗        | ✓*  |
218
| HSV     | ✓*  | ✓*  | ✓*  | ✓   | ✓   | ✓   | ✓*  | ✓*   | ✗        | ✓*  |
219
| CMY     | ✓*  | ✓*  | ✓*  | ✓   | ✓*  | ✓*  | ✓   | ✓    | ✗        | ✓*  |
220
| CMYK    | ✓*  | ✓*  | ✓*  | ✓   | ✓*  | ✓*  | ✓   | ✓    | ✗        | ✓*  |
221
| Spectral| ✓   | ✓*  | ✓*  | ✓*  | ✓*  | ✓*  | ✓*  | ✓*   | ✓        | ✓*  |
222
| IPT     | ✓   | ✓*  | ✓*  | ✓*  | ✓*  | ✓*  | ✓*  | ✓*   | ✗        | ✓   |
223
224
- ✓ = Direct conversion available
225
- ✓* = Multi-step conversion through intermediate color space
226
- ✗ = Conversion not supported (Spectral → other spaces requires integration)