Coverage for colorimetry/yellowness.py: 41%

1"""

2 Yellowness Index :math:`Y`

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

4

5 Define the *yellowness* index :math:`Y` computation methods.

6

7- :func:`colour.colorimetry.yellowness_ASTMD1925`: Compute *yellowness*

8 index :math:`YI` using *ASTM D1925* method for plastics.

9- :func:`colour.colorimetry.yellowness_ASTME313_alternative`: Compute

10 *yellowness* index :math:`YI` using the alternative *ASTM E313* method.

11- :func:`colour.colorimetry.yellowness_ASTME313`: Compute *yellowness*

12 index :math:`YI` using the recommended *ASTM E313* method.

13- :attr:`colour.YELLOWNESS_METHODS`: Supported *yellowness* computation

14 methods.

15- :func:`colour.yellowness`: Compute *yellowness* :math:`YI` using

16 specified method.

17

18 References

19----------

20- :cite:`ASTMInternational2015` : ASTM International. (2015). ASTM E313-15e1

21 - Standard Practice for Calculating Yellowness and Whiteness Indices from

22 Instrumentally Measured Color Coordinates. doi:10.1520/E0313-20

23- :cite:`X-Rite2012a` : X-Rite, & Pantone. (2012). Color iQC and Color iMatch

24 Color Calculations Guide.

25 https://www.xrite.com/-/media/xrite/files/apps_engineering_techdocuments/\

26 c/09_color_calculations_en.pdf

27"""

28

29 from __future__ import annotations

30

31 import typing

32

33 import numpy as np

34

35 from colour.algebra import sdiv, sdiv_mode

36

37 if typing.TYPE_CHECKING:

38 from colour.hints import Any, Literal

39

40 from colour.hints import ( # noqa: TC001

41 ArrayLike,

42 Domain100,

43 Range100,

44)

45 from colour.utilities import (

46 CanonicalMapping,

47 as_float,

48 filter_kwargs,

49 from_range_100,

50 to_domain_100,

51 tsplit,

52 validate_method,

53)

54

55 __author__ = "Colour Developers"

56 __copyright__ = "Copyright 2013 Colour Developers"

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

58 __maintainer__ = "Colour Developers"

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

60 __status__ = "Production"

61

62 __all__ = [

63 "yellowness_ASTMD1925",

64 "yellowness_ASTME313_alternative",

65 "YELLOWNESS_COEFFICIENTS_ASTME313",

66 "yellowness_ASTME313",

67 "YELLOWNESS_METHODS",

68 "yellowness",

69]

70

71

72 def yellowness_ASTMD1925(

73 XYZ: Domain100,

74) -> Range100:

75 """

76 Compute the *yellowness* index :math:`YI` of the specified sample *CIE XYZ*

77 tristimulus values using the *ASTM D1925* method.

78

79 The *ASTM D1925* method has been specifically developed for defining the

80 yellowness of homogeneous, non-fluorescent, almost neutral-transparent,

81 white-scattering or opaque plastics as they will be evaluated under

82 daylight conditions. The method can be applied to other materials as

83 well, provided they fit this description.

84

85 Parameters

86 ----------

87 XYZ

88 *CIE XYZ* tristimulus values of the sample.

89

90 Returns

91 -------

92 :class:`numpy.ndarray`

93 *Yellowness* index :math:`YI`.

94

95 Notes

96 -----

97 +------------+-----------------------+---------------+

98 | **Domain** | **Scale - Reference** | **Scale - 1** |

99 +============+=======================+===============+

100 | ``XYZ`` | 100 | 1 |

101 +------------+-----------------------+---------------+

102

103 +------------+-----------------------+---------------+

104 | **Range** | **Scale - Reference** | **Scale - 1** |

105 +============+=======================+===============+

106 | ``YI`` | 100 | 1 |

107 +------------+-----------------------+---------------+

108

109 - Input *CIE XYZ* tristimulus values must be adapted to

110 *CIE Illuminant C*.

111

112 References

113 ----------

114 :cite:`ASTMInternational2015`, :cite:`X-Rite2012a`

115

116 Examples

117 --------

118 >>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])

119 >>> yellowness_ASTMD1925(XYZ) # doctest: +ELLIPSIS

120 10.2999999...

121 """

122

123 X, Y, Z = tsplit(to_domain_100(XYZ))

124

125 with sdiv_mode():

