0
# Color Objects and Spaces
1

2
Color objects represent colors in specific color spaces and provide the foundation for all color operations in colormath. The library supports 14+ color spaces with appropriate illuminant and observer configurations.
3

4
## Capabilities
5

6
### Base Color Classes
7

8
Foundation classes that provide common functionality for all color objects.
9

10
```python { .api }
11
class ColorBase:
12
    """Base class for all color objects."""
13
    def get_value_tuple(self):
14
        """Get color values as tuple."""
15
    
16
    def set_observer(self, observer):
17
        """Set observer angle ('2' or '10')."""
18
    
19
    def set_illuminant(self, illuminant):
20
        """Set illuminant (e.g., 'd65', 'a', 'c')."""
21

22
class IlluminantMixin:
23
    """Mixin for color spaces that support illuminants."""
24
    def get_illuminant_xyz(self):
25
        """Get illuminant XYZ values."""
26
    
27
    def apply_adaptation(self, target_illuminant, adaptation='bradford'):
28
        """Apply chromatic adaptation."""
29

30
class BaseRGBColor(ColorBase):
31
    """Base class for RGB color spaces."""
32
    def get_upscaled_value_tuple(self):
33
        """Get RGB values scaled 0-255."""
34
    
35
    def get_rgb_hex(self):
36
        """Convert RGB to hex string."""
37
    
38
    @classmethod
39
    def new_from_rgb_hex(cls, hex_str):
40
        """Create RGB color from hex string."""
41
```
42

43
### CIE Color Spaces
44

45
Standard CIE color spaces for device-independent color representation.
46

47
```python { .api }
48
class XYZColor(ColorBase, IlluminantMixin):
49
    """CIE XYZ color space."""
50
    def __init__(self, xyz_x, xyz_y, xyz_z, observer='2', illuminant='d50'):
51
        """
52
        Create XYZ color.
53
        
54
        Parameters:
55
        - xyz_x, xyz_y, xyz_z: XYZ coordinates (0-1 range typically)
56
        - observer: Observer angle ('2' or '10')
57
        - illuminant: Illuminant name ('d65', 'a', 'c', etc.)
58
        """
59

60
class xyYColor(ColorBase, IlluminantMixin):
61
    """CIE xyY color space."""
62
    def __init__(self, xyy_x, xyy_y, xyy_Y, observer='2', illuminant='d50'):
63
        """
64
        Create xyY color.
65
        
66
        Parameters:
67
        - xyy_x, xyy_y: Chromaticity coordinates
68
        - xyy_Y: Luminance value
69
        - observer: Observer angle ('2' or '10')
70
        - illuminant: Illuminant name
71
        """
72

73
class LabColor(ColorBase, IlluminantMixin):
74
    """CIE L*a*b* color space."""
75
    def __init__(self, lab_l, lab_a, lab_b, observer='2', illuminant='d50'):
76
        """
77
        Create Lab color.
78
        
79
        Parameters:
80
        - lab_l: Lightness (0-100)
81
        - lab_a: Green-red axis
82
        - lab_b: Blue-yellow axis
83
        - observer: Observer angle ('2' or '10')
84
        - illuminant: Illuminant name
85
        """
86

87
class LuvColor(ColorBase, IlluminantMixin):
88
    """CIE L*u*v* color space."""
89
    def __init__(self, luv_l, luv_u, luv_v, observer='2', illuminant='d50'):
90
        """
91
        Create Luv color.
92
        
93
        Parameters:
94
        - luv_l: Lightness (0-100)
95
        - luv_u, luv_v: Chromaticity coordinates
96
        - observer: Observer angle ('2' or '10')
97
        - illuminant: Illuminant name
98
        """
99

100
class LCHabColor(ColorBase, IlluminantMixin):
101
    """CIE LCH color space (via Lab)."""
102
    def __init__(self, lch_l, lch_c, lch_h, observer='2', illuminant='d50'):
103
        """
104
        Create LCH color via Lab.
105
        
106
        Parameters:
107
        - lch_l: Lightness (0-100)
108
        - lch_c: Chroma
109
        - lch_h: Hue angle (degrees)
110
        - observer: Observer angle ('2' or '10')
111
        - illuminant: Illuminant name
112
        """
113

114
class LCHuvColor(ColorBase, IlluminantMixin):
115
    """CIE LCH color space (via Luv)."""
116
    def __init__(self, lch_l, lch_c, lch_h, observer='2', illuminant='d50'):
117
        """
118
        Create LCH color via Luv.
119
        
120
        Parameters:
121
        - lch_l: Lightness (0-100)
122
        - lch_c: Chroma
123
        - lch_h: Hue angle (degrees)
124
        - observer: Observer angle ('2' or '10')
125
        - illuminant: Illuminant name
126
        """
127
```
128

