Coverage for colour/models/cie_xyy.py: 100%

1""" 

2Tristimulus Values, CIE xyY Colourspace and Chromaticity Coordinates 

3==================================================================== 

4 

5Define the *CIE xyY* colourspace transformations. 

6 

7- :func:`colour.XYZ_to_xyY` 

8- :func:`colour.xyY_to_XYZ` 

9- :func:`colour.xyY_to_xy` 

10- :func:`colour.xy_to_xyY` 

11- :func:`colour.XYZ_to_xy` 

12- :func:`colour.xy_to_XYZ` 

13 

14References 

15---------- 

16- :cite:`CIETC1-482004h` : CIE TC 1-48. (2004). CIE 015:2004 Colorimetry, 

17 3rd Edition. In CIE 015:2004 Colorimetry, 3rd Edition. Commission 

18 Internationale de l'Eclairage. ISBN:978-3-901906-33-6 

19- :cite:`Wikipedia2005` : Wikipedia. (2005). CIE 1931 color space. Retrieved 

20 February 24, 2014, from http://en.wikipedia.org/wiki/CIE_1931_color_space 

21""" 

22 

23from __future__ import annotations 

24 

25import numpy as np 

26 

27from colour.algebra import sdiv, sdiv_mode 

28from colour.hints import ( # noqa: TC001 

29 ArrayLike, 

30 Domain1, 

31 NDArrayFloat, 

32 Range1, 

33) 

34from colour.utilities import as_float_array, from_range_1, to_domain_1, tsplit, tstack 

35 

36__author__ = "Colour Developers" 

37__copyright__ = "Copyright 2013 Colour Developers" 

38__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause" 

39__maintainer__ = "Colour Developers" 

40__email__ = "colour-developers@colour-science.org" 

41__status__ = "Production" 

42 

43__all__ = [ 

44 "XYZ_to_xyY", 

45 "xyY_to_XYZ", 

46 "xy_to_xyY", 

47 "xyY_to_xy", 

48 "XYZ_to_xy", 

49 "xy_to_XYZ", 

50] 

51 

52 

53def XYZ_to_xyY(XYZ: Domain1) -> Range1: 

54 """ 

55 Convert from *CIE XYZ* tristimulus values to *CIE xyY* colourspace. 

56 

57 Parameters 

58 ---------- 

59 XYZ 

60 *CIE XYZ* tristimulus values. 

61 

62 Returns 

63 ------- 

64 :class:`numpy.ndarray` 

65 *CIE xyY* colourspace array with chromaticity coordinates 

66 :math:`x, y` and luminance :math:`Y`. 

67 

68 Notes 

69 ----- 

70 +------------+-----------------------+---------------+ 

71 | **Domain** | **Scale - Reference** | **Scale - 1** | 

72 +============+=======================+===============+ 

73 | ``XYZ`` | 1 | 1 | 

74 +------------+-----------------------+---------------+ 

75 

76 +------------+-----------------------+---------------+ 

77 | **Range** | **Scale - Reference** | **Scale - 1** | 

78 +============+=======================+===============+ 

79 | ``xyY`` | 1 | 1 | 

80 +------------+-----------------------+---------------+ 

81 

82 References 

83 ---------- 

84 :cite:`CIETC1-482004h`, :cite:`Wikipedia2005` 

85 

86 Examples 

87 -------- 

88 >>> XYZ = np.array([0.20654008, 0.12197225, 0.05136952]) 

89 >>> XYZ_to_xyY(XYZ) # doctest: +ELLIPSIS 

90 array([ 0.5436955..., 0.3210794..., 0.1219722...]) 

91 """ 

92 

93 XYZ = to_domain_1(XYZ) 

94 

95 X, Y, Z = tsplit(XYZ) 

96 

97 X_Y_Z = X + Y + Z 

98 

99 with sdiv_mode(): 

100 x = sdiv(X, X_Y_Z) 

101 y = sdiv(Y, X_Y_Z) 

102 

103 return tstack([x, y, from_range_1(Y)]) 

104 

105 

106def xyY_to_XYZ(xyY: Domain1) -> Range1: 

