Coverage for appearance/hellwig2022.py: 76%

1"""

2 Hellwig and Fairchild (2022) Colour Appearance Model

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

4

5 Define the *Hellwig and Fairchild (2022)* colour appearance model for

6 predicting perceptual colour attributes under varying viewing conditions.

7

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`

13

14 References

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"""

25

26 from __future__ import annotations

27

28 import typing

29 from dataclasses import astuple, dataclass, field

30

31 import numpy as np

32

33 from colour.algebra import sdiv, sdiv_mode, spow, vecmul

34 from colour.appearance.cam16 import MATRIX_16, MATRIX_INVERSE_16

35 from 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)

49 from colour.appearance.hunt import luminance_level_adaptation_factor

50

51 if typing.TYPE_CHECKING:

52 from colour.hints import Tuple

53

54 from colour.hints import ( # noqa: TC001

55 Annotated,

56 ArrayLike,

57 Domain100,

58 NDArrayFloat,

59 Range100,

60)

61 from 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)

76

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"

83

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]

101

102

103@dataclass(frozen=True)

104 class InductionFactors_Hellwig2022(MixinDataclassIterable):

105 """

106 Define the *Hellwig and Fairchild (2022)* colour appearance model

107 induction factors.

108

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`.

117

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.

122

123 References

124 ----------

125 :cite:`Fairchild2022`, :cite:`Hellwig2022`

126 """

127

128 F: float

129 c: float

130 N_c: float

131

132

133 VIEWING_CONDITIONS_HELLWIG2022: CanonicalMapping = CanonicalMapping(

134 VIEWING_CONDITIONS_CIECAM02

135)

136 VIEWING_CONDITIONS_HELLWIG2022.__doc__ = """

137 Define the reference *Hellwig and Fairchild (2022)* colour appearance model

138 viewing conditions.

139

140 References

141----------

142:cite:`Hellwig2022`

143"""

144

145

146@dataclass

147 class CAM_Specification_Hellwig2022(MixinDataclassArithmetic):

148 """

149 Define the *Hellwig and Fairchild (2022)* colour appearance model

150 specification.

151

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.

160

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.

185

186 References

187 ----------

188 :cite:`Fairchild2022`, :cite:`Hellwig2022`, :cite:`Hellwig2022a`

189 """

190

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)

201

202

203 def 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.

219

220 This implementation supports the *Helmholtz-Kohlrausch* effect extension

221 from :cite:`Hellwig2022a`.

222

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.

246

247 Returns

248 -------

249 :class:`colour.CAM_Specification_Hellwig2022`

250 *Hellwig and Fairchild (2022)* colour appearance model specification.

251

252 Notes

253 -----

254 +------------------------+-----------------------+---------------+

255 | **Domain** | **Scale - Reference** | **Scale - 1** |

256 +========================+=======================+===============+

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

258 +------------------------+-----------------------+---------------+

259 | ``XYZ_w`` | 100 | 1 |

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

261

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 +------------------------+-----------------------+---------------+

283

284 References

285 ----------

286 :cite:`Fairchild2022`, :cite:`Hellwig2022`, :cite:`Hellwig2022a`

287

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..., \

298 h=217.0679597..., s=0.0608550..., Q=55.8523226..., M=0.0339889..., \

299 H=275.5949861..., HC=None, J_HK=41.8802782..., Q_HK=56.0518358...)