129
### RGB Color Spaces
130

131
Device-dependent RGB color spaces for display and image processing.
132

133
```python { .api }
134
class sRGBColor(BaseRGBColor):
135
    """Standard RGB color space."""
136
    def __init__(self, rgb_r, rgb_g, rgb_b, is_upscaled=False):
137
        """
138
        Create sRGB color.
139
        
140
        Parameters:
141
        - rgb_r, rgb_g, rgb_b: RGB values (0-1 or 0-255 if upscaled)
142
        - is_upscaled: True if values are 0-255, False if 0-1
143
        """
144

145
class AdobeRGBColor(BaseRGBColor):
146
    """Adobe RGB color space."""
147
    def __init__(self, rgb_r, rgb_g, rgb_b, is_upscaled=False):
148
        """
149
        Create Adobe RGB color.
150
        
151
        Parameters:
152
        - rgb_r, rgb_g, rgb_b: RGB values (0-1 or 0-255 if upscaled)
153
        - is_upscaled: True if values are 0-255, False if 0-1
154
        """
155
```
156

157
### HSL and HSV Color Spaces
158

159
Hue-based color spaces for intuitive color manipulation.
160

161
```python { .api }
162
class HSLColor(ColorBase):
163
    """HSL color space."""
164
    def __init__(self, hsl_h, hsl_s, hsl_l):
165
        """
166
        Create HSL color.
167
        
168
        Parameters:
169
        - hsl_h: Hue (0-360 degrees)
170
        - hsl_s: Saturation (0-1)
171
        - hsl_l: Lightness (0-1)
172
        """
173

174
class HSVColor(ColorBase):
175
    """HSV color space."""
176
    def __init__(self, hsv_h, hsv_s, hsv_v):
177
        """
178
        Create HSV color.
179
        
180
        Parameters:
181
        - hsv_h: Hue (0-360 degrees)
182
        - hsv_s: Saturation (0-1)
183
        - hsv_v: Value (0-1)
184
        """
185
```
186

187
### CMY/CMYK Color Spaces
188

189
Subtractive color spaces for printing applications.
190

191
```python { .api }
192
class CMYColor(ColorBase):
193
    """CMY color space."""
194
    def __init__(self, cmy_c, cmy_m, cmy_y):
195
        """
196
        Create CMY color.
197
        
198
        Parameters:
199
        - cmy_c: Cyan (0-1)
200
        - cmy_m: Magenta (0-1)
201
        - cmy_y: Yellow (0-1)
202
        """
203

204
class CMYKColor(ColorBase):
205
    """CMYK color space."""
206
    def __init__(self, cmyk_c, cmyk_m, cmyk_y, cmyk_k):
207
        """
208
        Create CMYK color.
209
        
210
        Parameters:
211
        - cmyk_c: Cyan (0-1)
212
        - cmyk_m: Magenta (0-1)
213
        - cmyk_y: Yellow (0-1)
214
        - cmyk_k: Black (0-1)
215
        """
216
```
217

218
### Spectral Color
219

220
Full spectral power distribution representation for scientific applications.
221

