Coverage for colour/difference/cam02_ucs.py: 100%

1""" 

2:math:`\\Delta E'` - Delta E Colour Difference - Luo, Cui and Li (2006) 

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

4 

5Define the :math:`\\Delta E'` colour difference computation objects based on 

6*Luo et al. (2006)* *CAM02-LCD*, *CAM02-SCD*, and *CAM02-UCS* colourspaces: 

7 

8- :func:`colour.difference.delta_E_CAM02LCD` 

9- :func:`colour.difference.delta_E_CAM02SCD` 

10- :func:`colour.difference.delta_E_CAM02UCS` 

11 

12References 

13---------- 

14- :cite:`Luo2006b` : Luo, M. Ronnier, Cui, G., & Li, C. (2006). Uniform 

15 colour spaces based on CIECAM02 colour appearance model. Color Research & 

16 Application, 31(4), 320-330. doi:10.1002/col.20227 

17""" 

18 

19from __future__ import annotations 

20 

21import typing 

22 

23import numpy as np 

24 

25if typing.TYPE_CHECKING: 

26 from colour.hints import NDArrayFloat 

27 

28from colour.hints import Domain100 # noqa: TC001 

29from colour.models.cam02_ucs import COEFFICIENTS_UCS_LUO2006, Coefficients_UCS_Luo2006 

30from colour.utilities import as_float, tsplit 

31 

32__author__ = "Colour Developers" 

33__copyright__ = "Copyright 2013 Colour Developers" 

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

35__maintainer__ = "Colour Developers" 

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

37__status__ = "Production" 

38 

39__all__ = [ 

40 "delta_E_Luo2006", 

41 "delta_E_CAM02LCD", 

42 "delta_E_CAM02SCD", 

43 "delta_E_CAM02UCS", 

44] 

45 

46 

47def delta_E_Luo2006( 

48 Jpapbp_1: Domain100, 

49 Jpapbp_2: Domain100, 

50 coefficients: Coefficients_UCS_Luo2006, 

51) -> NDArrayFloat: 

52 """ 

53 Compute the colour difference :math:`\\Delta E'` between two specified 

54 *Luo et al. (2006)* *CAM02-LCD*, *CAM02-SCD*, or *CAM02-UCS* 

55 colourspaces :math:`J'a'b'` arrays. 

56 

57 Parameters 

58 ---------- 

59 Jpapbp_1 

60 Standard / reference *Luo et al. (2006)* *CAM02-LCD*, *CAM02-SCD*, 

61 or *CAM02-UCS* colourspaces :math:`J'a'b'` array. 

62 Jpapbp_2 

63 Sample / test *Luo et al. (2006)* *CAM02-LCD*, *CAM02-SCD*, or 

64 *CAM02-UCS* colourspaces :math:`J'a'b'` array. 

65 coefficients 

66 Coefficients of one of the *Luo et al. (2006)* *CAM02-LCD*, 

67 *CAM02-SCD*, or *CAM02-UCS* colourspaces. 

68 

69 Returns 

70 ------- 

71 :class:`numpy.ndarray` 

72 Colour difference :math:`\\Delta E'`. 

73 

74 Warnings 

75 -------- 

76 The :math:`J'a'b'` array should have been computed with a 

77 *Luo et al. (2006)* *CAM02-LCD*, *CAM02-SCD*, or *CAM02-UCS* 

78 colourspace and not with the *CIE L\\*a\\*b\\** colourspace. 

79 

80 Notes 

81 ----- 

82 +--------------+------------------------+--------------------+ 

83 | **Domain** | **Scale - Reference** | **Scale - 1** | 

84 +==============+========================+====================+ 

85 | ``Jpapbp_1`` | 100 | 1 | 

86 +--------------+------------------------+--------------------+ 

87 | ``Jpapbp_2`` | 100 | 1 | 

88 +--------------+------------------------+--------------------+ 

89 

90 Examples 

91 -------- 

92 >>> Jpapbp_1 = np.array([54.90433134, -0.08450395, -0.06854831]) 

93 >>> Jpapbp_2 = np.array([54.80352754, -3.96940084, -13.57591013]) 

94 >>> delta_E_Luo2006(Jpapbp_1, Jpapbp_2, COEFFICIENTS_UCS_LUO2006["CAM02-LCD"]) 

95 ... # doctest: +ELLIPSIS 

96 14.0555464... 

97 """ 

