Coverage for contrast/__init__.py: 25%

1"""

2 References

3----------

4- :cite:`Barten1999` : Barten, P. G. (1999). Contrast Sensitivity of the

5 Human Eye and Its Effects on Image Quality. SPIE. doi:10.1117/3.353254

6- :cite:`Barten2003` : Barten, P. G. J. (2003). Formula for the contrast

7 sensitivity of the human eye. In Y. Miyake & D. R. Rasmussen (Eds.),

8 Proceedings of SPIE (Vol. 5294, pp. 231-238). doi:10.1117/12.537476

9- :cite:`Cowan2004` : Cowan, M., Kennel, G., Maier, T., & Walker, B. (2004).

10 Contrast Sensitivity Experiment to Determine the Bit Depth for Digital

11 Cinema. SMPTE Motion Imaging Journal, 113(9), 281-292. doi:10.5594/j11549

12- :cite:`InternationalTelecommunicationUnion2015` : International

13 Telecommunication Union. (2015). Report ITU-R BT.2246-4 - The present

14 state of ultra-high definition television BT Series Broadcasting service

15 (Vol. 5, pp. 1-92).

16 https://www.itu.int/dms_pub/itu-r/opb/rep/R-REP-BT.2246-4-2015-PDF-E.pdf

17"""

18

19 from __future__ import annotations

20

21 import typing

22

23 if typing.TYPE_CHECKING:

24 from colour.hints import Any, NDArrayFloat, Literal

25

26 from colour.utilities import (

27 CanonicalMapping,

28 filter_kwargs,

29 validate_method,

30)

31

32 from .barten1999 import (

33 contrast_sensitivity_function_Barten1999,

34 maximum_angular_size_Barten1999,

35 optical_MTF_Barten1999,

36 pupil_diameter_Barten1999,

37 retinal_illuminance_Barten1999,

38 sigma_Barten1999,

39)

40

41 __all__ = [

42 "contrast_sensitivity_function_Barten1999",

43 "maximum_angular_size_Barten1999",

44 "optical_MTF_Barten1999",

45 "pupil_diameter_Barten1999",

46 "retinal_illuminance_Barten1999",

47 "sigma_Barten1999",

48]

49

50 CONTRAST_SENSITIVITY_METHODS: CanonicalMapping = CanonicalMapping(

51 {

52 "Barten 1999": contrast_sensitivity_function_Barten1999,

53 }

54)

55 CONTRAST_SENSITIVITY_METHODS.__doc__ = """

56 Supported contrast sensitivity function computation methods.

57

58 References

59----------

60:cite:`Barten1999`, :cite:`Barten2003`, :cite:`Cowan2004`,

61:cite:`InternationalTelecommunicationUnion2015`,

62"""

63

64

65 def contrast_sensitivity_function(

66 method: Literal["Barten 1999"] | str = "Barten 1999", **kwargs: Any

67) -> NDArrayFloat:

68 """

69 Compute the contrast sensitivity :math:`S` of the human eye.

70

71 Parameters

72 ----------

73 method

74 Computation method.

75

76 Other Parameters

77 ----------------

78 E

79 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

80 Retinal illuminance :math:`E` in Trolands.

81 k

82 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

83 Signal-to-noise (SNR) ratio :math:`k`.

84 n

85 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

86 Quantum efficiency of the eye :math:`n`.

87 N_max

88 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

89 Maximum number of cycles :math:`N_{max}` over which the eye can

90 integrate the information.

91 p

92 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

93 Photon conversion factor :math:`p` in

94 :math:`photons\\div seconds\\div degrees^2\\div Trolands` that

95 depends on the light source.

96 phi_0

97 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

98 Spectral density :math:`\\phi_0` in :math:`seconds degrees^2` of the

99 neural noise.

100 sigma

101 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

102 Standard deviation :math:`\\sigma` of the line-spread function

103 resulting from the convolution of the different elements of the

104 convolution process.

105 T

106 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

107 Integration time :math:`T` in seconds of the eye.

108 u

109 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

110 Spatial frequency :math:`u`, the cycles per degree.

111 u_0

112 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

113 Spatial frequency :math:`u_0` in :math:`cycles\\div degrees` above

114 which the lateral inhibition ceases.

115 X_0

116 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

117 Angular size :math:`X_0` in degrees of the object in the x direction.

118 Y_0

119 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

120 Angular size :math:`Y_0` in degrees of the object in the y direction.

121 X_max

122 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

123 Maximum angular size :math:`X_{max}` in degrees of the integration

124 area in the x direction.

125 Y_max

126 {:func:`colour.contrast.contrast_sensitivity_function_Barten1999`},

127 Maximum angular size :math:`Y_{max}` in degrees of the integration

128 area in the y direction.

129

130 Returns

131 -------

132 :class:`numpy.ndarray`

133 Contrast sensitivity :math:`S`.

134

135 References

136 ----------

137 :cite:`Barten1999`, :cite:`Barten2003`, :cite:`Cowan2004`,

138 :cite:`InternationalTelecommunicationUnion2015`,

139

140 Examples

141 --------

142 >>> contrast_sensitivity_function(u=4) # doctest: +ELLIPSIS

143 360.8691122...

144 >>> contrast_sensitivity_function("Barten 1999", u=4) # doctest: +ELLIPSIS

145 360.8691122...

146 """

147

148 method = validate_method(method, tuple(CONTRAST_SENSITIVITY_METHODS))

149

150 function = CONTRAST_SENSITIVITY_METHODS[method]

151

152 return function(**filter_kwargs(function, **kwargs))

153

154

155 __all__ += [

156 "CONTRAST_SENSITIVITY_METHODS",

157 "contrast_sensitivity_function",

158]