222
```python { .api }
223
class SpectralColor(ColorBase, IlluminantMixin):
224
    """Spectral power distribution color."""
225
    def __init__(self, 
226
                 spec_340nm=0.0, spec_350nm=0.0, spec_360nm=0.0, spec_370nm=0.0,
227
                 spec_380nm=0.0, spec_390nm=0.0, spec_400nm=0.0, spec_410nm=0.0,
228
                 spec_420nm=0.0, spec_430nm=0.0, spec_440nm=0.0, spec_450nm=0.0,
229
                 spec_460nm=0.0, spec_470nm=0.0, spec_480nm=0.0, spec_490nm=0.0,
230
                 spec_500nm=0.0, spec_510nm=0.0, spec_520nm=0.0, spec_530nm=0.0,
231
                 spec_540nm=0.0, spec_550nm=0.0, spec_560nm=0.0, spec_570nm=0.0,
232
                 spec_580nm=0.0, spec_590nm=0.0, spec_600nm=0.0, spec_610nm=0.0,
233
                 spec_620nm=0.0, spec_630nm=0.0, spec_640nm=0.0, spec_650nm=0.0,
234
                 spec_660nm=0.0, spec_670nm=0.0, spec_680nm=0.0, spec_690nm=0.0,
235
                 spec_700nm=0.0, spec_710nm=0.0, spec_720nm=0.0, spec_730nm=0.0,
236
                 spec_740nm=0.0, spec_750nm=0.0, spec_760nm=0.0, spec_770nm=0.0,
237
                 spec_780nm=0.0, spec_790nm=0.0, spec_800nm=0.0, spec_810nm=0.0,
238
                 spec_820nm=0.0, spec_830nm=0.0, observer='2', illuminant='d50'):
239
        """
240
        Create spectral color with spectral power distribution data.
241
        
242
        Parameters:
243
        - spec_340nm through spec_830nm: Spectral reflectance values at each wavelength (0.0-1.0)
244
        - observer: Observer angle ('2' or '10')
245
        - illuminant: Illuminant name
246
        """
247
    
248
    def calc_density(self):
249
        """Calculate density for this spectral color."""
250
    
251
    def get_numpy_array(self):
252
        """Convert spectral data to NumPy array."""
253
```
254

255
### Advanced Color Spaces
256

257
Specialized color spaces for specific applications.
258

259
```python { .api }
260
class IPTColor(ColorBase):
261
    """IPT color space."""
262
    def __init__(self, ipt_i, ipt_p, ipt_t):
263
        """
264
        Create IPT color.
265
        
266
        Parameters:
267
        - ipt_i: Image (lightness)
268
        - ipt_p: Protan (red-green)
269
        - ipt_t: Tritan (yellow-blue)
270
        """
271
```
272

273
## Usage Examples
274

275
### Basic Color Creation
276

277
```python
278
from colormath.color_objects import LabColor, sRGBColor, XYZColor
279

280
# Create colors in different spaces
281
lab = LabColor(lab_l=50.0, lab_a=20.0, lab_b=-30.0)
282
rgb = sRGBColor(rgb_r=0.8, rgb_g=0.2, rgb_b=0.1)
283
xyz = XYZColor(xyz_x=0.4, xyz_y=0.3, xyz_z=0.2, illuminant='d50')
284
```
285

286
### RGB Hex Conversion
287

288
```python
289
from colormath.color_objects import sRGBColor
290

291
# Create RGB from 0-255 values
292
rgb = sRGBColor(255, 128, 64, is_upscaled=True)
293

294
# Convert to hex
295
hex_color = rgb.get_rgb_hex()  # "#ff8040"
296

297
# Create RGB from hex
298
rgb_from_hex = sRGBColor.new_from_rgb_hex("#ff8040")
299
```
300

301
### Spectral Color
302

303
```python
304
from colormath.color_objects import SpectralColor
305

306
# Create spectral color with wavelength data
307
spectral = SpectralColor(
308
    spec_340nm=0.050,
309
    spec_400nm=0.064,
310
    spec_410nm=0.065,
311
    spec_420nm=0.066,
312
    # ... continue for all wavelengths 340-830nm in 10nm intervals
313
    spec_700nm=0.108,
314
    spec_780nm=0.095,
315
    spec_830nm=0.083,
316
    observer='2',
317
    illuminant='d65'
318
)
319

320
# Calculate density
321
density = spectral.calc_density()
322
```
323

324
### Illuminant and Observer Configuration
325

326
```python
327
from colormath.color_objects import LabColor
328

329
# Create color with specific illuminant and observer
330
lab = LabColor(lab_l=50, lab_a=0, lab_b=0, observer='10', illuminant='a')
331

332
# Change illuminant
333
lab.set_illuminant('d50')
334

335
# Get illuminant XYZ values
336
illum_xyz = lab.get_illuminant_xyz()
337
```