126 YI = sdiv(100 * (1.28 * X - 1.06 * Z), Y)

127

128 return as_float(from_range_100(YI))

129

130

131 def yellowness_ASTME313_alternative(

132 XYZ: Domain100,

133) -> Range100:

134 """

135 Compute the *yellowness* index :math:`YI` of the specified sample *CIE XYZ*

136 tristimulus values using the alternative *ASTM E313* method.

137

138 In the original form of *Test Method E313*, an alternative equation was

139 recommended for a *yellowness* index. In terms of colorimeter readings,

140 it was :math:`YI = 100(1 - B/G)` where :math:`B` and :math:`G` are,

141 respectively, blue and green colorimeter readings. Its derivation

142 assumed that, because of the limitation of the concept to yellow (or

143 blue) colors, it was not necessary to take account of variations in the

144 amber or red colorimeter reading :math:`A`. This equation is no longer

145 recommended.

146

147 Parameters

148 ----------

149 XYZ

150 *CIE XYZ* tristimulus values of the sample.

151

152 Returns

153 -------

154 :class:`numpy.ndarray`

155 *Yellowness* index :math:`YI`.

156

157 Notes

158 -----

159 +------------+-----------------------+---------------+

160 | **Domain** | **Scale - Reference** | **Scale - 1** |

161 +============+=======================+===============+

162 | ``XYZ`` | 100 | 1 |

163 +------------+-----------------------+---------------+

164

165 +------------+-----------------------+---------------+

166 | **Range** | **Scale - Reference** | **Scale - 1** |

167 +============+=======================+===============+

168 | ``YI`` | 100 | 1 |

169 +------------+-----------------------+---------------+

170

171 - Input *CIE XYZ* tristimulus values must be adapted to

172 *CIE Illuminant C*.

173

174 References

175 ----------

176 :cite:`ASTMInternational2015`, :cite:`X-Rite2012a`

177

178 Examples

179 --------

180 >>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])

181 >>> yellowness_ASTME313_alternative(XYZ) # doctest: +ELLIPSIS

182 11.0650000...

183 """

184

185 _X, Y, Z = tsplit(to_domain_100(XYZ))

186

187 with sdiv_mode():

188 YI = 100 * (1 - sdiv(0.847 * Z, Y))

189

190 return as_float(from_range_100(YI))

191

192

193 YELLOWNESS_COEFFICIENTS_ASTME313: CanonicalMapping = CanonicalMapping(

194 {

195 "CIE 1931 2 Degree Standard Observer": CanonicalMapping(

196 {

197 "C": np.array([1.2769, 1.0592]),

198 "D65": np.array([1.2985, 1.1335]),

199 }

200 ),

201 "CIE 1964 10 Degree Standard Observer": CanonicalMapping(

202 {

203 "C": np.array([1.2871, 1.0781]),

204 "D65": np.array([1.3013, 1.1498]),

205 }

206 ),

207 }

208)

209 YELLOWNESS_COEFFICIENTS_ASTME313.__doc__ = """

210 Coefficients :math:`C_X` and :math:`C_Z` for the *ASTM E313*

211*yellowness* index :math:`YI` computation method.

212

213 References

214----------

215:cite:`ASTMInternational2015`

216

217 Aliases:

218

219- 'cie_2_1931': 'CIE 1931 2 Degree Standard Observer'

220- 'cie_10_1964': 'CIE 1964 10 Degree Standard Observer'

221"""

222 YELLOWNESS_COEFFICIENTS_ASTME313["cie_2_1931"] = YELLOWNESS_COEFFICIENTS_ASTME313[

223 "CIE 1931 2 Degree Standard Observer"

224]

225 YELLOWNESS_COEFFICIENTS_ASTME313["cie_10_1964"] = YELLOWNESS_COEFFICIENTS_ASTME313[

226 "CIE 1964 10 Degree Standard Observer"

227]

228

229

230 def yellowness_ASTME313(

231 XYZ: Domain100,

232 C_XZ: ArrayLike = YELLOWNESS_COEFFICIENTS_ASTME313[

233 "CIE 1931 2 Degree Standard Observer"

234 ]["D65"],

235) -> Range100:

