Coverage for colorimetry/photometry.py: 40%

1"""

2 Photometry

3==========

4

5 Define photometric quantities computation objects.

6

7 References

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

16 from __future__ import annotations

17

18 import numpy as np

19

20 from colour.colorimetry import SDS_LEFS_PHOTOPIC, SpectralDistribution, reshape_sd

21 from colour.constants import CONSTANT_K_M

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

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

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

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