98 

99 J_p_1, a_p_1, b_p_1 = tsplit(Jpapbp_1) 

100 J_p_2, a_p_2, b_p_2 = tsplit(Jpapbp_2) 

101 K_L, _c_1, _c_2 = coefficients.values 

102 

103 d_E = np.sqrt( 

104 ((J_p_1 - J_p_2) / K_L) ** 2 + (a_p_1 - a_p_2) ** 2 + (b_p_1 - b_p_2) ** 2 

105 ) 

106 

107 return as_float(d_E) 

108 

109 

110def delta_E_CAM02LCD(Jpapbp_1: Domain100, Jpapbp_2: Domain100) -> NDArrayFloat: 

111 """ 

112 Compute the colour difference :math:`\\Delta E'` between two specified 

113 *CAM02-LCD* colourspace :math:`J'a'b'` arrays using the 

114 *Luo et al. (2006)* formula. 

115 

116 Parameters 

117 ---------- 

118 Jpapbp_1 

119 Standard / reference *CAM02-LCD* colourspace :math:`J'a'b'` array as 

120 computed by the *Luo et al. (2006)* uniform colour space model. 

121 Jpapbp_2 

122 Sample / test *CAM02-LCD* colourspace :math:`J'a'b'` array as computed 

123 by the *Luo et al. (2006)* uniform colour space model. 

124 

125 Returns 

126 ------- 

127 :class:`numpy.ndarray` 

128 Colour difference :math:`\\Delta E'`. 

129 

130 Warnings 

131 -------- 

132 The :math:`J'a'b'` arrays should have been computed with the 

133 *Luo et al. (2006)* *CAM02-LCD* colourspace and not with the 

134 *CIE L\\*a\\*b\\** colourspace. 

135 

136 Notes 

137 ----- 

138 +--------------+------------------------+--------------------+ 

139 | **Domain** | **Scale - Reference** | **Scale - 1** | 

140 +==============+========================+====================+ 

141 | ``Jpapbp_1`` | 100 | 1 | 

142 +--------------+------------------------+--------------------+ 

143 | ``Jpapbp_2`` | 100 | 1 | 

144 +--------------+------------------------+--------------------+ 

145 

146 References 

147 ---------- 

148 :cite:`Luo2006b` 

149 

150 Examples 

151 -------- 

152 >>> Jpapbp_1 = np.array([54.90433134, -0.08450395, -0.06854831]) 

153 >>> Jpapbp_2 = np.array([54.80352754, -3.96940084, -13.57591013]) 

154 >>> delta_E_CAM02LCD(Jpapbp_1, Jpapbp_2) # doctest: +ELLIPSIS 

155 14.0555464... 

156 """ 

157 

158 return delta_E_Luo2006(Jpapbp_1, Jpapbp_2, COEFFICIENTS_UCS_LUO2006["CAM02-LCD"]) 

159 

160 

161def delta_E_CAM02SCD(Jpapbp_1: Domain100, Jpapbp_2: Domain100) -> NDArrayFloat: 