236 """

237 Compute the *yellowness* index :math:`YI` of the specified sample *CIE XYZ*

238 tristimulus values using the *ASTM E313* method.

239

240 *ASTM E313* has been successfully used for a variety of white or near white

241 materials. This includes coatings, plastics, and textiles.

242

243 Parameters

244 ----------

245 XYZ

246 *CIE XYZ* tristimulus values of the sample.

247 C_XZ

248 Coefficients :math:`C_X` and :math:`C_Z` for the

249 *CIE 1931 2 Degree Standard Observer* and

250 *CIE 1964 10 Degree Standard Observer* with *CIE Illuminant C* and

251 *CIE Standard Illuminant D65*.

252

253 Returns

254 -------

255 :class:`numpy.ndarray`

256 *Yellowness* index :math:`YI`.

257

258 Notes

259 -----

260 +------------+-----------------------+---------------+

261 | **Domain** | **Scale - Reference** | **Scale - 1** |

262 +============+=======================+===============+

263 | ``XYZ`` | 100 | 1 |

264 +------------+-----------------------+---------------+

265

266 +------------+-----------------------+---------------+

267 | **Range** | **Scale - Reference** | **Scale - 1** |

268 +============+=======================+===============+

269 | ``YI`` | 100 | 1 |

270 +------------+-----------------------+---------------+

271

272 References

273 ----------

274 :cite:`ASTMInternational2015`

275

276 Examples

277 --------

278 >>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])

279 >>> yellowness_ASTME313(XYZ) # doctest: +ELLIPSIS

280 4.3400000...

281 """

282

283 X, Y, Z = tsplit(to_domain_100(XYZ))

284 C_X, C_Z = tsplit(C_XZ)

285

286 with sdiv_mode():

287 YI = 100 * sdiv(C_X * X - C_Z * Z, Y)

288

289 return as_float(from_range_100(YI))

290

291

292 YELLOWNESS_METHODS = CanonicalMapping(

293 {

294 "ASTM D1925": yellowness_ASTMD1925,

295 "ASTM E313 Alternative": yellowness_ASTME313_alternative,

296 "ASTM E313": yellowness_ASTME313,

297 }

298)

299 YELLOWNESS_METHODS.__doc__ = """

300 Supported *yellowness* computation methods.

301

302 References

303----------

304:cite:`ASTMInternational2015`, :cite:`X-Rite2012a`

305"""

306

307

308 def yellowness(

309 XYZ: Domain100,

310 method: (

311 Literal["ASTM D1925", "ASTM E313", "ASTM E313 Alternative"] | str

312 ) = "ASTM E313",

313 **kwargs: Any,

314) -> Range100:

315 """

316 Compute the *yellowness* index :math:`YI` using the specified method.

317

318 Parameters

319 ----------

320 XYZ

321 *CIE XYZ* tristimulus values of the sample.

322 method

323 Computation method.

324

325 Other Parameters

326 ----------------

327 C_XZ

328 {:func:`colour.colorimetry.yellowness_ASTME313`},

329 Coefficients :math:`C_X` and :math:`C_Z` for the

330 *CIE 1931 2 Degree Standard Observer* and

331 *CIE 1964 10 Degree Standard Observer* with *CIE Illuminant C* and

332 *CIE Standard Illuminant D65*.

333

334 Returns

335 -------

336 :class:`numpy.ndarray`

337 *Yellowness* index :math:`YI`.

338

339 Notes

340 -----

341 +------------+-----------------------+---------------+

342 | **Domain** | **Scale - Reference** | **Scale - 1** |

343 +============+=======================+===============+

344 | ``XYZ`` | 100 | 1 |

345 +------------+-----------------------+---------------+

346

347 +------------+-----------------------+---------------+

348 | **Range** | **Scale - Reference** | **Scale - 1** |

349 +============+=======================+===============+

350 | ``YI`` | 100 | 1 |

351 +------------+-----------------------+---------------+

352

353 References

354 ----------

355 :cite:`ASTMInternational2015`, :cite:`X-Rite2012a`

356

357 Examples

358 --------

359 >>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])

360 >>> yellowness(XYZ) # doctest: +ELLIPSIS

361 4.3400000...

362 >>> yellowness(XYZ, method="ASTM E313 Alternative") # doctest: +ELLIPSIS

363 11.0650000...

364 >>> yellowness(XYZ, method="ASTM D1925") # doctest: +ELLIPSIS

365 10.2999999...

366 """

367

368 method = validate_method(method, tuple(YELLOWNESS_METHODS))

369

370 function = YELLOWNESS_METHODS[method]

371

372 return function(XYZ, **filter_kwargs(function, **kwargs))