Coverage for colour/colorimetry/correction.py: 100%

1""" 

2Spectral Bandpass Dependence Correction 

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

4 

5Define objects to perform spectral bandpass dependence correction. 

6 

7The following correction methods are available: 

8 

9- :func:`colour.colorimetry.bandpass_correction_Stearns1988`: 

10 *Stearns and Stearns (1988)* spectral bandpass dependence correction 

11 method. 

12- :attr:`colour.BANDPASS_CORRECTION_METHODS`: Supported spectral bandpass 

13 dependence correction methods. 

14- :func:`colour.bandpass_correction`: Spectral bandpass dependence 

15 correction using the specified method. 

16 

17References 

18---------- 

19- :cite:`Stearns1988a` : Stearns, E. I., & Stearns, R. E. (1988). An example 

20 of a method for correcting radiance data for Bandpass error. Color Research 

21 & Application, 13(4), 257-259. doi:10.1002/col.5080130410 

22- :cite:`Westland2012f` : Westland, S., Ripamonti, C., & Cheung, V. (2012). 

23 Correction for Spectral Bandpass. In Computational Colour Science Using 

24 MATLAB (2nd ed., p. 38). ISBN:978-0-470-66569-5 

25""" 

26 

27from __future__ import annotations 

28 

29import typing 

30 

31if typing.TYPE_CHECKING: 

32 from colour.colorimetry import SpectralDistribution 

33 from colour.hints import Literal 

34 

35from colour.utilities import CanonicalMapping, validate_method 

36 

37__author__ = "Colour Developers" 

38__copyright__ = "Copyright 2013 Colour Developers" 

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

40__maintainer__ = "Colour Developers" 

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

42__status__ = "Production" 

43 

44__all__ = [ 

45 "bandpass_correction_Stearns1988", 

46 "BANDPASS_CORRECTION_METHODS", 

47 "bandpass_correction", 

48] 

49 

50CONSTANT_ALPHA_STEARNS: float = 0.083 

51 

52 

53def bandpass_correction_Stearns1988( 

54 sd: SpectralDistribution, 

55) -> SpectralDistribution: 

56 """ 

57 Apply spectral bandpass dependence correction to the specified spectral 

58 distribution using *Stearns and Stearns (1988)* method. 

59 

60 Parameters 

61 ---------- 

62 sd 

63 Spectral distribution. 

64 

65 Returns 

66 ------- 

67 :class:`colour.SpectralDistribution` 

68 Spectral bandpass dependence corrected spectral distribution. 

69 

70 References 

71 ---------- 

72 :cite:`Stearns1988a`, :cite:`Westland2012f` 

73 

74 Examples 

75 -------- 

76 >>> from colour import SpectralDistribution 

77 >>> from colour.utilities import numpy_print_options 

78 >>> data = { 

79 ... 500: 0.0651, 

80 ... 520: 0.0705, 

81 ... 540: 0.0772, 

82 ... 560: 0.0870, 

83 ... 580: 0.1128, 

84 ... 600: 0.1360, 

85 ... } 

86 >>> with numpy_print_options(suppress=True): 

87 ... bandpass_correction_Stearns1988(SpectralDistribution(data)) 

88 ... # doctest: +ELLIPSIS 

89 SpectralDistribution([[ 500. , 0.0646518...], 

90 [ 520. , 0.0704293...], 

91 [ 540. , 0.0769485...], 

92 [ 560. , 0.0856928...], 

93 [ 580. , 0.1129644...], 

94 [ 600. , 0.1379256...]], 

95 SpragueInterpolator, 

96 {}, 

97 Extrapolator, 

98 {'method': 'Constant', 'left': None, 'right': None}) 

99 """ 

100 

101 A_S = CONSTANT_ALPHA_STEARNS 

102 values = sd.values 

103 

104 values[0] = (1 + A_S) * values[0] - A_S * values[1] 

105 values[-1] = (1 + A_S) * values[-1] - A_S * values[-2] 

106 for i in range(1, len(values) - 1): 

107 values[i] = ( 

108 -A_S * values[i - 1] + (1 + 2 * A_S) * values[i] - A_S * values[i + 1] 

109 ) 

110 

111 sd.values = values 

112 

113 return sd 

114 

115 

116BANDPASS_CORRECTION_METHODS: CanonicalMapping = CanonicalMapping( 

117 {"Stearns 1988": bandpass_correction_Stearns1988} 

118) 

119BANDPASS_CORRECTION_METHODS.__doc__ = """ 

120Supported spectral bandpass dependence correction methods. 

121""" 

122 

123 

124def bandpass_correction( 

125 sd: SpectralDistribution, 

126 method: Literal["Stearns 1988"] | str = "Stearns 1988", 

127) -> SpectralDistribution: 

128 """ 

129 Apply spectral bandpass dependence correction to the specified spectral 

130 distribution. 

131 

132 Correct for the systematic errors introduced by finite bandpass 

133 measurements in spectrophotometry. The correction compensates for the 

134 deviation between the measured spectral values and the true spectral 

135 values that would be obtained with infinitesimal bandpass width. 

136 

137 Parameters 

138 ---------- 

139 sd 

140 Spectral distribution requiring bandpass correction. 

141 method 

142 Bandpass correction method to apply. 

143 

144 Returns 

145 ------- 

146 :class:`colour.SpectralDistribution` 

147 Spectral distribution with bandpass dependence correction applied, 

148 preserving the original wavelength sampling. 

149 

150 References 

151 ---------- 

152 :cite:`Stearns1988a`, :cite:`Westland2012f` 

153 

154 Examples 

155 -------- 

156 >>> from colour import SpectralDistribution 

157 >>> from colour.utilities import numpy_print_options 

158 >>> data = { 

159 ... 500: 0.0651, 

160 ... 520: 0.0705, 

161 ... 540: 0.0772, 

162 ... 560: 0.0870, 

163 ... 580: 0.1128, 

164 ... 600: 0.1360, 

165 ... } 

166 >>> with numpy_print_options(suppress=True): 

167 ... bandpass_correction(SpectralDistribution(data)) 

168 ... # doctest: +ELLIPSIS 

169 SpectralDistribution([[ 500. , 0.0646518...], 

170 [ 520. , 0.0704293...], 

171 [ 540. , 0.0769485...], 

172 [ 560. , 0.0856928...], 

173 [ 580. , 0.1129644...], 

174 [ 600. , 0.1379256...]], 

175 SpragueInterpolator, 

176 {}, 

177 Extrapolator, 

178 {'method': 'Constant', 'left': None, 'right': None}) 

179 """ 

180 

181 method = validate_method(method, tuple(BANDPASS_CORRECTION_METHODS)) 

182 

183 return BANDPASS_CORRECTION_METHODS[method](sd)