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

1""" 

2Photometry 

3========== 

4 

5Define photometric quantities computation objects. 

6 

7References 

8---------- 

9- :cite:`Wikipedia2003b` : Wikipedia. (2003). Luminosity function. Retrieved 

10 October 20, 2014, from 

11 https://en.wikipedia.org/wiki/Luminosity_function#Details 

12- :cite:`Wikipedia2005c` : Wikipedia. (2005). Luminous Efficacy. Retrieved 

13 April 3, 2016, from https://en.wikipedia.org/wiki/Luminous_efficacy 

14""" 

15 

16from __future__ import annotations 

17 

18import numpy as np 

19 

20from colour.colorimetry import SDS_LEFS_PHOTOPIC, SpectralDistribution, reshape_sd 

21from colour.constants import CONSTANT_K_M 

22from colour.utilities import as_float_scalar, optional 

23 

24__author__ = "Colour Developers" 

25__copyright__ = "Copyright 2013 Colour Developers" 

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

27__maintainer__ = "Colour Developers" 

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

29__status__ = "Production" 

30 

31__all__ = [ 

32 "luminous_flux", 

33 "luminous_efficiency", 

34 "luminous_efficacy", 

35] 

36 

37 

38def luminous_flux( 

39 sd: SpectralDistribution, 

40 lef: SpectralDistribution | None = None, 

41 K_m: float = CONSTANT_K_M, 

42) -> float: 

43 """ 

44 Compute the *luminous flux* for the specified spectral distribution 

45 using the specified *luminous efficiency* function. 

46 

47 Parameters 

48 ---------- 

49 sd 

50 Spectral distribution to compute the *luminous flux* for. 

51 lef 

52 :math:`V(\\lambda)` *luminous efficiency* function, defaults to the 

53 *CIE 1924 Photopic Standard Observer*. 

54 K_m 

55 :math:`lm\\cdot W^{-1}` maximum photopic luminous efficacy. 

56 

57 Returns 

58 ------- 

59 :class:`float` 

60 *Luminous flux* in lumens. 

61 

62 References 

63 ---------- 

64 :cite:`Wikipedia2003b` 

65 

66 Examples 

67 -------- 

68 >>> from colour import SDS_LIGHT_SOURCES 

69 >>> sd = SDS_LIGHT_SOURCES["Neodimium Incandescent"] 

70 >>> luminous_flux(sd) # doctest: +ELLIPSIS 

71 23807.6555273... 

72 """ 

73 

74 lef = optional(lef, SDS_LEFS_PHOTOPIC["CIE 1924 Photopic Standard Observer"]) 

75 

76 lef = reshape_sd( 

77 lef, 

78 sd.shape, 

79 copy=False, 

80 extrapolator_kwargs={"method": "Constant", "left": 0, "right": 0}, 

81 ) 

82 

83 flux = K_m * np.trapezoid(lef.values * sd.values, sd.wavelengths) 

84 

85 return as_float_scalar(flux) 

86 

87 

88def luminous_efficiency( 

89 sd: SpectralDistribution, lef: SpectralDistribution | None = None 

90) -> float: 

91 """ 

92 Compute the *luminous efficiency* of the specified spectral distribution using 

93 specified luminous efficiency function. 

94 

95 The *luminous efficiency* quantifies the ratio of *luminous flux* to 

96 *radiant flux* for a light source, representing how efficiently radiant 

97 energy is converted to luminous energy as perceived by the human visual 

98 system. 

99 

100 Parameters 

101 ---------- 

102 sd 

103 Test spectral distribution to evaluate. 

104 lef 

105 :math:`V(\\lambda)` *luminous efficiency* function, defaults to the 

106 *CIE 1924 Photopic Standard Observer*. 

107 

108 Returns 

109 ------- 

110 :class:`float` 

111 *Luminous efficiency*. 

112 

113 References 

114 ---------- 

115 :cite:`Wikipedia2003b` 

116 

117 Examples 

118 -------- 

119 >>> from colour import SDS_LIGHT_SOURCES 

120 >>> sd = SDS_LIGHT_SOURCES["Neodimium Incandescent"] 

121 >>> luminous_efficiency(sd) # doctest: +ELLIPSIS 

122 0.1994393... 

123 """ 

124 

125 lef = optional(lef, SDS_LEFS_PHOTOPIC["CIE 1924 Photopic Standard Observer"]) 

126 

127 lef = reshape_sd( 

128 lef, 

129 sd.shape, 

130 copy=False, 

131 extrapolator_kwargs={"method": "Constant", "left": 0, "right": 0}, 

132 ) 

133 

134 efficiency = np.trapezoid(lef.values * sd.values, sd.wavelengths) / np.trapezoid( 

135 sd.values, sd.wavelengths 

136 ) 

137 

138 return as_float_scalar(efficiency) 

139 

140 

141def luminous_efficacy( 

142 sd: SpectralDistribution, lef: SpectralDistribution | None = None 

143) -> float: 

144 """ 

145 Compute the *luminous efficacy* in :math:`lm\\cdot W^{-1}` of the 

146 specified spectral distribution using the specified *luminous efficiency* 

147 function. 

148 

149 *Luminous efficacy* quantifies how effectively a light source converts 

150 radiant power into *luminous flux* as perceived by the human visual 

151 system. 

152 

153 Parameters 

154 ---------- 

155 sd 

156 Test spectral distribution to evaluate. 

157 lef 

158 :math:`V(\\lambda)` *luminous efficiency* function, defaults to the 

159 *CIE 1924 Photopic Standard Observer*. 

160 

161 Returns 

162 ------- 

163 :class:`float` 

164 *Luminous efficacy* in :math:`lm\\cdot W^{-1}`. 

165 

166 References 

167 ---------- 

168 :cite:`Wikipedia2005c` 

169 

170 Examples 

171 -------- 

172 >>> from colour import SDS_LIGHT_SOURCES 

173 >>> sd = SDS_LIGHT_SOURCES["Neodimium Incandescent"] 

174 >>> luminous_efficacy(sd) # doctest: +ELLIPSIS 

175 136.2170803... 

176 """ 

177 

178 efficacy = CONSTANT_K_M * luminous_efficiency(sd, lef) 

179 

180 return as_float_scalar(efficacy)