Coverage for difference/__init__.py: 12%
25 statements
« prev ^ index » next coverage.py v7.11.0, created at 2025-11-16 22:49 +1300
1"""
2References
3----------
4- :cite:`Abasi2020a` : Abasi, S., Amani Tehran, M., & Fairchild, M. D. (2020).
5 Distance metrics for very large color differences. Color Research &
6 Application, 45(2), 208-223. doi:10.1002/col.22451
7- :cite:`ASTMInternational2007` : ASTM International. (2007). ASTM D2244-07 -
8 Standard Practice for Calculation of Color Tolerances and Color Differences
9 from Instrumentally Measured Color Coordinates: Vol. i (pp. 1-10).
10 doi:10.1520/D2244-16
11- :cite:`InternationalTelecommunicationUnion2019` : International
12 Telecommunication Union. (2019). Recommendation ITU-R BT.2124-0 -
13 Objective metric for the assessment of the potential visibility of colour
14 differences in television (pp. 1-36). http://www.itu.int/dms_pubrec/itu-r/\
15rec/bt/R-REC-BT.470-6-199811-S!!PDF-E.pdf
16- :cite:`Li2017` : Li, C., Li, Z., Wang, Z., Xu, Y., Luo, M. R., Cui, G.,
17 Melgosa, M., Brill, M. H., & Pointer, M. (2017). Comprehensive color
18 solutions: CAM16, CAT16, and CAM16-UCS. Color Research & Application,
19 42(6), 703-718. doi:10.1002/col.22131
20- :cite:`Lindbloom2003c` : Lindbloom, B. (2003). Delta E (CIE 1976).
21 Retrieved February 24, 2014, from
22 http://brucelindbloom.com/Eqn_DeltaE_CIE76.html
23- :cite:`Lindbloom2009f` : Lindbloom, B. (2009). Delta E (CMC). Retrieved
24 February 24, 2014, from http://brucelindbloom.com/Eqn_DeltaE_CMC.html
25- :cite:`Lindbloom2011a` : Lindbloom, B. (2011). Delta E (CIE 1994).
26 Retrieved February 24, 2014, from
27 http://brucelindbloom.com/Eqn_DeltaE_CIE94.html
28- :cite:`Luo2006b` : Luo, M. Ronnier, Cui, G., & Li, C. (2006). Uniform
29 colour spaces based on CIECAM02 colour appearance model. Color Research &
30 Application, 31(4), 320-330. doi:10.1002/col.20227
31- :cite:`Melgosa2013b` : Melgosa, M. (2013). CIE / ISO new standard:
32 CIEDE2000. http://www.color.org/events/colorimetry/\
33Melgosa_CIEDE2000_Workshop-July4.pdf
34- :cite:`Wikipedia2008b` : Wikipedia. (2008). Color difference. Retrieved
35 August 29, 2014, from http://en.wikipedia.org/wiki/Color_difference
36"""
38from __future__ import annotations
40import typing
42if typing.TYPE_CHECKING:
43 from colour.hints import Any, ArrayLike, NDArrayFloat, LiteralDeltaEMethod
45from colour.utilities import (
46 CanonicalMapping,
47 filter_kwargs,
48 validate_method,
49)
51from .cam02_ucs import delta_E_CAM02LCD, delta_E_CAM02SCD, delta_E_CAM02UCS
52from .cam16_ucs import delta_E_CAM16LCD, delta_E_CAM16SCD, delta_E_CAM16UCS
53from .delta_e import (
54 JND_CIE1976,
55 delta_E_CIE1976,
56 delta_E_CIE1994,
57 delta_E_CIE2000,
58 delta_E_CMC,
59 delta_E_HyAB,
60 delta_E_HyCH,
61 delta_E_ITP,
62)
63from .din99 import delta_E_DIN99
64from .huang2015 import power_function_Huang2015
65from .stress import INDEX_STRESS_METHODS, index_stress, index_stress_Garcia2007
67__all__ = [
68 "delta_E_CAM02LCD",
69 "delta_E_CAM02SCD",
70 "delta_E_CAM02UCS",
71]
72__all__ += [
73 "delta_E_CAM16LCD",
74 "delta_E_CAM16SCD",
75 "delta_E_CAM16UCS",
76]
77__all__ += [
78 "JND_CIE1976",
79 "delta_E_CIE1976",
80 "delta_E_CIE1994",
81 "delta_E_CIE2000",
82 "delta_E_CMC",
83 "delta_E_HyAB",
84 "delta_E_HyCH",
85 "delta_E_ITP",
86]
87__all__ += [
88 "delta_E_DIN99",
89]
90__all__ += [
91 "power_function_Huang2015",
92]
93__all__ += [
94 "INDEX_STRESS_METHODS",
95 "index_stress",
96 "index_stress_Garcia2007",
97]
99DELTA_E_METHODS: CanonicalMapping = CanonicalMapping(
100 {
101 "CIE 1976": delta_E_CIE1976,
102 "CIE 1994": delta_E_CIE1994,
103 "CIE 2000": delta_E_CIE2000,
104 "CMC": delta_E_CMC,
105 "ITP": delta_E_ITP,
106 "CAM02-LCD": delta_E_CAM02LCD,
107 "CAM02-SCD": delta_E_CAM02SCD,
108 "CAM02-UCS": delta_E_CAM02UCS,
109 "CAM16-LCD": delta_E_CAM16LCD,
110 "CAM16-SCD": delta_E_CAM16SCD,
111 "CAM16-UCS": delta_E_CAM16UCS,
112 "DIN99": delta_E_DIN99,
113 "HyAB": delta_E_HyAB,
114 "HyCH": delta_E_HyCH,
115 }
116)
117DELTA_E_METHODS.__doc__ = """
118Supported :math:`\\Delta E_{ab}` colour difference computation methods.
120References
121----------
122:cite:`ASTMInternational2007`, :cite:`Abasi2020a`, :cite:`Li2017`,
123:cite:`Lindbloom2003c`, :cite:`Lindbloom2011a`, :cite:`Lindbloom2009f`,
124:cite:`Luo2006b`, :cite:`Melgosa2013b`, :cite:`Wikipedia2008b`
126Aliases:
128- 'cie1976': 'CIE 1976'
129- 'cie1994': 'CIE 1994'
130- 'cie2000': 'CIE 2000'
131"""
132DELTA_E_METHODS["cie1976"] = DELTA_E_METHODS["CIE 1976"]
133DELTA_E_METHODS["cie1994"] = DELTA_E_METHODS["CIE 1994"]
134DELTA_E_METHODS["cie2000"] = DELTA_E_METHODS["CIE 2000"]
137def delta_E(
138 a: ArrayLike,
139 b: ArrayLike,
140 method: LiteralDeltaEMethod | str = "CIE 2000",
141 **kwargs: Any,
142) -> NDArrayFloat:
143 """
144 Compute the colour difference :math:`\\Delta E_{ab}` between two
145 specified *CIE L\\*a\\*b\\**, :math:`IC_TC_P`, or :math:`J'a'b'`
146 colourspace arrays.
148 Parameters
149 ----------
150 a
151 *CIE L\\*a\\*b\\**, :math:`IC_TC_P`, or :math:`J'a'b'` colourspace
152 array :math:`a`.
153 b
154 *CIE L\\*a\\*b\\**, :math:`IC_TC_P`, or :math:`J'a'b'` colourspace
155 array :math:`b`.
156 method
157 Computation method.
159 Other Parameters
160 ----------------
161 c
162 {:func:`colour.difference.delta_E_CMC`},
163 *Chroma* weighting factor.
164 l
165 {:func:`colour.difference.delta_E_CMC`},
166 *Lightness* weighting factor.
167 textiles
168 {:func:`colour.difference.delta_E_CIE1994`,
169 :func:`colour.difference.delta_E_CIE2000`,
170 :func:`colour.difference.delta_E_DIN99`},
171 Textiles application specific parametric factors
172 :math:`k_L=2,\\ k_C=k_H=1,\\ k_1=0.048,\\ k_2=0.014,\\ k_E=2,\\ k_{CH}=0.5`
173 weights are used instead of
174 :math:`k_L=k_C=k_H=1,\\ k_1=0.045,\\ k_2=0.015,\\ k_E=k_{CH}=1.0`.
176 Returns
177 -------
178 :class:`numpy.ndarray`
179 Colour difference :math:`\\Delta E_{ab}`.
181 References
182 ----------
183 :cite:`ASTMInternational2007`,
184 :cite:`InternationalTelecommunicationUnion2019`, :cite:`Li2017`,
185 :cite:`Lindbloom2003c`, :cite:`Lindbloom2011a`, :cite:`Lindbloom2009f`,
186 :cite:`Luo2006b`, :cite:`Melgosa2013b`, :cite:`Wikipedia2008b`
188 Examples
189 --------
190 >>> import numpy as np
191 >>> a = np.array([48.99183622, -0.10561667, 400.65619925])
192 >>> b = np.array([50.65907324, -0.11671910, 402.82235718])
193 >>> delta_E(a, b) # doctest: +ELLIPSIS
194 1.6709303...
195 >>> delta_E(a, b, method="CIE 2000") # doctest: +ELLIPSIS
196 1.6709303...
197 >>> delta_E(a, b, method="CIE 1976") # doctest: +ELLIPSIS
198 2.7335037...
199 >>> delta_E(a, b, method="CIE 1994") # doctest: +ELLIPSIS
200 1.6711191...
201 >>> delta_E(a, b, method="CIE 1994", textiles=True)
202 ... # doctest: +ELLIPSIS
203 0.8404677...
204 >>> delta_E(a, b, method="DIN99") # doctest: +ELLIPSIS
205 1.5591089...
206 >>> a = np.array([0.4885468072, -0.04739350675, 0.07475401302])
207 >>> b = np.array([0.4899203231, -0.04567508203, 0.07361341775])
208 >>> delta_E(a, b, method="ITP") # doctest: +ELLIPSIS
209 1.42657228...
210 >>> a = np.array([54.90433134, -0.08450395, -0.06854831])
211 >>> b = np.array([54.90433134, -0.08442362, -0.06848314])
212 >>> delta_E(a, b, method="CAM02-UCS") # doctest: +ELLIPSIS
213 0.0001034...
214 >>> delta_E(a, b, method="CAM16-LCD") # doctest: +ELLIPSIS
215 0.0001034...
216 >>> a = np.array([39.91531343, 51.16658481, 146.12933781])
217 >>> b = np.array([53.12207516, -39.92365056, 249.54831278])
218 >>> delta_E(a, b, method="HyAB") # doctest: +ELLIPSIS
219 151.0215481...
220 >>> a = np.array([39.91531343, 51.16658481, 146.12933781])
221 >>> b = np.array([53.12207516, -39.92365056, 249.54831278])
222 >>> delta_E(a, b, method="HyCH") # doctest: +ELLIPSIS
223 48.66427941...
224 """
226 method = validate_method(method, tuple(DELTA_E_METHODS))
228 function = DELTA_E_METHODS[method]
230 return function(a, b, **filter_kwargs(function, **kwargs))
233__all__ += [
234 "DELTA_E_METHODS",
235 "delta_E",
236]