300 """

301

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)

307

308 # Step 0

309 # Converting *CIE XYZ* tristimulus values to sharpened *RGB* values.

310 RGB_w = vecmul(MATRIX_16, XYZ_w)

311

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 )

318

319 F_L, z = viewing_conditions_dependent_parameters(Y_b, Y_w, L_A)

320

321 D_RGB = D[..., None] * Y_w[..., None] / RGB_w + 1 - D[..., None]

322 RGB_wc = D_RGB * RGB_w

323

324 # Applying forward post-adaptation non-linear response compression.

325 RGB_aw = post_adaptation_non_linear_response_compression_forward(RGB_wc, F_L)

326

327 # Computing achromatic responses for the whitepoint.

328 A_w = achromatic_response_forward(RGB_aw)

329

330 # Step 1

331 # Converting *CIE XYZ* tristimulus values to sharpened *RGB* values.

332 RGB = vecmul(MATRIX_16, XYZ)

333

334 # Step 2

335 RGB_c = D_RGB * RGB

336

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)

340

341 # Step 4

342 # Converting to preliminary cartesian coordinates.

343 a, b = tsplit(opponent_colour_dimensions_forward(RGB_a))

344

345 # Computing the *hue* angle :math:`h`.

346 h = hue_angle(a, b)

347

348 # Step 5

349 # Computing eccentricity factor *e_t*.

350 e_t = eccentricity_factor(h)

351

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.

355

356 # Step 6

357 # Computing achromatic responses for the stimulus.

358 A = achromatic_response_forward(RGB_a)

359

360 # Step 7

361 # Computing the correlate of *Lightness* :math:`J`.

362 J = lightness_correlate(A, A_w, surround.c, z)

363

364 # Step 8

365 # Computing the correlate of *brightness* :math:`Q`.

366 Q = brightness_correlate(surround.c, J, A_w)

367

368 # Step 9

369 # Computing the correlate of *colourfulness* :math:`M`.

370 M = colourfulness_correlate(surround.N_c, e_t, a, b)

371

372 # Computing the correlate of *chroma* :math:`C`.

373 C = chroma_correlate(M, A_w)

374

375 # Computing the correlate of *saturation* :math:`s`.

376 s = saturation_correlate(M, Q)

377

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

381

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 )

394

395

396 def 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.

411

412 This implementation supports the *Helmholtz-Kohlrausch* effect extension

413 from :cite:`Hellwig2022a`.

414

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.

438

439 Returns

440 -------

441 :class:`numpy.ndarray`

442 *CIE XYZ* tristimulus values.

443

444 Raises

445 ------

446 ValueError

447 If neither :math:`C` or :math:`M` correlates have been defined in

448 the ``specification`` argument.

449

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 +------------------------+-----------------------+---------------+

475

476 +------------------------+-----------------------+---------------+

477 | **Range** | **Scale - Reference** | **Scale - 1** |

478 +========================+=======================+===============+

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

480 +------------------------+-----------------------+---------------+

481

482 References

483 ----------

484 :cite:`Fairchild2022`, :cite:`Hellwig2022`, :cite:`Hellwig2022a`

485

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 """

506

507 J, C, h, _s, _Q, M, _H, _HC, J_HK, _Q_HK = astuple(specification)

508

509 C = to_domain_100(C)

510 h = to_domain_degrees(h)

511 M = to_domain_100(M)

512

513 if has_only_nan(J) and not has_only_nan(J_HK):

514 J_HK = to_domain_100(J_HK)

515

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 )

522

523 raise ValueError(error)

524 else:

525 J = to_domain_100(J)

526

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)

530

531 # Step 0

532 # Converting *CIE XYZ* tristimulus values to sharpened *RGB* values.

533 RGB_w = vecmul(MATRIX_16, XYZ_w)

534

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 )

541

542 F_L, z = viewing_conditions_dependent_parameters(Y_b, Y_w, L_A)

543

544 D_RGB = D[..., None] * Y_w[..., None] / RGB_w + 1 - D[..., None]

545 RGB_wc = D_RGB * RGB_w

546

547 # Applying forward post-adaptation non-linear response compression.

548 RGB_aw = post_adaptation_non_linear_response_compression_forward(RGB_wc, F_L)

549

550 # Computing achromatic responses for the whitepoint.

551 A_w = achromatic_response_forward(RGB_aw)

552

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 )

561

562 raise ValueError(error)

563

564 # Step 2

565 # Computing eccentricity factor *e_t*.

566 e_t = eccentricity_factor(h)

567

568 # Computing achromatic response :math:`A` for the stimulus.

569 A = achromatic_response_inverse(A_w, J, surround.c, z)

570

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)

574

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)

579

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)

583

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)

587

588 # Step 6

589 RGB = RGB_c / D_RGB

590

591 # Step 7

592 XYZ = vecmul(MATRIX_INVERSE_16, RGB)

593

594 return from_range_100(XYZ)

595

596

597 def 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.

604

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`.

613

614 Returns

615 -------

616 :class:`tuple`

617 Viewing condition dependent parameters.

618

619 Examples

620 --------

621 >>> viewing_conditions_dependent_parameters(20.0, 100.0, 318.31)

622 ... # doctest: +ELLIPSIS

623 (1.1675444..., 1.9272135...)

624 """

625

626 Y_b = as_float_array(Y_b)

627 Y_w = as_float_array(Y_w)

628

629 with sdiv_mode():

630 n = sdiv(Y_b, Y_w)

631

632 F_L = luminance_level_adaptation_factor(L_A)

633 z = base_exponential_non_linearity(n)

634

635 return F_L, z

636

637

638 def 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.

643

644 Parameters

645 ----------

646 RGB

647 Compressed *CAM16* transform sharpened *RGB* array.

648

649 Returns

650 -------

651 :class:`numpy.ndarray`

652 Achromatic response :math:`A`.

653

654 Examples

655 --------

656 >>> RGB = np.array([7.94634384, 7.94713791, 7.9488967])

657 >>> achromatic_response_forward(RGB) # doctest: +ELLIPSIS

658 23.9322704...

659 """

660

661 R, G, B = tsplit(RGB)

662

663 return 2 * R + G + 0.05 * B - 0.305

664

665

666 def 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.

673

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`.

682

683 Returns

684 -------

685 :class:`numpy.ndarray`

686 Opponent colour dimensions.

