0
# Colour Temperature and CCT Calculations
1

2
Comprehensive colour temperature and correlated colour temperature (CCT) calculations supporting multiple computational methods for converting between chromaticity coordinates and temperature values.
3

4
## Capabilities
5

6
### CIE xy to CCT Conversion
7

8
Convert CIE xy chromaticity coordinates to correlated colour temperature using various computational methods.
9

10
```python { .api }
11
def xy_to_CCT(xy: ArrayLike, method: str = "CIE Illuminant D Series") -> NDArray:
12
    """
13
    Calculate correlated colour temperature from CIE xy chromaticity coordinates.
14
    
15
    Parameters:
16
    - xy: CIE xy chromaticity coordinates as ndarray shape (2,) or (..., 2)
17
    - method: computation method
18
        - "CIE Illuminant D Series" (default): CIE D-illuminant series method
19
        - "Hernandez 1999": Hernández-Andrés, Lee, and Romero (1999) method
20
        - "Kang 2002": Kang et al. (2002) method
21
        - "McCamy 1992": McCamy's (1992) approximation method
22
    
23
    Returns:
24
    Correlated colour temperature in Kelvin
25
    """
26

27
# Method collection for xy to CCT conversion
28
XY_TO_CCT_METHODS: Dict[str, Callable]
29
```
30

31
### CCT to CIE xy Conversion
32

33
Convert correlated colour temperature to CIE xy chromaticity coordinates.
34

35
```python { .api }
36
def CCT_to_xy(CCT: ArrayLike, method: str = "CIE Illuminant D Series") -> NDArray:
37
    """
38
    Calculate CIE xy chromaticity coordinates from correlated colour temperature.
39
    
40
    Parameters:
41
    - CCT: correlated colour temperature in Kelvin
42
    - method: computation method (same options as xy_to_CCT)
43
    
44
    Returns:
45
    CIE xy chromaticity coordinates as ndarray shape (2,) or (..., 2)
46
    """
47

48
# Method collection for CCT to xy conversion
49
CCT_TO_XY_METHODS: Dict[str, Callable]
50
```
51

52
### CIE uv to CCT Conversion
53

54
Convert CIE UCS uv chromaticity coordinates to correlated colour temperature with delta uv.
55

56
```python { .api }
57
def uv_to_CCT(uv: ArrayLike, method: str = "Ohno 2013", **kwargs) -> NDArray:
58
    """
59
    Calculate correlated colour temperature and Duv from CIE UCS uv coordinates.
60
    
61
    Parameters:
62
    - uv: CIE UCS uv chromaticity coordinates as ndarray shape (2,) or (..., 2)
63
    - method: computation method
64
        - "Ohno 2013" (default): Ohno (2013) method with Duv calculation
65
        - "Krystek 1985": Krystek (1985) optimization method
66
        - "Planck 1900": Planckian radiator method
67
        - "Robertson 1968": Robertson (1968) isotemperature lines method
68
    - **kwargs: additional method-specific parameters
69
    
70
    Returns:
71
    ndarray with CCT in Kelvin and Duv as [CCT, Duv]
72
    """
73

74
# Method collection for uv to CCT conversion
75
UV_TO_CCT_METHODS: Dict[str, Callable]
76
```
77

78
### CCT to CIE uv Conversion
79

80
Convert correlated colour temperature and delta uv to CIE UCS uv chromaticity coordinates.
81

82
```python { .api }
83
def CCT_to_uv(CCT_D_uv: ArrayLike, method: str = "Ohno 2013", **kwargs) -> NDArray:
84
    """
85
    Calculate CIE UCS uv coordinates from correlated colour temperature and Duv.
86
    
87
    Parameters:
88
    - CCT_D_uv: array containing [CCT, Duv] values
89
    - method: computation method (same options as uv_to_CCT)
90
    - **kwargs: additional method-specific parameters
91
    
92
    Returns:
93
    CIE UCS uv chromaticity coordinates as ndarray shape (2,) or (..., 2)
94
    """
95

96
# Method collection for CCT to uv conversion
97
CCT_TO_UV_METHODS: Dict[str, Callable]
98
```
99

100
### Specialized Temperature Functions
101

102
Additional temperature-related utility functions for specific applications.
103

104
```python { .api }
105
def CCT_to_XYZ_Ohno2013(CCT_D_uv: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None) -> NDArray:
106
    """
107
    Convert CCT and Duv to CIE XYZ tristimulus values using Ohno (2013) method.
108
    
109
    Parameters:
110
    - CCT_D_uv: array containing [CCT, Duv] values
111
    - cmfs: colour matching functions
112
    
113
    Returns:
114
    CIE XYZ tristimulus values
115
    """
116

117
def XYZ_to_CCT_Ohno2013(XYZ: ArrayLike, cmfs: XYZ_ColourMatchingFunctions = None, **kwargs) -> NDArray:
118
    """
119
    Convert CIE XYZ tristimulus values to CCT and Duv using Ohno (2013) method.
120
    
121
    Parameters:
122
    - XYZ: CIE XYZ tristimulus values
123
    - cmfs: colour matching functions
124
    - **kwargs: additional computation parameters
125
    
126
    Returns:
127
    ndarray with CCT in Kelvin and Duv as [CCT, Duv]
128
    """
129

130
def CCT_to_mired(CCT: ArrayLike) -> NDArray:
131
    """
132
    Convert correlated colour temperature to mireds (micro reciprocal degrees).
133
    
134
    Parameters:
135
    - CCT: correlated colour temperature in Kelvin
136
    
137
    Returns:
138
    Temperature in mireds
139
    """
140

141
def mired_to_CCT(mireds: ArrayLike) -> NDArray:
142
    """
143
    Convert mireds to correlated colour temperature.
144
    
145
    Parameters:
146
    - mireds: temperature in mireds
147
    
148
    Returns:
149
    Correlated colour temperature in Kelvin
150
    """
151
```
152