107 """ 

108 Convert from *CIE xyY* colourspace to *CIE XYZ* tristimulus values. 

109 

110 Parameters 

111 ---------- 

112 xyY 

113 *CIE xyY* colourspace array with chromaticity coordinates 

114 :math:`x, y` and luminance :math:`Y`. 

115 

116 Returns 

117 ------- 

118 :class:`numpy.ndarray` 

119 *CIE XYZ* tristimulus values. 

120 

121 Notes 

122 ----- 

123 +------------+-----------------------+---------------+ 

124 | **Domain** | **Scale - Reference** | **Scale - 1** | 

125 +============+=======================+===============+ 

126 | ``xyY`` | 1 | 1 | 

127 +------------+-----------------------+---------------+ 

128 

129 +------------+-----------------------+---------------+ 

130 | **Range** | **Scale - Reference** | **Scale - 1** | 

131 +============+=======================+===============+ 

132 | ``XYZ`` | 1 | 1 | 

133 +------------+-----------------------+---------------+ 

134 

135 References 

136 ---------- 

137 :cite:`CIETC1-482004h`, :cite:`Wikipedia2005` 

138 

139 Examples 

140 -------- 

141 >>> xyY = np.array([0.54369557, 0.32107944, 0.12197225]) 

142 >>> xyY_to_XYZ(xyY) # doctest: +ELLIPSIS 

143 array([ 0.2065400..., 0.1219722..., 0.0513695...]) 

144 """ 

145 

146 xyY = as_float_array(xyY) 

147 

148 x, y, Y = tsplit(xyY) 

149 Y = to_domain_1(Y) 

150 

151 with sdiv_mode(): 

152 Y_y = sdiv(Y, y) 

153 

154 XYZ = tstack([x * Y_y, Y, (1 - (x + y)) * Y_y]) 

155 

156 return from_range_1(XYZ) 

157 

158 

159def xyY_to_xy(xyY: Domain1) -> NDArrayFloat: 

160 """ 

161 Convert from *CIE xyY* colourspace to *CIE xy* chromaticity 

162 coordinates. 

163 

164 ``xyY`` argument with last dimension being equal to 2 will be 

165 assumed to be a *CIE xy* chromaticity coordinates argument and will 

166 be returned directly by the definition. 

167 

168 Parameters 

169 ---------- 

170 xyY 

171 *CIE xyY* colourspace array or *CIE xy* chromaticity 

172 coordinates. 

173 

174 Returns 

175 ------- 

176 :class:`numpy.ndarray` 

177 *CIE xy* chromaticity coordinates. 

178 

179 Notes 

180 ----- 

181 +------------+-----------------------+---------------+ 

182 | **Domain** | **Scale - Reference** | **Scale - 1** | 

183 +============+=======================+===============+ 

184 | ``xyY`` | 1 | 1 | 

185 +------------+-----------------------+---------------+ 

186 

187 References 

188 ---------- 

189 :cite:`CIETC1-482004h`, :cite:`Wikipedia2005` 

190 

191 Examples 

192 -------- 

193 >>> xyY = np.array([0.54369557, 0.32107944, 0.12197225]) 

194 >>> xyY_to_xy(xyY) # doctest: +ELLIPSIS 

195 array([ 0.54369557..., 0.32107944...]) 

196 >>> xy = np.array([0.54369557, 0.32107944]) 

197 >>> xyY_to_xy(xy) # doctest: +ELLIPSIS 

198 array([ 0.54369557..., 0.32107944...]) 

199 """ 

200 

201 xyY = as_float_array(xyY) 

202 

203 # Assuming ``xyY`` is actually a *CIE xy* chromaticity coordinates argument 

204 # and returning it directly. 

205 if xyY.shape[-1] == 2: 

206 return xyY 

207 

208 return xyY[..., 0:2] 

209 

210 

211def xy_to_xyY(xy: ArrayLike, Y: Domain1 = 1) -> Range1: 