687

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 """

696

697 P_p_1 = as_float_array(P_p_1)

698 M = as_float_array(M)

699

700 hr = np.radians(h)

701

702 with sdiv_mode():

703 gamma = M / P_p_1

704

705 a = gamma * np.cos(hr)

706 b = gamma * np.sin(hr)

707

708 return tstack([a, b])

709

710

711 def 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.

715

716 Parameters

717 ----------

718 h

719 Hue :math:`h` angle in degrees.

720

721 Returns

722 -------

723 :class:`numpy.ndarray`

724 Eccentricity factor :math:`e_t`.

725

726 Examples

727 --------

728 >>> eccentricity_factor(217.067959767393) # doctest: +ELLIPSIS

729 0.9945215...

730 """

731

732 h = as_float_array(h)

733

734 hr = np.radians(h)

735

736 _h = hr

737 _2_h = 2 * hr

738 _3_h = 3 * hr

739 _4_h = 4 * hr

740

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 )

752

753

754 def brightness_correlate(

755 c: ArrayLike,

756 J: ArrayLike,

757 A_w: ArrayLike,

758) -> NDArrayFloat:

759 """

760 Compute the *brightness* correlate :math:`Q`.

761

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.

770

771 Returns

772 -------

773 :class:`numpy.ndarray`

774 *Brightness* correlate :math:`Q`.

775

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 """

784

785 c = as_float_array(c)

786 J = as_float_array(J)

787 A_w = as_float_array(A_w)

788

789 with sdiv_mode():

790 return (2 / c) * (J / 100) * A_w

791

792

793 def 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`.

801

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`.

812

813 Returns

814 -------

815 :class:`numpy.ndarray`

816 *Colourfulness* correlate :math:`M`.

817

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 """

827

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)

832

833 return 43.0 * N_c * e_t * np.hypot(a, b)

834

835

836 def chroma_correlate(

837 M: ArrayLike,

838 A_w: ArrayLike,

839) -> NDArrayFloat:

840 """

841 Compute the *chroma* correlate :math:`C`.

842

843 Parameters

844 ----------

845 M

846 *Colourfulness* correlate :math:`M`.

847 A_w

848 Achromatic response :math:`A_w` for the whitepoint.

849

850 Returns

851 -------

852 :class:`numpy.ndarray`

853 *Chroma* correlate :math:`C`.

854

855 Examples

856 --------

857 >>> M = 0.0387637282462

858 >>> A_w = 46.1741997997

859 >>> chroma_correlate(M, A_w) # doctest: +ELLIPSIS

860 0.0293828...

861 """

862

863 M = as_float_array(M)

864 A_w = as_float_array(A_w)

865

866 with sdiv_mode():

867 return 35 * sdiv(M, A_w)

868

869

870 def saturation_correlate(M: ArrayLike, Q: ArrayLike) -> NDArrayFloat:

871 """

872 Compute the *saturation* correlate :math:`s`.

873

874 Parameters

875 ----------

876 M

877 *Colourfulness* correlate :math:`M`.

878 Q

879 *Brightness* correlate :math:`Q`.

880

881 Returns

882 -------

883 :class:`numpy.ndarray`

884 *Saturation* correlate :math:`s`.

885

886 Examples

887 --------

888 >>> M = 0.0387637282462

889 >>> Q = 55.8523226578

890 >>> saturation_correlate(M, Q) # doctest: +ELLIPSIS

891 0.0694039...

892 """

893

894 M = as_float_array(M)

895 Q = as_float_array(Q)

896

897 with sdiv_mode():

898 return 100 * sdiv(M, Q)

899

900

901 def 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`.

908

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.

917

918 Returns

919 -------

920 :class:`numpy.ndarray`

921 Points :math:`P'` as an array containing :math:`P'_1` and

922 :math:`P'_2`.

923

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 """

932

933 N_c = as_float_array(N_c)

934 e_t = as_float_array(e_t)

935 A = as_float_array(A)

936

937 P_p_1 = 43 * N_c * e_t

938 P_p_2 = A

939

940 return tstack([P_p_1, P_p_2])

941

942

943 def hue_angle_dependency_Hellwig2022(

944 h: ArrayLike,

945) -> NDArrayFloat:

946 """

947 Compute the hue angle dependency of the *Helmholtz-Kohlrausch* effect.

948

949 Parameters

950 ----------

951 h

952 Hue :math:`h` angle in degrees.

953

954 Returns

955 -------

956 :class:`numpy.ndarray`

957 Hue angle dependency of the *Helmholtz-Kohlrausch* effect.

958

959 References

960 ----------

961 :cite:`Hellwig2022a`

962

963 Examples

964 --------

965 >>> hue_angle_dependency_Hellwig2022(217.06795976739301)

966 ... # doctest: +ELLIPSIS

967 1.2768219...

968 """

969

970 h = as_float_array(h)

971

972 h_r = np.radians(h)

973

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 )