Coverage for difference/stress.py: 36%

1"""

2 Standardized Residual Sum of Squares (STRESS) Index

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

4

5 Define the *Kruskal's Standardized Residual Sum of Squares (:math:`STRESS`)*

6 index:

7

8- :func:`colour.index_stress_Garcia2007`: :math:`STRESS` index computation

9 according to *García, Huertas, Melgosa and Cui (2007)* method.

10- :func:`colour.index_stress`: *lightness* :math:`STRESS` index computation

11 using the specified method.

12

13 References

14----------

15- :cite:`Garcia2007` : García, P. A., Huertas, R., Melgosa, M., & Cui, G.

16 (2007). Measurement of the relationship between perceived and computed

17 color differences. Journal of the Optical Society of America A, 24(7),

18 1823. doi:10.1364/JOSAA.24.001823

19"""

20

21 from __future__ import annotations

22

23 import typing

24

25 import numpy as np

26

27 from colour.algebra import sdiv, sdiv_mode

28

29 if typing.TYPE_CHECKING:

30 from colour.hints import ArrayLike, Literal, NDArrayFloat

31

32 from colour.utilities import CanonicalMapping, as_float, as_float_array, validate_method

33

34 __author__ = "Colour Developers"

35 __copyright__ = "Copyright 2013 Colour Developers"

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

37 __maintainer__ = "Colour Developers"

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

39 __status__ = "Production"

40

41 __all__ = [

42 "index_stress_Garcia2007",

43 "INDEX_STRESS_METHODS",

44 "index_stress",

45]

46

47

48 def index_stress_Garcia2007(d_E: ArrayLike, d_V: ArrayLike) -> NDArrayFloat:

49 """

50 Compute the *Kruskal's Standardized Residual Sum of Squares

51 (:math:`STRESS`)* index according to the *García, Huertas, Melgosa and

52 Cui (2007)* method.

53

54 Parameters

55 ----------

56 d_E

57 Computed colour difference array :math:`\\Delta E`.

58 d_V

59 Computed colour difference array :math:`\\Delta V`.

60

61 Returns

62 -------

63 :class:`numpy.ndarray`

64 :math:`STRESS` index.

65

66 References

67 ----------

68 :cite:`Garcia2007`

69

70 Examples

71 --------

72 >>> d_E = np.array([2.0425, 2.8615, 3.4412])

73 >>> d_V = np.array([1.2644, 1.2630, 1.8731])

74 >>> index_stress_Garcia2007(d_E, d_V) # doctest: +ELLIPSIS

75 0.1211709...

76 """

77

78 d_E = as_float_array(d_E)

79 d_V = as_float_array(d_V)

80

81 with sdiv_mode():

82 F_1 = sdiv(np.sum(d_E**2), np.sum(d_E * d_V))

83

84 stress = np.sqrt(sdiv(np.sum((d_E - F_1 * d_V) ** 2), np.sum(F_1**2 * d_V**2)))

85

86 return as_float(stress)

87

88

89 INDEX_STRESS_METHODS: CanonicalMapping = CanonicalMapping(

90 {

91 "Garcia 2007": index_stress_Garcia2007,

92 }

93)

94 INDEX_STRESS_METHODS.__doc__ = """

95 Supported *Standardized Residual Sum of Squares* (*STRESS*) index

96 computation methods.

97

98 References

99----------

100:cite:`Garcia2007`

101"""

102

103

104 def index_stress(

105 d_E: ArrayLike,

106 d_V: ArrayLike,

107 method: Literal["Garcia 2007"] | str = "Garcia 2007",

108) -> NDArrayFloat:

109 """

110 Compute *Kruskal's Standardized Residual Sum of Squares*

111 (:math:`STRESS`) index using the specified method

112

113 Parameters

114 ----------

115 d_E

116 Computed colour difference array :math:`\\Delta E`.

117 d_V

118 Computed colour difference array :math:`\\Delta V`.

119 method

120 Computation method.

121

122 Returns

123 -------

124 :class:`numpy.ndarray`

125 :math:`STRESS` index.

126

127 References

128 ----------

129 :cite:`Garcia2007`

130

131 Examples

132 --------

133 >>> d_E = np.array([2.0425, 2.8615, 3.4412])

134 >>> d_V = np.array([1.2644, 1.2630, 1.8731])

135 >>> index_stress(d_E, d_V) # doctest: +ELLIPSIS

136 0.1211709...

137 """

138

139 method = validate_method(method, tuple(INDEX_STRESS_METHODS))

140

141 function = INDEX_STRESS_METHODS[method]

142

143 return function(d_E, d_V)