"""
Photometry
==========
Define photometric quantities computation objects.
References
----------
- :cite:`Wikipedia2003b` : Wikipedia. (2003). Luminosity function. Retrieved
October 20, 2014, from
https://en.wikipedia.org/wiki/Luminosity_function#Details
- :cite:`Wikipedia2005c` : Wikipedia. (2005). Luminous Efficacy. Retrieved
April 3, 2016, from https://en.wikipedia.org/wiki/Luminous_efficacy
"""
from __future__ import annotations
from colour.colorimetry import SDS_LEFS_PHOTOPIC, SpectralDistribution, reshape_sd
from colour.constants import CONSTANT_K_M
from colour.utilities import (
array_namespace,
as_float_scalar,
optional,
xp_as_float_array,
xp_trapezoid,
)
__author__ = "Colour Developers"
__copyright__ = "Copyright 2013 Colour Developers"
__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
__maintainer__ = "Colour Developers"
__email__ = "colour-developers@colour-science.org"
__status__ = "Production"
__all__ = [
"luminous_flux",
"luminous_efficiency",
"luminous_efficacy",
]
[docs]
def luminous_flux(
sd: SpectralDistribution,
lef: SpectralDistribution | None = None,
K_m: float = CONSTANT_K_M,
) -> float:
"""
Compute the *luminous flux* for the specified spectral distribution
using the specified *luminous efficiency* function.
Parameters
----------
sd
Spectral distribution to compute the *luminous flux* for.
lef
:math:`V(\\lambda)` *luminous efficiency* function, defaults to the
*CIE 1924 Photopic Standard Observer*.
K_m
:math:`lm\\cdot W^{-1}` maximum photopic luminous efficacy.
Returns
-------
:class:`float`
*Luminous flux* in lumens.
References
----------
:cite:`Wikipedia2003b`
Examples
--------
>>> from colour import SDS_LIGHT_SOURCES
>>> sd = SDS_LIGHT_SOURCES["Neodimium Incandescent"]
>>> luminous_flux(sd) # doctest: +ELLIPSIS
np.float64(23807.6555273...)
"""
lef = optional(lef, SDS_LEFS_PHOTOPIC["CIE 1924 Photopic Standard Observer"])
lef = reshape_sd(
lef,
sd.shape,
copy=False,
extrapolator_kwargs={"method": "Constant", "left": 0, "right": 0},
)
xp = array_namespace(sd.values)
sd_values = xp_as_float_array(sd.values, xp=xp)
lef_values = xp_as_float_array(lef.values, xp=xp, like=sd_values)
flux = K_m * xp_trapezoid(lef_values * sd_values, x=sd.wavelengths, xp=xp)
return as_float_scalar(flux)
[docs]
def luminous_efficiency(
sd: SpectralDistribution, lef: SpectralDistribution | None = None
) -> float:
"""
Compute the *luminous efficiency* of the specified spectral distribution using
specified luminous efficiency function.
The *luminous efficiency* quantifies the ratio of *luminous flux* to
*radiant flux* for a light source, representing how efficiently radiant
energy is converted to luminous energy as perceived by the human visual
system.
Parameters
----------
sd
Test spectral distribution to evaluate.
lef
:math:`V(\\lambda)` *luminous efficiency* function, defaults to the
*CIE 1924 Photopic Standard Observer*.
Returns
-------
:class:`float`
*Luminous efficiency*.
References
----------
:cite:`Wikipedia2003b`
Examples
--------
>>> from colour import SDS_LIGHT_SOURCES
>>> sd = SDS_LIGHT_SOURCES["Neodimium Incandescent"]
>>> luminous_efficiency(sd) # doctest: +ELLIPSIS
np.float64(0.1994393...)
"""
lef = optional(lef, SDS_LEFS_PHOTOPIC["CIE 1924 Photopic Standard Observer"])
lef = reshape_sd(
lef,
sd.shape,
copy=False,
extrapolator_kwargs={"method": "Constant", "left": 0, "right": 0},
)
xp = array_namespace(sd.values)
sd_values = xp_as_float_array(sd.values, xp=xp)
lef_values = xp_as_float_array(lef.values, xp=xp, like=sd_values)
efficiency = xp_trapezoid(
lef_values * sd_values, x=sd.wavelengths, xp=xp
) / xp_trapezoid(sd_values, x=sd.wavelengths, xp=xp)
return as_float_scalar(efficiency)
[docs]
def luminous_efficacy(
sd: SpectralDistribution, lef: SpectralDistribution | None = None
) -> float:
"""
Compute the *luminous efficacy* in :math:`lm\\cdot W^{-1}` of the
specified spectral distribution using the specified *luminous efficiency*
function.
*Luminous efficacy* quantifies how effectively a light source converts
radiant power into *luminous flux* as perceived by the human visual
system.
Parameters
----------
sd
Test spectral distribution to evaluate.
lef
:math:`V(\\lambda)` *luminous efficiency* function, defaults to the
*CIE 1924 Photopic Standard Observer*.
Returns
-------
:class:`float`
*Luminous efficacy* in :math:`lm\\cdot W^{-1}`.
References
----------
:cite:`Wikipedia2005c`
Examples
--------
>>> from colour import SDS_LIGHT_SOURCES
>>> sd = SDS_LIGHT_SOURCES["Neodimium Incandescent"]
>>> luminous_efficacy(sd) # doctest: +ELLIPSIS
np.float64(136.2170803...)
"""
efficacy = CONSTANT_K_M * luminous_efficiency(sd, lef)
return as_float_scalar(efficacy)
