Source code for colour.colorimetry.photometry
"""
Photometry
==========
Define the photometric quantities computation related 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
import numpy as np
from colour.colorimetry import (
SDS_LEFS_PHOTOPIC,
SpectralDistribution,
reshape_sd,
)
from colour.constants import CONSTANT_K_M
from colour.utilities import as_float_scalar, optional
__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:
"""
Return the *luminous flux* for given spectral distribution using given
luminous efficiency function.
Parameters
----------
sd
test spectral distribution
lef
:math:`V(\\lambda)` luminous efficiency function, default to the
*CIE 1924 Photopic Standard Observer*.
K_m
:math:`lm\\cdot W^{-1}` maximum photopic luminous efficiency.
Returns
-------
:class:`float`
Luminous flux.
References
----------
:cite:`Wikipedia2003b`
Examples
--------
>>> from colour import SDS_LIGHT_SOURCES
>>> sd = SDS_LIGHT_SOURCES["Neodimium Incandescent"]
>>> luminous_flux(sd) # doctest: +ELLIPSIS
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},
)
flux = K_m * np.trapezoid(lef.values * sd.values, sd.wavelengths) # pyright: ignore
return as_float_scalar(flux)
[docs]
def luminous_efficiency(
sd: SpectralDistribution, lef: SpectralDistribution | None = None
) -> float:
"""
Return the *luminous efficiency* of given spectral distribution using
given luminous efficiency function.
Parameters
----------
sd
test spectral distribution
lef
:math:`V(\\lambda)` luminous efficiency function, default 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
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},
)
efficiency = np.trapezoid( # pyright: ignore
lef.values * sd.values, sd.wavelengths
) / np.trapezoid( # pyright: ignore
sd.values, sd.wavelengths
)
return as_float_scalar(efficiency)
[docs]
def luminous_efficacy(
sd: SpectralDistribution, lef: SpectralDistribution | None = None
) -> float:
"""
Return the *luminous efficacy* in :math:`lm\\cdot W^{-1}` of given
spectral distribution using given luminous efficiency function.
Parameters
----------
sd
test spectral distribution
lef
:math:`V(\\lambda)` luminous efficiency function, default 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
136.2170803...
"""
efficacy = CONSTANT_K_M * luminous_efficiency(sd, lef)
return as_float_scalar(efficacy)
