Coverage for colour/contrast/__init__.py: 100%

1""" 

2References 

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 

19from __future__ import annotations 

20 

21import typing 

22 

23if typing.TYPE_CHECKING: 

24 from colour.hints import Any, NDArrayFloat, Literal 

25 

26from colour.utilities import ( 

27 CanonicalMapping, 

28 filter_kwargs, 

29 validate_method, 

30) 

31 

32from .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 

50CONTRAST_SENSITIVITY_METHODS: CanonicalMapping = CanonicalMapping( 

51 { 

52 "Barten 1999": contrast_sensitivity_function_Barten1999, 

53 } 

54) 

55CONTRAST_SENSITIVITY_METHODS.__doc__ = """ 

56Supported contrast sensitivity function computation methods. 

57 

58References 

59---------- 

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

61:cite:`InternationalTelecommunicationUnion2015`, 

62""" 

63 

64 

65def 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]