212 """ 

213 Convert from *CIE xy* chromaticity coordinates to *CIE xyY* 

214 colourspace by extending the array's last dimension with the 

215 specified :math:`Y` *luminance*. 

216 

217 ``xy`` argument with last dimension equal to 3 will be assumed 

218 to be a *CIE xyY* colourspace array and will be returned 

219 directly by the definition. 

220 

221 Parameters 

222 ---------- 

223 xy 

224 *CIE xy* chromaticity coordinates or *CIE xyY* colourspace 

225 array. 

226 Y 

227 Optional :math:`Y` *luminance* value used to construct the 

228 *CIE xyY* colourspace array. The default :math:`Y` 

229 *luminance* value is 1. 

230 

231 Returns 

232 ------- 

233 :class:`numpy.ndarray` 

234 *CIE xyY* colourspace array. 

235 

236 Notes 

237 ----- 

238 +------------+-----------------------+---------------+ 

239 | **Domain** | **Scale - Reference** | **Scale - 1** | 

240 +============+=======================+===============+ 

241 | ``xy`` | 1 | 1 | 

242 +------------+-----------------------+---------------+ 

243 | ``Y`` | 1 | 1 | 

244 +------------+-----------------------+---------------+ 

245 

246 +------------+-----------------------+---------------+ 

247 | **Range** | **Scale - Reference** | **Scale - 1** | 

248 +============+=======================+===============+ 

249 | ``xyY`` | 1 | 1 | 

250 +------------+-----------------------+---------------+ 

251 

252 - This definition is a convenient object provided to 

253 implement support of illuminant argument luminance value 

254 in various :mod:`colour.models` package objects such as 

255 :func:`colour.Lab_to_XYZ` or :func:`colour.Luv_to_XYZ`. 

256 

257 References 

258 ---------- 

259 :cite:`CIETC1-482004h`, :cite:`Wikipedia2005` 

260 

261 Examples 

262 -------- 

263 >>> xy = np.array([0.54369557, 0.32107944]) 

264 >>> xy_to_xyY(xy) # doctest: +ELLIPSIS 

265 array([ 0.5436955..., 0.3210794..., 1. ]) 

266 >>> xy = np.array([0.54369557, 0.32107944, 1.00000000]) 

267 >>> xy_to_xyY(xy) # doctest: +ELLIPSIS 

268 array([ 0.5436955..., 0.3210794..., 1. ]) 

269 >>> xy = np.array([0.54369557, 0.32107944]) 

270 >>> xy_to_xyY(xy, 100) # doctest: +ELLIPSIS 

271 array([ 0.5436955..., 0.3210794..., 100. ]) 

272 """ 

273 

274 xy = as_float_array(xy) 

275 Y = as_float_array(to_domain_1(Y)) 

276 

277 # Assuming ``xy`` is actually a *CIE xyY* colourspace array argument and 

278 # returning it directly. 

279 if xy.shape[-1] == 3: 

280 return xy 

281 

282 x, y = tsplit(xy) 

283 

284 xyY = tstack([x, y, np.resize(Y, x.shape)]) 

285 

286 return from_range_1(xyY, np.array([1, 1, 100])) 

287 

288 

289def XYZ_to_xy(XYZ: Domain1) -> NDArrayFloat: 

290 """ 

291 Convert from *CIE XYZ* tristimulus values to *CIE xy* chromaticity 

292 coordinates. 

293 

294 Parameters 

295 ---------- 

296 XYZ 

297 *CIE XYZ* tristimulus values. 

298 

299 Returns 

300 ------- 

301 :class:`numpy.ndarray` 

302 *CIE xy* chromaticity coordinates. 

303 

304 Notes 

305 ----- 

306 +------------+-----------------------+---------------+ 

307 | **Domain** | **Scale - Reference** | **Scale - 1** | 

308 +============+=======================+===============+ 

309 | ``XYZ`` | 1 | 1 | 

310 +------------+-----------------------+---------------+ 

311 

312 References 

313 ---------- 

314 :cite:`CIETC1-482004h`, :cite:`Wikipedia2005` 

315 

316 Examples 

317 -------- 

318 >>> XYZ = np.array([0.20654008, 0.12197225, 0.05136952]) 

319 >>> XYZ_to_xy(XYZ) # doctest: +ELLIPSIS 

320 array([ 0.5436955..., 0.3210794...]) 

321 """ 

322 

323 return xyY_to_xy(XYZ_to_xyY(XYZ)) 

324 

325 

326def xy_to_XYZ(xy: ArrayLike) -> Range1: 

327 """ 

328 Convert from *CIE xy* chromaticity coordinates to *CIE XYZ* tristimulus values. 

329 

330 Parameters 

331 ---------- 

332 xy 

333 *CIE xy* chromaticity coordinates. 

334 

335 Returns 

336 ------- 

337 :class:`numpy.ndarray` 

338 *CIE XYZ* tristimulus values. 

339 

340 Notes 

341 ----- 

342 +------------+-----------------------+---------------+ 

343 | **Domain** | **Scale - Reference** | **Scale - 1** | 

344 +============+=======================+===============+ 

345 | ``xy`` | 1 | 1 | 

346 +------------+-----------------------+---------------+ 

347 

348 +------------+-----------------------+---------------+ 

349 | **Range** | **Scale - Reference** | **Scale - 1** | 

350 +============+=======================+===============+ 

351 | ``XYZ`` | 1 | 1 | 

352 +------------+-----------------------+---------------+ 

353 

354 References 

355 ---------- 

356 :cite:`CIETC1-482004h`, :cite:`Wikipedia2005` 

357 

358 Examples 

359 -------- 

360 >>> xy = np.array([0.54369557, 0.32107944]) 

361 >>> xy_to_XYZ(xy) # doctest: +ELLIPSIS 

362 array([ 1.6933366..., 1. , 0.4211574...]) 

363 """ 

364 

365 return xyY_to_XYZ(xy_to_xyY(xy))