162 """ 

163 Compute the colour difference :math:`\\Delta E'` between two specified 

164 *CAM02-SCD* colourspace :math:`J'a'b'` arrays using the 

165 *Luo et al. (2006)* formula. 

166 

167 Parameters 

168 ---------- 

169 Jpapbp_1 

170 Standard / reference *CAM02-SCD* colourspace :math:`J'a'b'` array as 

171 computed by the *Luo et al. (2006)* uniform colour space model. 

172 Jpapbp_2 

173 Sample / test *CAM02-SCD* colourspace :math:`J'a'b'` array as computed 

174 by the *Luo et al. (2006)* uniform colour space model. 

175 

176 Returns 

177 ------- 

178 :class:`numpy.ndarray` 

179 Colour difference :math:`\\Delta E'`. 

180 

181 Warnings 

182 -------- 

183 The :math:`J'a'b'` arrays should have been computed with the 

184 *Luo et al. (2006)* *CAM02-SCD* colourspace and not with the 

185 *CIE L\\*a\\*b\\** colourspace. 

186 

187 Notes 

188 ----- 

189 +--------------+------------------------+--------------------+ 

190 | **Domain** | **Scale - Reference** | **Scale - 1** | 

191 +==============+========================+====================+ 

192 | ``Jpapbp_1`` | 100 | 1 | 

193 +--------------+------------------------+--------------------+ 

194 | ``Jpapbp_2`` | 100 | 1 | 

195 +--------------+------------------------+--------------------+ 

196 

197 References 

198 ---------- 

199 :cite:`Luo2006b` 

200 

201 Examples 

202 -------- 

203 >>> Jpapbp_1 = np.array([54.90433134, -0.08450395, -0.06854831]) 

204 >>> Jpapbp_2 = np.array([54.80352754, -3.96940084, -13.57591013]) 

205 >>> delta_E_CAM02SCD(Jpapbp_1, Jpapbp_2) # doctest: +ELLIPSIS 

206 14.0551718... 

207 """ 

208 

209 return delta_E_Luo2006(Jpapbp_1, Jpapbp_2, COEFFICIENTS_UCS_LUO2006["CAM02-SCD"]) 

210 

211 

212def delta_E_CAM02UCS(Jpapbp_1: Domain100, Jpapbp_2: Domain100) -> NDArrayFloat: 

213 """ 

214 Compute the colour difference :math:`\\Delta E'` between two specified 

215 *CAM02-UCS* colourspace :math:`J'a'b'` arrays using the 

216 *Luo et al. (2006)* formula. 

217 

218 Parameters 

219 ---------- 

220 Jpapbp_1 

221 Standard / reference *CAM02-UCS* colourspace :math:`J'a'b'` array as 

222 computed by the *Luo et al. (2006)* uniform colour space model. 

223 Jpapbp_2 

224 Sample / test *CAM02-UCS* colourspace :math:`J'a'b'` array as computed 

225 by the *Luo et al. (2006)* uniform colour space model. 

226 

227 Returns 

228 ------- 

229 :class:`numpy.ndarray` 

230 Colour difference :math:`\\Delta E'`. 

231 

232 Warnings 

233 -------- 

234 The :math:`J'a'b'` arrays should have been computed with the 

235 *Luo et al. (2006)* *CAM02-UCS* colourspace and not with the 

236 *CIE L\\*a\\*b\\** colourspace. 

237 

238 Notes 

239 ----- 

240 +--------------+------------------------+--------------------+ 

241 | **Domain** | **Scale - Reference** | **Scale - 1** | 

242 +==============+========================+====================+ 

243 | ``Jpapbp_1`` | 100 | 1 | 

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

245 | ``Jpapbp_2`` | 100 | 1 | 

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

247 

248 References 

249 ---------- 

250 :cite:`Luo2006b` 

251 

252 Examples 

253 -------- 

254 >>> Jpapbp_1 = np.array([54.90433134, -0.08450395, -0.06854831]) 

255 >>> Jpapbp_2 = np.array([54.80352754, -3.96940084, -13.57591013]) 

256 >>> delta_E_CAM02UCS(Jpapbp_1, Jpapbp_2) # doctest: +ELLIPSIS 

257 14.0552982... 

258 """ 

259 

260 return delta_E_Luo2006(Jpapbp_1, Jpapbp_2, COEFFICIENTS_UCS_LUO2006["CAM02-UCS"])