153
## Usage Examples
154

155
### Basic CCT Calculations
156

157
```python
158
import colour
159
import numpy as np
160

161
# Convert xy chromaticity to CCT
162
xy_d65 = np.array([0.31270, 0.32900])  # D65 white point
163
cct_d65 = colour.xy_to_CCT(xy_d65)
164
print(f"D65 CCT: {cct_d65:.0f}K")  # ~6500K
165

166
# Convert CCT back to xy
167
xy_recovered = colour.CCT_to_xy(cct_d65)
168
print(f"Recovered xy: {xy_recovered}")
169

170
# Try different methods
171
cct_hernandez = colour.xy_to_CCT(xy_d65, method="Hernandez 1999")
172
cct_mccamy = colour.xy_to_CCT(xy_d65, method="McCamy 1992")
173
print(f"Hernandez 1999: {cct_hernandez:.0f}K")
174
print(f"McCamy 1992: {cct_mccamy:.0f}K")
175
```
176

177
### Advanced CCT with Duv
178

179
```python
180
import colour
181
import numpy as np
182

183
# Convert uv coordinates to CCT with Duv
184
uv = np.array([0.1978, 0.3122])
185
cct_duv = colour.uv_to_CCT(uv, method="Ohno 2013")
186
print(f"CCT: {cct_duv[0]:.0f}K, Duv: {cct_duv[1]:.4f}")
187

188
# Convert CCT and Duv back to uv
189
uv_recovered = colour.CCT_to_uv(cct_duv, method="Ohno 2013")
190
print(f"Recovered uv: {uv_recovered}")
191

192
# Direct XYZ to CCT conversion
193
XYZ_d65 = np.array([95.047, 100.0, 108.883])
194
cct_duv_xyz = colour.XYZ_to_CCT_Ohno2013(XYZ_d65)
195
print(f"XYZ to CCT: {cct_duv_xyz[0]:.0f}K, Duv: {cct_duv_xyz[1]:.4f}")
196
```
197

198
### Mired Conversions
199

200
```python
201
import colour
202
import numpy as np
203

204
# Convert CCT to mireds for color correction calculations
205
cct_values = np.array([2850, 5600, 6500])  # Tungsten, daylight, D65
206
mireds = colour.CCT_to_mired(cct_values)
207
print(f"CCT: {cct_values}")
208
print(f"Mireds: {mireds}")
209

210
# Color temperature shift calculation
211
shift_mireds = mireds[1] - mireds[0]  # Tungsten to daylight shift
212
print(f"Color correction shift: {shift_mireds:.0f} mireds")
213

214
# Convert back to CCT
215
cct_recovered = colour.mired_to_CCT(mireds)
216
print(f"Recovered CCT: {cct_recovered}")
217
```
218

219
### Method Comparison
220

221
```python
222
import colour
223
import numpy as np
224

225
# Compare different methods for same chromaticity
226
xy_test = np.array([0.3, 0.32])
227

228
methods = ["CIE Illuminant D Series", "Hernandez 1999", "Kang 2002", "McCamy 1992"]
229
for method in methods:
230
    cct = colour.xy_to_CCT(xy_test, method=method)
231
    print(f"{method}: {cct:.0f}K")
232

233
# Compare uv methods
234
uv_test = np.array([0.2, 0.31])
235
uv_methods = ["Ohno 2013", "Krystek 1985", "Robertson 1968", "Planck 1900"]
236
for method in uv_methods:
237
    result = colour.uv_to_CCT(uv_test, method=method)
238
    if len(result) == 2:
239
        print(f"{method}: {result[0]:.0f}K, Duv: {result[1]:.4f}")
240
    else:
241
        print(f"{method}: {result:.0f}K")
242
```
243

244
## Types
245

246
```python { .api }
247
from colour.hints import ArrayLike, NDArray, Dict, Callable, Literal
248
from colour.colorimetry import XYZ_ColourMatchingFunctions
249

250
# Method collections type
251
MethodCollection = Dict[str, Callable]
252

253
# CCT calculation result types
254
CCTResult = NDArray  # Single CCT value
255
CCTDuvResult = NDArray  # [CCT, Duv] pair
256
```
257

258
## Imports
259

260
```python
261
# Master temperature functions
262
from colour.temperature import (
263
    xy_to_CCT, CCT_to_xy, uv_to_CCT, CCT_to_uv,
264
    XY_TO_CCT_METHODS, CCT_TO_XY_METHODS,
265
    UV_TO_CCT_METHODS, CCT_TO_UV_METHODS
266
)
267

268
# Specialized functions
269
from colour.temperature import (
270
    CCT_to_XYZ_Ohno2013, XYZ_to_CCT_Ohno2013,
271
    CCT_to_mired, mired_to_CCT
272
)
273

274
# Alternative imports from main package
275
from colour import (
276
    xy_to_CCT, CCT_to_xy, uv_to_CCT, CCT_to_uv,
277
    CCT_to_mired, mired_to_CCT
278
)
279
```