Coverage for colour/appearance/hellwig2022.py: 100%
164 statements
« prev ^ index » next coverage.py v7.11.0, created at 2025-11-15 19:01 +1300
1"""
2Hellwig and Fairchild (2022) Colour Appearance Model
3====================================================
5Define the *Hellwig and Fairchild (2022)* colour appearance model for
6predicting perceptual colour attributes under varying viewing conditions.
8- :class:`colour.appearance.InductionFactors_Hellwig2022`
9- :attr:`colour.VIEWING_CONDITIONS_HELLWIG2022`
10- :class:`colour.CAM_Specification_Hellwig2022`
11- :func:`colour.XYZ_to_Hellwig2022`
12- :func:`colour.Hellwig2022_to_XYZ`
14References
15----------
16- :cite:`Fairchild2022` : Fairchild, M. D., & Hellwig, L. (2022). Private
17 Discussion with Mansencal, T.
18- :cite:`Hellwig2022` : Hellwig, L., & Fairchild, M. D. (2022). Brightness,
19 lightness, colorfulness, and chroma in CIECAM02 and CAM16. Color Research
20 & Application, col.22792. doi:10.1002/col.22792
21- :cite:`Hellwig2022a` : Hellwig, L., Stolitzka, D., & Fairchild, M. D.
22 (2022). Extending CIECAM02 and CAM16 for the Helmholtz-Kohlrausch effect.
23 Color Research & Application, col.22793. doi:10.1002/col.22793
24"""
26from __future__ import annotations
28import typing
29from dataclasses import astuple, dataclass, field
31import numpy as np
33from colour.algebra import sdiv, sdiv_mode, spow, vecmul
34from colour.appearance.cam16 import MATRIX_16, MATRIX_INVERSE_16
35from colour.appearance.ciecam02 import (
36 VIEWING_CONDITIONS_CIECAM02,
37 InductionFactors_CIECAM02,
38 achromatic_response_inverse,
39 base_exponential_non_linearity,
40 degree_of_adaptation,
41 hue_angle,
42 hue_quadrature,
43 lightness_correlate,
44 matrix_post_adaptation_non_linear_response_compression,
45 opponent_colour_dimensions_forward,
46 post_adaptation_non_linear_response_compression_forward,
47 post_adaptation_non_linear_response_compression_inverse,
48)
49from colour.appearance.hunt import luminance_level_adaptation_factor
51if typing.TYPE_CHECKING:
52 from colour.hints import Tuple
54from colour.hints import ( # noqa: TC001
55 Annotated,
56 ArrayLike,
57 Domain100,
58 NDArrayFloat,
59 Range100,
60)
61from colour.utilities import (
62 CanonicalMapping,
63 MixinDataclassArithmetic,
64 MixinDataclassIterable,
65 as_float,
66 as_float_array,
67 from_range_100,
68 from_range_degrees,
69 has_only_nan,
70 ones,
71 to_domain_100,
72 to_domain_degrees,
73 tsplit,
74 tstack,
75)
77__author__ = "Colour Developers"
78__copyright__ = "Copyright 2013 Colour Developers"
79__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
80__maintainer__ = "Colour Developers"
81__email__ = "colour-developers@colour-science.org"
82__status__ = "Production"
84__all__ = [
85 "InductionFactors_Hellwig2022",
86 "VIEWING_CONDITIONS_HELLWIG2022",
87 "CAM_Specification_Hellwig2022",
88 "XYZ_to_Hellwig2022",
89 "Hellwig2022_to_XYZ",
90 "viewing_conditions_dependent_parameters",
91 "achromatic_response_forward",
92 "opponent_colour_dimensions_inverse",
93 "eccentricity_factor",
94 "brightness_correlate",
95 "colourfulness_correlate",
96 "chroma_correlate",
97 "saturation_correlate",
98 "P_p",
99 "hue_angle_dependency_Hellwig2022",
100]
103@dataclass(frozen=True)
104class InductionFactors_Hellwig2022(MixinDataclassIterable):
105 """
106 Define the *Hellwig and Fairchild (2022)* colour appearance model
107 induction factors.
109 Parameters
110 ----------
111 F
112 Maximum degree of adaptation :math:`F`.
113 c
114 Exponential non-linearity :math:`c`.
115 N_c
116 Chromatic induction factor :math:`N_c`.
118 Notes
119 -----
120 - The *Hellwig and Fairchild (2022)* colour appearance model induction
121 factors are the same as *CIECAM02* and *CAM16* colour appearance model.
123 References
124 ----------
125 :cite:`Fairchild2022`, :cite:`Hellwig2022`
126 """
128 F: float
129 c: float
130 N_c: float
133VIEWING_CONDITIONS_HELLWIG2022: CanonicalMapping = CanonicalMapping(
134 VIEWING_CONDITIONS_CIECAM02
135)
136VIEWING_CONDITIONS_HELLWIG2022.__doc__ = """
137Define the reference *Hellwig and Fairchild (2022)* colour appearance model
138viewing conditions.
140References
141----------
142:cite:`Hellwig2022`
143"""
146@dataclass
147class CAM_Specification_Hellwig2022(MixinDataclassArithmetic):
148 """
149 Define the *Hellwig and Fairchild (2022)* colour appearance model
150 specification.
152 Represent colour appearance attributes calculated by the
153 *Hellwig and Fairchild (2022)* colour appearance model. The
154 specification includes correlates for lightness, chroma, hue,
155 saturation, brightness, colourfulness, and hue quadrature. This
156 implementation supports the *Helmholtz-Kohlrausch* effect extension
157 from :cite:`Hellwig2022a`, providing adjusted lightness and brightness
158 correlates that account for the increased brightness perception of
159 highly saturated colours.
161 Parameters
162 ----------
163 J
164 Correlate of *lightness* :math:`J`.
165 C
166 Correlate of *chroma* :math:`C`.
167 h
168 *Hue* angle :math:`h` in degrees.
169 s
170 Correlate of *saturation* :math:`s`.
171 Q
172 Correlate of *brightness* :math:`Q`.
173 M
174 Correlate of *colourfulness* :math:`M`.
175 H
176 *Hue* :math:`h` quadrature :math:`H`.
177 HC
178 *Hue* :math:`h` composition :math:`H^C`.
179 J_HK
180 Correlate of *lightness* :math:`J_{HK}` accounting for
181 *Helmholtz-Kohlrausch* effect.
182 Q_HK
183 Correlate of *brightness* :math:`Q_{HK}` accounting for
184 *Helmholtz-Kohlrausch* effect.
186 References
187 ----------
188 :cite:`Fairchild2022`, :cite:`Hellwig2022`, :cite:`Hellwig2022a`
189 """
191 J: float | NDArrayFloat | None = field(default_factory=lambda: None)
192 C: float | NDArrayFloat | None = field(default_factory=lambda: None)
193 h: float | NDArrayFloat | None = field(default_factory=lambda: None)
194 s: float | NDArrayFloat | None = field(default_factory=lambda: None)
195 Q: float | NDArrayFloat | None = field(default_factory=lambda: None)
196 M: float | NDArrayFloat | None = field(default_factory=lambda: None)
197 H: float | NDArrayFloat | None = field(default_factory=lambda: None)
198 HC: float | NDArrayFloat | None = field(default_factory=lambda: None)
199 J_HK: float | NDArrayFloat | None = field(default_factory=lambda: None)
200 Q_HK: float | NDArrayFloat | None = field(default_factory=lambda: None)
203def XYZ_to_Hellwig2022(
204 XYZ: Domain100,
205 XYZ_w: Domain100,
206 L_A: ArrayLike,
207 Y_b: ArrayLike,
208 surround: (
209 InductionFactors_CIECAM02 | InductionFactors_Hellwig2022
210 ) = VIEWING_CONDITIONS_HELLWIG2022["Average"],
211 discount_illuminant: bool = False,
212 compute_H: bool = True,
213) -> Annotated[
214 CAM_Specification_Hellwig2022, (100, 100, 360, 100, 100, 100, 400, 100, 100)
215]:
216 """
217 Compute the *Hellwig and Fairchild (2022)* colour appearance model
218 correlates from the specified *CIE XYZ* tristimulus values.
220 This implementation supports the *Helmholtz-Kohlrausch* effect extension
221 from :cite:`Hellwig2022a`.
223 Parameters
224 ----------
225 XYZ
226 *CIE XYZ* tristimulus values of test sample / stimulus.
227 XYZ_w
228 *CIE XYZ* tristimulus values of reference white.
229 L_A
230 Adapting field *luminance* :math:`L_A` in :math:`cd/m^2`, (often taken
231 to be 20% of the luminance of a white object in the scene).
232 Y_b
233 Luminous factor of background :math:`Y_b` such as
234 :math:`Y_b = 100 \\times L_b / L_w` where :math:`L_w` is the luminance
235 of the light source and :math:`L_b` is the luminance of the background.
236 For viewing images, :math:`Y_b` can be the average :math:`Y` value for
237 the pixels in the entire image, or frequently, a :math:`Y` value of 20,
238 approximating an :math:`L^*` of 50 is used.
239 surround
240 Surround viewing conditions induction factors.
241 discount_illuminant
242 Truth value indicating if the illuminant should be discounted.
243 compute_H
244 Whether to compute *Hue* :math:`h` quadrature :math:`H`. :math:`H` is
245 rarely used, and expensive to compute.
247 Returns
248 -------
249 :class:`colour.CAM_Specification_Hellwig2022`
250 *Hellwig and Fairchild (2022)* colour appearance model specification.
252 Notes
253 -----
254 +------------------------+-----------------------+---------------+
255 | **Domain** | **Scale - Reference** | **Scale - 1** |
256 +========================+=======================+===============+
257 | ``XYZ`` | 100 | 1 |
258 +------------------------+-----------------------+---------------+
259 | ``XYZ_w`` | 100 | 1 |
260 +------------------------+-----------------------+---------------+
262 +------------------------+-----------------------+---------------+
263 | **Range** | **Scale - Reference** | **Scale - 1** |
264 +========================+=======================+===============+
265 | ``specification.J`` | 100 | 1 |
266 +------------------------+-----------------------+---------------+
267 | ``specification.C`` | 100 | 1 |
268 +------------------------+-----------------------+---------------+
269 | ``specification.h`` | 360 | 1 |
270 +------------------------+-----------------------+---------------+
271 | ``specification.s`` | 100 | 1 |
272 +------------------------+-----------------------+---------------+
273 | ``specification.Q`` | 100 | 1 |
274 +------------------------+-----------------------+---------------+
275 | ``specification.M`` | 100 | 1 |
276 +------------------------+-----------------------+---------------+
277 | ``specification.H`` | 400 | 1 |
278 +------------------------+-----------------------+---------------+
279 | ``specification.J_HK`` | 100 | 1 |
280 +------------------------+-----------------------+---------------+
281 | ``specification.Q_HK`` | 100 | 1 |
282 +------------------------+-----------------------+---------------+
284 References
285 ----------
286 :cite:`Fairchild2022`, :cite:`Hellwig2022`, :cite:`Hellwig2022a`
288 Examples
289 --------
290 >>> XYZ = np.array([19.01, 20.00, 21.78])
291 >>> XYZ_w = np.array([95.05, 100.00, 108.88])
292 >>> L_A = 318.31
293 >>> Y_b = 20.0
294 >>> surround = VIEWING_CONDITIONS_HELLWIG2022["Average"]
295 >>> XYZ_to_Hellwig2022(XYZ, XYZ_w, L_A, Y_b, surround)
296 ... # doctest: +ELLIPSIS
297 CAM_Specification_Hellwig2022(J=41.7312079..., C=0.0257636..., \
298h=217.0679597..., s=0.0608550..., Q=55.8523226..., M=0.0339889..., \
299H=275.5949861..., HC=None, J_HK=41.8802782..., Q_HK=56.0518358...)
300 """
302 XYZ = to_domain_100(XYZ)
303 XYZ_w = to_domain_100(XYZ_w)
304 _X_w, Y_w, _Z_w = tsplit(XYZ_w)
305 L_A = as_float_array(L_A)
306 Y_b = as_float_array(Y_b)
308 # Step 0
309 # Converting *CIE XYZ* tristimulus values to sharpened *RGB* values.
310 RGB_w = vecmul(MATRIX_16, XYZ_w)
312 # Computing degree of adaptation :math:`D`.
313 D = (
314 np.clip(degree_of_adaptation(surround.F, L_A), 0, 1)
315 if not discount_illuminant
316 else ones(L_A.shape)
317 )
319 F_L, z = viewing_conditions_dependent_parameters(Y_b, Y_w, L_A)
321 D_RGB = D[..., None] * Y_w[..., None] / RGB_w + 1 - D[..., None]
322 RGB_wc = D_RGB * RGB_w
324 # Applying forward post-adaptation non-linear response compression.
325 RGB_aw = post_adaptation_non_linear_response_compression_forward(RGB_wc, F_L)
327 # Computing achromatic responses for the whitepoint.
328 A_w = achromatic_response_forward(RGB_aw)
330 # Step 1
331 # Converting *CIE XYZ* tristimulus values to sharpened *RGB* values.
332 RGB = vecmul(MATRIX_16, XYZ)
334 # Step 2
335 RGB_c = D_RGB * RGB
337 # Step 3
338 # Applying forward post-adaptation non-linear response compression.
339 RGB_a = post_adaptation_non_linear_response_compression_forward(RGB_c, F_L)
341 # Step 4
342 # Converting to preliminary cartesian coordinates.
343 a, b = tsplit(opponent_colour_dimensions_forward(RGB_a))
345 # Computing the *hue* angle :math:`h`.
346 h = hue_angle(a, b)
348 # Step 5
349 # Computing eccentricity factor *e_t*.
350 e_t = eccentricity_factor(h)
352 # Computing hue :math:`h` quadrature :math:`H`.
353 H = hue_quadrature(h) if compute_H else np.full(h.shape, np.nan)
354 # TODO: Compute hue composition.
356 # Step 6
357 # Computing achromatic responses for the stimulus.
358 A = achromatic_response_forward(RGB_a)
360 # Step 7
361 # Computing the correlate of *Lightness* :math:`J`.
362 J = lightness_correlate(A, A_w, surround.c, z)
364 # Step 8
365 # Computing the correlate of *brightness* :math:`Q`.
366 Q = brightness_correlate(surround.c, J, A_w)
368 # Step 9
369 # Computing the correlate of *colourfulness* :math:`M`.
370 M = colourfulness_correlate(surround.N_c, e_t, a, b)
372 # Computing the correlate of *chroma* :math:`C`.
373 C = chroma_correlate(M, A_w)
375 # Computing the correlate of *saturation* :math:`s`.
376 s = saturation_correlate(M, Q)
378 # *Helmholtz-Kohlrausch* Effect Extension.
379 J_HK = J + hue_angle_dependency_Hellwig2022(h) * spow(C, 0.587)
380 Q_HK = (2 / surround.c) * (J_HK / 100) * A_w
382 return CAM_Specification_Hellwig2022(
383 J=as_float(from_range_100(J)),
384 C=as_float(from_range_100(C)),
385 h=as_float(from_range_degrees(h)),
386 s=as_float(from_range_100(s)),
387 Q=as_float(from_range_100(Q)),
388 M=as_float(from_range_100(M)),
389 H=as_float(from_range_degrees(H, 400)),
390 HC=None,
391 J_HK=as_float(from_range_100(J_HK)),
392 Q_HK=as_float(from_range_100(Q_HK)),
393 )
396def Hellwig2022_to_XYZ(
397 specification: Annotated[
398 CAM_Specification_Hellwig2022, (100, 100, 360, 100, 100, 100, 400, 100, 100)
399 ],
400 XYZ_w: Domain100,
401 L_A: ArrayLike,
402 Y_b: ArrayLike,
403 surround: (
404 InductionFactors_CIECAM02 | InductionFactors_Hellwig2022
405 ) = VIEWING_CONDITIONS_HELLWIG2022["Average"],
406 discount_illuminant: bool = False,
407) -> Range100:
408 """
409 Convert the *Hellwig and Fairchild (2022)* colour appearance model
410 specification to *CIE XYZ* tristimulus values.
412 This implementation supports the *Helmholtz-Kohlrausch* effect extension
413 from :cite:`Hellwig2022a`.
415 Parameters
416 ----------
417 specification
418 *Hellwig and Fairchild (2022)* colour appearance model specification.
419 Correlate of *lightness* :math:`J`, correlate of *chroma* :math:`C`
420 or correlate of *colourfulness* :math:`M` and *hue* angle :math:`h`
421 in degrees must be specified, e.g., :math:`JCh` or :math:`JMh`.
422 XYZ_w
423 *CIE XYZ* tristimulus values of reference white.
424 L_A
425 Adapting field *luminance* :math:`L_A` in :math:`cd/m^2`, (often
426 taken to be 20% of the luminance of a white object in the scene).
427 Y_b
428 Luminous factor of background :math:`Y_b` such as
429 :math:`Y_b = 100 \\times L_b / L_w` where :math:`L_w` is the
430 luminance of the light source and :math:`L_b` is the luminance of the
431 background. For viewing images, :math:`Y_b` can be the average
432 :math:`Y` value for the pixels in the entire image, or frequently, a
433 :math:`Y` value of 20, approximating an :math:`L^*` of 50 is used.
434 surround
435 Surround viewing conditions.
436 discount_illuminant
437 Discount the illuminant.
439 Returns
440 -------
441 :class:`numpy.ndarray`
442 *CIE XYZ* tristimulus values.
444 Raises
445 ------
446 ValueError
447 If neither :math:`C` or :math:`M` correlates have been defined in
448 the ``specification`` argument.
450 Notes
451 -----
452 +------------------------+-----------------------+---------------+
453 | **Domain** | **Scale - Reference** | **Scale - 1** |
454 +========================+=======================+===============+
455 | ``specification.J`` | 100 | 1 |
456 +------------------------+-----------------------+---------------+
457 | ``specification.C`` | 100 | 1 |
458 +------------------------+-----------------------+---------------+
459 | ``specification.h`` | 360 | 1 |
460 +------------------------+-----------------------+---------------+
461 | ``specification.s`` | 100 | 1 |
462 +------------------------+-----------------------+---------------+
463 | ``specification.Q`` | 100 | 1 |
464 +------------------------+-----------------------+---------------+
465 | ``specification.M`` | 100 | 1 |
466 +------------------------+-----------------------+---------------+
467 | ``specification.H`` | 400 | 1 |
468 +------------------------+-----------------------+---------------+
469 | ``specification.J_HK`` | 100 | 1 |
470 +------------------------+-----------------------+---------------+
471 | ``specification.Q_HK`` | 100 | 1 |
472 +------------------------+-----------------------+---------------+
473 | ``XYZ_w`` | 100 | 1 |
474 +------------------------+-----------------------+---------------+
476 +------------------------+-----------------------+---------------+
477 | **Range** | **Scale - Reference** | **Scale - 1** |
478 +========================+=======================+===============+
479 | ``XYZ`` | 100 | 1 |
480 +------------------------+-----------------------+---------------+
482 References
483 ----------
484 :cite:`Fairchild2022`, :cite:`Hellwig2022`, :cite:`Hellwig2022a`
486 Examples
487 --------
488 >>> specification = CAM_Specification_Hellwig2022(
489 ... J=41.731207905126638, C=0.025763615829912909, h=217.06795976739301
490 ... )
491 >>> XYZ_w = np.array([95.05, 100.00, 108.88])
492 >>> L_A = 318.31
493 >>> Y_b = 20.0
494 >>> Hellwig2022_to_XYZ(specification, XYZ_w, L_A, Y_b)
495 ... # doctest: +ELLIPSIS
496 array([ 19.01..., 20... , 21.78...])
497 >>> specification = CAM_Specification_Hellwig2022(
498 ... J_HK=41.880278283880095,
499 ... C=0.025763615829912909,
500 ... h=217.06795976739301,
501 ... )
502 >>> Hellwig2022_to_XYZ(specification, XYZ_w, L_A, Y_b)
503 ... # doctest: +ELLIPSIS
504 array([ 19.01..., 20... , 21.78...])
505 """
507 J, C, h, _s, _Q, M, _H, _HC, J_HK, _Q_HK = astuple(specification)
509 C = to_domain_100(C)
510 h = to_domain_degrees(h)
511 M = to_domain_100(M)
513 if has_only_nan(J) and not has_only_nan(J_HK):
514 J_HK = to_domain_100(J_HK)
516 J = J_HK - hue_angle_dependency_Hellwig2022(h) * spow(C, 0.587)
517 elif has_only_nan(J):
518 error = (
519 'Either "J" or "J_HK" correlate must be defined in '
520 'the "CAM_Specification_Hellwig2022" argument!'
521 )
523 raise ValueError(error)
524 else:
525 J = to_domain_100(J)
527 L_A = as_float_array(L_A)
528 XYZ_w = to_domain_100(XYZ_w)
529 _X_w, Y_w, _Z_w = tsplit(XYZ_w)
531 # Step 0
532 # Converting *CIE XYZ* tristimulus values to sharpened *RGB* values.
533 RGB_w = vecmul(MATRIX_16, XYZ_w)
535 # Computing degree of adaptation :math:`D`.
536 D = (
537 np.clip(degree_of_adaptation(surround.F, L_A), 0, 1)
538 if not discount_illuminant
539 else ones(L_A.shape)
540 )
542 F_L, z = viewing_conditions_dependent_parameters(Y_b, Y_w, L_A)
544 D_RGB = D[..., None] * Y_w[..., None] / RGB_w + 1 - D[..., None]
545 RGB_wc = D_RGB * RGB_w
547 # Applying forward post-adaptation non-linear response compression.
548 RGB_aw = post_adaptation_non_linear_response_compression_forward(RGB_wc, F_L)
550 # Computing achromatic responses for the whitepoint.
551 A_w = achromatic_response_forward(RGB_aw)
553 # Step 1
554 if has_only_nan(M) and not has_only_nan(C):
555 M = (C * A_w) / 35
556 elif has_only_nan(M):
557 error = (
558 'Either "C" or "M" correlate must be defined in '
559 'the "CAM_Specification_Hellwig2022" argument!'
560 )
562 raise ValueError(error)
564 # Step 2
565 # Computing eccentricity factor *e_t*.
566 e_t = eccentricity_factor(h)
568 # Computing achromatic response :math:`A` for the stimulus.
569 A = achromatic_response_inverse(A_w, J, surround.c, z)
571 # Computing *P_p_1* to *P_p_2*.
572 P_p_n = P_p(surround.N_c, e_t, A)
573 P_p_1, P_p_2 = tsplit(P_p_n)
575 # Step 3
576 # Computing opponent colour dimensions :math:`a` and :math:`b`.
577 ab = opponent_colour_dimensions_inverse(P_p_1, h, M)
578 a, b = tsplit(ab)
580 # Step 4
581 # Applying post-adaptation non-linear response compression matrix.
582 RGB_a = matrix_post_adaptation_non_linear_response_compression(P_p_2, a, b)
584 # Step 5
585 # Applying inverse post-adaptation non-linear response compression.
586 RGB_c = post_adaptation_non_linear_response_compression_inverse(RGB_a + 0.1, F_L)
588 # Step 6
589 RGB = RGB_c / D_RGB
591 # Step 7
592 XYZ = vecmul(MATRIX_INVERSE_16, RGB)
594 return from_range_100(XYZ)
597def viewing_conditions_dependent_parameters(
598 Y_b: ArrayLike,
599 Y_w: ArrayLike,
600 L_A: ArrayLike,
601) -> Tuple[NDArrayFloat, NDArrayFloat]:
602 """
603 Compute the viewing condition dependent parameters.
605 Parameters
606 ----------
607 Y_b
608 Adapting field *Y* tristimulus value :math:`Y_b`.
609 Y_w
610 Whitepoint *Y* tristimulus value :math:`Y_w`.
611 L_A
612 Adapting field *luminance* :math:`L_A` in :math:`cd/m^2`.
614 Returns
615 -------
616 :class:`tuple`
617 Viewing condition dependent parameters.
619 Examples
620 --------
621 >>> viewing_conditions_dependent_parameters(20.0, 100.0, 318.31)
622 ... # doctest: +ELLIPSIS
623 (1.1675444..., 1.9272135...)
624 """
626 Y_b = as_float_array(Y_b)
627 Y_w = as_float_array(Y_w)
629 with sdiv_mode():
630 n = sdiv(Y_b, Y_w)
632 F_L = luminance_level_adaptation_factor(L_A)
633 z = base_exponential_non_linearity(n)
635 return F_L, z
638def achromatic_response_forward(RGB: ArrayLike) -> NDArrayFloat:
639 """
640 Compute the achromatic response :math:`A` from the specified compressed
641 *CAM16* transform sharpened *RGB* array for forward *Hellwig and Fairchild
642 (2022)* implementation.
644 Parameters
645 ----------
646 RGB
647 Compressed *CAM16* transform sharpened *RGB* array.
649 Returns
650 -------
651 :class:`numpy.ndarray`
652 Achromatic response :math:`A`.
654 Examples
655 --------
656 >>> RGB = np.array([7.94634384, 7.94713791, 7.9488967])
657 >>> achromatic_response_forward(RGB) # doctest: +ELLIPSIS
658 23.9322704...
659 """
661 R, G, B = tsplit(RGB)
663 return 2 * R + G + 0.05 * B - 0.305
666def opponent_colour_dimensions_inverse(
667 P_p_1: ArrayLike, h: ArrayLike, M: ArrayLike
668) -> NDArrayFloat:
669 """
670 Compute opponent colour dimensions from the specified point :math:`P'_1`,
671 hue :math:`h` in degrees and correlate of *colourfulness* :math:`M` for
672 inverse *Hellwig and Fairchild (2022)* implementation.
674 Parameters
675 ----------
676 P_p_1
677 Point :math:`P'_1`.
678 h
679 Hue :math:`h` in degrees.
680 M
681 Correlate of *colourfulness* :math:`M`.
683 Returns
684 -------
685 :class:`numpy.ndarray`
686 Opponent colour dimensions.
688 Examples
689 --------
690 >>> P_p_1 = 48.7719436928
691 >>> h = 217.067959767393
692 >>> M = 0.0387637282462
693 >>> opponent_colour_dimensions_inverse(P_p_1, h, M) # doctest: +ELLIPSIS
694 array([-0.0006341..., -0.0004790...])
695 """
697 P_p_1 = as_float_array(P_p_1)
698 M = as_float_array(M)
700 hr = np.radians(h)
702 with sdiv_mode():
703 gamma = M / P_p_1
705 a = gamma * np.cos(hr)
706 b = gamma * np.sin(hr)
708 return tstack([a, b])
711def eccentricity_factor(h: ArrayLike) -> NDArrayFloat:
712 """
713 Compute the eccentricity factor :math:`e_t` from the specified hue
714 :math:`h` angle in degrees for forward *CIECAM02* implementation.
716 Parameters
717 ----------
718 h
719 Hue :math:`h` angle in degrees.
721 Returns
722 -------
723 :class:`numpy.ndarray`
724 Eccentricity factor :math:`e_t`.
726 Examples
727 --------
728 >>> eccentricity_factor(217.067959767393) # doctest: +ELLIPSIS
729 0.9945215...
730 """
732 h = as_float_array(h)
734 hr = np.radians(h)
736 _h = hr
737 _2_h = 2 * hr
738 _3_h = 3 * hr
739 _4_h = 4 * hr
741 return (
742 -0.0582 * np.cos(_h)
743 - 0.0258 * np.cos(_2_h)
744 - 0.1347 * np.cos(_3_h)
745 + 0.0289 * np.cos(_4_h)
746 - 0.1475 * np.sin(_h)
747 - 0.0308 * np.sin(_2_h)
748 + 0.0385 * np.sin(_3_h)
749 + 0.0096 * np.sin(_4_h)
750 + 1
751 )
754def brightness_correlate(
755 c: ArrayLike,
756 J: ArrayLike,
757 A_w: ArrayLike,
758) -> NDArrayFloat:
759 """
760 Compute the *brightness* correlate :math:`Q`.
762 Parameters
763 ----------
764 c
765 Surround exponential non-linearity :math:`c`.
766 J
767 *Lightness* correlate :math:`J`.
768 A_w
769 Achromatic response :math:`A_w` for the whitepoint.
771 Returns
772 -------
773 :class:`numpy.ndarray`
774 *Brightness* correlate :math:`Q`.
776 Examples
777 --------
778 >>> c = 0.69
779 >>> J = 41.7310911325
780 >>> A_w = 46.1741997997
781 >>> brightness_correlate(c, J, A_w) # doctest: +ELLIPSIS
782 55.8521663...
783 """
785 c = as_float_array(c)
786 J = as_float_array(J)
787 A_w = as_float_array(A_w)
789 with sdiv_mode():
790 return (2 / c) * (J / 100) * A_w
793def colourfulness_correlate(
794 N_c: ArrayLike,
795 e_t: ArrayLike,
796 a: ArrayLike,
797 b: ArrayLike,
798) -> NDArrayFloat:
799 """
800 Compute the *colourfulness* correlate :math:`M`.
802 Parameters
803 ----------
804 N_c
805 Surround chromatic induction factor :math:`N_c`.
806 e_t
807 Eccentricity factor :math:`e_t`.
808 a
809 Opponent colour dimension :math:`a`.
810 b
811 Opponent colour dimension :math:`b`.
813 Returns
814 -------
815 :class:`numpy.ndarray`
816 *Colourfulness* correlate :math:`M`.
818 Examples
819 --------
820 >>> N_c = 1
821 >>> e_t = 1.13423124867
822 >>> a = -0.00063418423001
823 >>> b = -0.000479072513542
824 >>> colourfulness_correlate(N_c, e_t, a, b) # doctest: +ELLIPSIS
825 0.0387637...
826 """
828 N_c = as_float_array(N_c)
829 e_t = as_float_array(e_t)
830 a = as_float_array(a)
831 b = as_float_array(b)
833 return 43.0 * N_c * e_t * np.hypot(a, b)
836def chroma_correlate(
837 M: ArrayLike,
838 A_w: ArrayLike,
839) -> NDArrayFloat:
840 """
841 Compute the *chroma* correlate :math:`C`.
843 Parameters
844 ----------
845 M
846 *Colourfulness* correlate :math:`M`.
847 A_w
848 Achromatic response :math:`A_w` for the whitepoint.
850 Returns
851 -------
852 :class:`numpy.ndarray`
853 *Chroma* correlate :math:`C`.
855 Examples
856 --------
857 >>> M = 0.0387637282462
858 >>> A_w = 46.1741997997
859 >>> chroma_correlate(M, A_w) # doctest: +ELLIPSIS
860 0.0293828...
861 """
863 M = as_float_array(M)
864 A_w = as_float_array(A_w)
866 with sdiv_mode():
867 return 35 * sdiv(M, A_w)
870def saturation_correlate(M: ArrayLike, Q: ArrayLike) -> NDArrayFloat:
871 """
872 Compute the *saturation* correlate :math:`s`.
874 Parameters
875 ----------
876 M
877 *Colourfulness* correlate :math:`M`.
878 Q
879 *Brightness* correlate :math:`Q`.
881 Returns
882 -------
883 :class:`numpy.ndarray`
884 *Saturation* correlate :math:`s`.
886 Examples
887 --------
888 >>> M = 0.0387637282462
889 >>> Q = 55.8523226578
890 >>> saturation_correlate(M, Q) # doctest: +ELLIPSIS
891 0.0694039...
892 """
894 M = as_float_array(M)
895 Q = as_float_array(Q)
897 with sdiv_mode():
898 return 100 * sdiv(M, Q)
901def P_p(
902 N_c: ArrayLike,
903 e_t: ArrayLike,
904 A: ArrayLike,
905) -> NDArrayFloat:
906 """
907 Compute the points :math:`P'_1` and :math:`P'_2`.
909 Parameters
910 ----------
911 N_c
912 Surround chromatic induction factor :math:`N_{c}`.
913 e_t
914 Eccentricity factor :math:`e_t`.
915 A
916 Achromatic response :math:`A` for the stimulus.
918 Returns
919 -------
920 :class:`numpy.ndarray`
921 Points :math:`P'` as an array containing :math:`P'_1` and
922 :math:`P'_2`.
924 Examples
925 --------
926 >>> N_c = 1
927 >>> e_t = 1.13423124867
928 >>> A = 23.9322704261
929 >>> P_p(N_c, e_t, A) # doctest: +ELLIPSIS
930 array([ 48.7719436..., 23.9322704...])
931 """
933 N_c = as_float_array(N_c)
934 e_t = as_float_array(e_t)
935 A = as_float_array(A)
937 P_p_1 = 43 * N_c * e_t
938 P_p_2 = A
940 return tstack([P_p_1, P_p_2])
943def hue_angle_dependency_Hellwig2022(
944 h: ArrayLike,
945) -> NDArrayFloat:
946 """
947 Compute the hue angle dependency of the *Helmholtz-Kohlrausch* effect.
949 Parameters
950 ----------
951 h
952 Hue :math:`h` angle in degrees.
954 Returns
955 -------
956 :class:`numpy.ndarray`
957 Hue angle dependency of the *Helmholtz-Kohlrausch* effect.
959 References
960 ----------
961 :cite:`Hellwig2022a`
963 Examples
964 --------
965 >>> hue_angle_dependency_Hellwig2022(217.06795976739301)
966 ... # doctest: +ELLIPSIS
967 1.2768219...
968 """
970 h = as_float_array(h)
972 h_r = np.radians(h)
974 return as_float(
975 -0.160 * np.cos(h_r)
976 + 0.132 * np.cos(2 * h_r)
977 - 0.405 * np.sin(h_r)
978 + 0.080 * np.sin(2 * h_r)
979 + 0.792
980 )