Coverage for colorimetry/correction.py: 32%

1"""

2 Spectral Bandpass Dependence Correction

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

4

5 Define objects to perform spectral bandpass dependence correction.

6

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

17 References

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

27 from __future__ import annotations

28

29 import typing

30

31 if typing.TYPE_CHECKING:

32 from colour.colorimetry import SpectralDistribution

33 from colour.hints import Literal

34

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

50 CONSTANT_ALPHA_STEARNS: float = 0.083

51

52

53 def 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

116 BANDPASS_CORRECTION_METHODS: CanonicalMapping = CanonicalMapping(

117 {"Stearns 1988": bandpass_correction_Stearns1988}

118)

119 BANDPASS_CORRECTION_METHODS.__doc__ = """

120 Supported spectral bandpass dependence correction methods.

121"""

122

123

124 def 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)