colour.SpectralDistribution#

class colour.SpectralDistribution(data: TypeAliasForwardRef('ArrayLike') | dict | Series | Signal | ValuesView | None = None, domain: TypeAliasForwardRef('ArrayLike') | SpectralShape | KeysView | None = None, **kwargs: Any)[source]#

Bases: Signal

Define the spectral distribution: the base object for spectral computations.

Initialise spectral distribution according to CIE 15:2004 recommendation: use the method developed by Sprague (1880) for interpolating functions having uniformly spaced independent variables and the Cubic Spline method for non-uniformly spaced independent variables. Perform extrapolation according to CIE 167:2005 recommendation.

Important

Specific documentation about getting, setting, indexing and slicing the spectral power distribution values is available in the Spectral Representation and Continuous Signal section.

Parameters:

  • data (ArrayLike | dict | Series | Signal | ValuesView | None) – Data to be stored in the spectral distribution.

  • domain (ArrayLike | SpectralShape | KeysView | None) – Values to initialise the colour.SpectralDistribution.wavelength property with. If both data and domain arguments are defined, the latter will be used to initialise the colour.SpectralDistribution.wavelength property.

  • extrapolator – Extrapolator class type to use as extrapolating function.

  • extrapolator_kwargs – Arguments to use when instantiating the extrapolating function.

  • interpolator – Interpolator class type to use as interpolating function.

  • interpolator_kwargs – Arguments to use when instantiating the interpolating function.

  • name – Spectral distribution name.

  • display_name – Spectral distribution name for figures, default to colour.SpectralDistribution.name property value.

  • kwargs (Any)

Warning

The Cubic Spline method might produce unexpected results with exceptionally noisy or non-uniformly spaced data.

Attributes

Methods

References

[CIET13805a], [CIET13805d], [CIET14804c]

Examples

Instantiating a spectral distribution with a uniformly spaced independent variable:

>>> from colour.utilities import numpy_print_options
>>> data = {
...     500: 0.0651,
...     520: 0.0705,
...     540: 0.0772,
...     560: 0.0870,
...     580: 0.1128,
...     600: 0.1360,
... }
>>> with numpy_print_options(suppress=True):
...     SpectralDistribution(data)
SpectralDistribution([[500.    ,   0.0651],
                      [520.    ,   0.0705],
                      [540.    ,   0.0772],
                      [560.    ,   0.087 ],
                      [580.    ,   0.1128],
                      [600.    ,   0.136 ]],
                     SpragueInterpolator,
                     {},
                     Extrapolator,
                     {'method': 'Constant', 'left': None, 'right': None})

Instantiating a spectral distribution with a non-uniformly spaced independent variable:

>>> data[510] = 0.31416
>>> with numpy_print_options(suppress=True):
...     SpectralDistribution(data)
SpectralDistribution([[500.     ,   0.0651 ],
                      [510.     ,   0.31416],
                      [520.     ,   0.0705 ],
                      [540.     ,   0.0772 ],
                      [560.     ,   0.087  ],
                      [580.     ,   0.1128 ],
                      [600.     ,   0.136  ]],
                     CubicSplineInterpolator,
                     {},
                     Extrapolator,
                     {'method': 'Constant', 'left': None, 'right': None})

Instantiation with a Pandas pandas.Series:

>>> from colour.utilities import is_pandas_installed
>>> if is_pandas_installed():
...     from pandas import Series
...
...     print(SpectralDistribution(Series(data)))
[[  5.0000000...e+02   6.5100000...e-02]
 [  5.2000000...e+02   7.0500000...e-02]
 [  5.4000000...e+02   7.7200000...e-02]
 [  5.6000000...e+02   8.7000000...e-02]
 [  5.8000000...e+02   1.1280000...e-01]
 [  6.0000000...e+02   1.3600000...e-01]
 [  5.1000000...e+02   3.1416000...e-01]]
__init__(data: TypeAliasForwardRef('ArrayLike') | dict | Series | Signal | ValuesView | None = None, domain: TypeAliasForwardRef('ArrayLike') | SpectralShape | KeysView | None = None, **kwargs: Any) → None[source]#
Parameters:
Return type:

None

property display_name: str#

Getter and setter for the spectral distribution’s display name.

The display name provides a human-readable identifier for the spectral distribution, used for visualization and reporting purposes.

Parameters:

value – Value to set the spectral distribution’s display name with.

Returns:

Spectral distribution’s display name.

Return type:

str

property wavelengths: NDArrayFloat#

Getter and setter for the spectral distribution wavelengths \(\lambda_n\).

Parameters:

value – Value to set the spectral distribution wavelengths \(\lambda_n\) with.

Returns:

Spectral distribution wavelengths \(\lambda_n\).

Return type:

numpy.ndarray

property values: NDArrayFloat#

Getter and setter for the spectral distribution values.

Parameters:

value – Value to set the spectral distribution wavelengths values with.

Returns:

Spectral distribution values.

Return type:

numpy.ndarray

property shape: SpectralShape#

Getter property for the spectral distribution shape.

Returns:

Spectral distribution shape.

Return type:

colour.SpectralShape

Notes

  • A spectral distribution with a non-uniformly spaced independent variable have multiple intervals, in that case colour.SpectralDistribution.shape property returns the minimum interval size.

Examples

Shape of a spectral distribution with a uniformly spaced independent variable:

>>> data = {
...     500: 0.0651,
...     520: 0.0705,
...     540: 0.0772,
...     560: 0.0870,
...     580: 0.1128,
...     600: 0.1360,
... }
>>> SpectralDistribution(data).shape
SpectralShape(500.0, 600.0, 20.0)

Shape of a spectral distribution with a non-uniformly spaced independent variable:

>>> data[510] = 0.31416
>>> SpectralDistribution(data).shape
SpectralShape(500.0, 600.0, 10.0)
interpolate(shape: SpectralShape, interpolator: Type[ProtocolInterpolator] | None = None, interpolator_kwargs: dict | None = None) → Self[source]#

Interpolate the spectral distribution in-place according to CIE 167:2005 recommendation (if the interpolator has not been changed at instantiation time) or specified interpolation arguments.

The logic for choosing the interpolator class when interpolator is not specified is as follows:

if self.interpolator not in (
    SpragueInterpolator,
    CubicSplineInterpolator,
):
    interpolator = self.interpolator
elif self.is_uniform():
    interpolator = SpragueInterpolator
else:
    interpolator = CubicSplineInterpolator

The logic for choosing the interpolator keyword arguments when interpolator_kwargs is not specified is as follows:

if self.interpolator not in (
    SpragueInterpolator,
    CubicSplineInterpolator,
):
    interpolator_kwargs = self.interpolator_kwargs
else:
    interpolator_kwargs = {}
Parameters:

  • shape (SpectralShape) – Spectral shape used for interpolation.

  • interpolator (Type[ProtocolInterpolator] | None) – Interpolator class type to use as interpolating function.

  • interpolator_kwargs (dict | None) – Arguments to use when instantiating the interpolating function.

Returns:

Interpolated spectral distribution.

Return type:

colour.SpectralDistribution

Notes

Warning

  • Cubic Spline interpolator requires at least 3 wavelengths \(\lambda_n\) for interpolation.

  • Sprague (1880) interpolator requires at least 6 wavelengths \(\lambda_n\) for interpolation.

References

[CIET13805a]

Examples

Spectral distribution with a uniformly spaced independent variable uses Sprague (1880) interpolation:

>>> from colour.utilities import numpy_print_options
>>> data = {
...     500: 0.0651,
...     520: 0.0705,
...     540: 0.0772,
...     560: 0.0870,
...     580: 0.1128,
...     600: 0.1360,
... }
>>> sd = SpectralDistribution(data)
>>> with numpy_print_options(suppress=True):
...     print(sd.interpolate(SpectralShape(500, 600, 1)))
...
[[500.           0.0651   ...]
 [501.           0.0653522...]
 [502.           0.0656105...]
 [503.           0.0658715...]
 [504.           0.0661328...]
 [505.           0.0663929...]
 [506.           0.0666509...]
 [507.           0.0669069...]
 [508.           0.0671613...]
 [509.           0.0674150...]
 [510.           0.0676692...]
 [511.           0.0679253...]
 [512.           0.0681848...]
 [513.           0.0684491...]
 [514.           0.0687197...]
 [515.           0.0689975...]
 [516.           0.0692832...]
 [517.           0.0695771...]
 [518.           0.0698787...]
 [519.           0.0701870...]
 [520.           0.0705   ...]
 [521.           0.0708155...]
 [522.           0.0711336...]
 [523.           0.0714547...]
 [524.           0.0717789...]
 [525.           0.0721063...]
 [526.           0.0724367...]
 [527.           0.0727698...]
 [528.           0.0731051...]
 [529.           0.0734423...]
 [530.           0.0737808...]
 [531.           0.0741203...]
 [532.           0.0744603...]
 [533.           0.0748006...]
 [534.           0.0751409...]
 [535.           0.0754813...]
 [536.           0.0758220...]
 [537.           0.0761633...]
 [538.           0.0765060...]
 [539.           0.0768511...]
 [540.           0.0772   ...]
 [541.           0.0775527...]
 [542.           0.0779042...]
 [543.           0.0782507...]
 [544.           0.0785908...]
 [545.           0.0789255...]
 [546.           0.0792576...]
 [547.           0.0795917...]
 [548.           0.0799334...]
 [549.           0.0802895...]
 [550.           0.0806671...]
 [551.           0.0810740...]
 [552.           0.0815176...]
 [553.           0.0820049...]
 [554.           0.0825423...]
 [555.           0.0831351...]
 [556.           0.0837873...]
 [557.           0.0845010...]
 [558.           0.0852763...]
 [559.           0.0861110...]
 [560.           0.087    ...]
 [561.           0.0879383...]
 [562.           0.0889300...]
 [563.           0.0899793...]
 [564.           0.0910876...]
 [565.           0.0922541...]
 [566.           0.0934760...]
 [567.           0.0947487...]
 [568.           0.0960663...]
 [569.           0.0974220...]
 [570.           0.0988081...]
 [571.           0.1002166...]
 [572.           0.1016394...]
 [573.           0.1030687...]
 [574.           0.1044972...]
 [575.           0.1059186...]
 [576.           0.1073277...]
 [577.           0.1087210...]
 [578.           0.1100968...]
 [579.           0.1114554...]
 [580.           0.1128   ...]
 [581.           0.1141333...]
 [582.           0.1154495...]
 [583.           0.1167424...]
 [584.           0.1180082...]
 [585.           0.1192452...]
 [586.           0.1204536...]
 [587.           0.1216348...]
 [588.           0.1227915...]
 [589.           0.1239274...]
 [590.           0.1250465...]
 [591.           0.1261531...]
 [592.           0.1272517...]
 [593.           0.1283460...]
 [594.           0.1294393...]
 [595.           0.1305340...]
 [596.           0.1316310...]
 [597.           0.1327297...]
 [598.           0.1338277...]
 [599.           0.1349201...]
 [600.           0.136    ...]]

Spectral distribution with a non-uniformly spaced independent variable uses Cubic Spline interpolation:

>>> sd = SpectralDistribution(data)
>>> sd[510] = np.pi / 10
>>> with numpy_print_options(suppress=True):
...     print(sd.interpolate(SpectralShape(500, 600, 1)))
...
[[500.           0.0651   ...]
 [501.           0.1365202...]
 [502.           0.1953263...]
 [503.           0.2423724...]
 [504.           0.2785126...]
 [505.           0.3046010...]
 [506.           0.3214916...]
 [507.           0.3300387...]
 [508.           0.3310962...]
 [509.           0.3255184...]
 [510.           0.3141592...]
 [511.           0.2978729...]
 [512.           0.2775135...]
 [513.           0.2539351...]
 [514.           0.2279918...]
 [515.           0.2005378...]
 [516.           0.1724271...]
 [517.           0.1445139...]
 [518.           0.1176522...]
 [519.           0.0926962...]
 [520.           0.0705   ...]
 [521.           0.0517370...]
 [522.           0.0363589...]
 [523.           0.0241365...]
 [524.           0.0148407...]
 [525.           0.0082424...]
 [526.           0.0041126...]
 [527.           0.0022222...]
 [528.           0.0023421...]
 [529.           0.0042433...]
 [530.           0.0076966...]
 [531.           0.0124729...]
 [532.           0.0183432...]
 [533.           0.0250785...]
 [534.           0.0324496...]
 [535.           0.0402274...]
 [536.           0.0481829...]
 [537.           0.0560870...]
 [538.           0.0637106...]
 [539.           0.0708246...]
 [540.           0.0772   ...]
 [541.           0.0826564...]
 [542.           0.0872086...]
 [543.           0.0909203...]
 [544.           0.0938549...]
 [545.           0.0960760...]
 [546.           0.0976472...]
 [547.           0.0986321...]
 [548.           0.0990942...]
 [549.           0.0990971...]
 [550.           0.0987043...]
 [551.           0.0979794...]
 [552.           0.0969861...]
 [553.           0.0957877...]
 [554.           0.0944480...]
 [555.           0.0930304...]
 [556.           0.0915986...]
 [557.           0.0902161...]
 [558.           0.0889464...]
 [559.           0.0878532...]
 [560.           0.087    ...]
 [561.           0.0864371...]
 [562.           0.0861623...]
 [563.           0.0861600...]
 [564.           0.0864148...]
 [565.           0.0869112...]
 [566.           0.0876336...]
 [567.           0.0885665...]
 [568.           0.0896945...]
 [569.           0.0910020...]
 [570.           0.0924735...]
 [571.           0.0940936...]
 [572.           0.0958467...]
 [573.           0.0977173...]
 [574.           0.0996899...]
 [575.           0.1017491...]
 [576.           0.1038792...]
 [577.           0.1060649...]
 [578.           0.1082906...]
 [579.           0.1105408...]
 [580.           0.1128   ...]
 [581.           0.1150526...]
 [582.           0.1172833...]
 [583.           0.1194765...]
 [584.           0.1216167...]
 [585.           0.1236884...]
 [586.           0.1256760...]
 [587.           0.1275641...]
 [588.           0.1293373...]
 [589.           0.1309798...]
 [590.           0.1324764...]
 [591.           0.1338114...]
 [592.           0.1349694...]
 [593.           0.1359349...]
 [594.           0.1366923...]
 [595.           0.1372262...]
 [596.           0.1375211...]
 [597.           0.1375614...]
 [598.           0.1373316...]
 [599.           0.1368163...]
 [600.           0.136    ...]]
extrapolate(shape: SpectralShape, extrapolator: Type[ProtocolExtrapolator] | None = None, extrapolator_kwargs: dict | None = None) → Self[source]#

Extrapolate the spectral distribution in-place according to CIE 15:2004 and CIE 167:2005 recommendations or specified extrapolation arguments.

Parameters:

  • shape (SpectralShape) – Spectral shape used for extrapolation.

  • extrapolator (Type[ProtocolExtrapolator] | None) – Extrapolator class type to use as extrapolating function.

  • extrapolator_kwargs (dict | None) – Arguments to use when instantiating the extrapolating function.

Returns:

Extrapolated spectral distribution.

Return type:

colour.SpectralDistribution

References

[CIET13805d], [CIET14804c]

Examples

>>> from colour.utilities import numpy_print_options
>>> data = {
...     500: 0.0651,
...     520: 0.0705,
...     540: 0.0772,
...     560: 0.0870,
...     580: 0.1128,
...     600: 0.1360,
... }
>>> sd = SpectralDistribution(data)
>>> sd.extrapolate(SpectralShape(400, 700, 20)).shape
SpectralShape(400.0, 700.0, 20.0)
>>> with numpy_print_options(suppress=True):
...     print(sd)
[[400.       0.0651]
 [420.       0.0651]
 [440.       0.0651]
 [460.       0.0651]
 [480.       0.0651]
 [500.       0.0651]
 [520.       0.0705]
 [540.       0.0772]
 [560.       0.087 ]
 [580.       0.1128]
 [600.       0.136 ]
 [620.       0.136 ]
 [640.       0.136 ]
 [660.       0.136 ]
 [680.       0.136 ]
 [700.       0.136 ]]
align(shape: SpectralShape, interpolator: Type[ProtocolInterpolator] | None = None, interpolator_kwargs: dict | None = None, extrapolator: Type[ProtocolExtrapolator] | None = None, extrapolator_kwargs: dict | None = None) → Self[source]#

Align the spectral distribution in-place to the specified spectral shape: Interpolate first then extrapolate to fit the specified range.

Interpolation is performed according to CIE 167:2005 recommendation (if the interpolator has not been changed at instantiation time) or specified interpolation arguments.

The logic for choosing the interpolator class when interpolator is not specified is as follows:

if self.interpolator not in (
    SpragueInterpolator,
    CubicSplineInterpolator,
):
    interpolator = self.interpolator
elif self.is_uniform():
    interpolator = SpragueInterpolator
else:
    interpolator = CubicSplineInterpolator

The logic for choosing the interpolator keyword arguments when interpolator_kwargs is not specified is as follows:

if self.interpolator not in (
    SpragueInterpolator,
    CubicSplineInterpolator,
):
    interpolator_kwargs = self.interpolator_kwargs
else:
    interpolator_kwargs = {}
Parameters:

  • shape (SpectralShape) – Spectral shape used for alignment.

  • interpolator (Type[ProtocolInterpolator] | None) – Interpolator class type to use as interpolating function.

  • interpolator_kwargs (dict | None) – Arguments to use when instantiating the interpolating function.

  • extrapolator (Type[ProtocolExtrapolator] | None) – Extrapolator class type to use as extrapolating function.

  • extrapolator_kwargs (dict | None) – Arguments to use when instantiating the extrapolating function.

Returns:

Aligned spectral distribution.

Return type:

colour.SpectralDistribution

Examples

>>> from colour.utilities import numpy_print_options
>>> data = {
...     500: 0.0651,
...     520: 0.0705,
...     540: 0.0772,
...     560: 0.0870,
...     580: 0.1128,
...     600: 0.1360,
... }
>>> sd = SpectralDistribution(data)
>>> with numpy_print_options(suppress=True):
...     print(sd.align(SpectralShape(505, 565, 1)))
...
[[505.           0.0663929...]
 [506.           0.0666509...]
 [507.           0.0669069...]
 [508.           0.0671613...]
 [509.           0.0674150...]
 [510.           0.0676692...]
 [511.           0.0679253...]
 [512.           0.0681848...]
 [513.           0.0684491...]
 [514.           0.0687197...]
 [515.           0.0689975...]
 [516.           0.0692832...]
 [517.           0.0695771...]
 [518.           0.0698787...]
 [519.           0.0701870...]
 [520.           0.0705   ...]
 [521.           0.0708155...]
 [522.           0.0711336...]
 [523.           0.0714547...]
 [524.           0.0717789...]
 [525.           0.0721063...]
 [526.           0.0724367...]
 [527.           0.0727698...]
 [528.           0.0731051...]
 [529.           0.0734423...]
 [530.           0.0737808...]
 [531.           0.0741203...]
 [532.           0.0744603...]
 [533.           0.0748006...]
 [534.           0.0751409...]
 [535.           0.0754813...]
 [536.           0.0758220...]
 [537.           0.0761633...]
 [538.           0.0765060...]
 [539.           0.0768511...]
 [540.           0.0772   ...]
 [541.           0.0775527...]
 [542.           0.0779042...]
 [543.           0.0782507...]
 [544.           0.0785908...]
 [545.           0.0789255...]
 [546.           0.0792576...]
 [547.           0.0795917...]
 [548.           0.0799334...]
 [549.           0.0802895...]
 [550.           0.0806671...]
 [551.           0.0810740...]
 [552.           0.0815176...]
 [553.           0.0820049...]
 [554.           0.0825423...]
 [555.           0.0831351...]
 [556.           0.0837873...]
 [557.           0.0845010...]
 [558.           0.0852763...]
 [559.           0.0861110...]
 [560.           0.087    ...]
 [561.           0.0879383...]
 [562.           0.0889300...]
 [563.           0.0899793...]
 [564.           0.0910876...]
 [565.           0.0922541...]]
trim(shape: SpectralShape) → Self[source]#

Trim the spectral distribution wavelengths to the specified spectral shape.

Parameters:

shape (SpectralShape) – Spectral shape used for trimming.

Returns:

Trimmed spectral distribution.

Return type:

colour.SpectralDistribution

Examples

>>> from colour.utilities import numpy_print_options
>>> data = {
...     500: 0.0651,
...     520: 0.0705,
...     540: 0.0772,
...     560: 0.0870,
...     580: 0.1128,
...     600: 0.1360,
... }
>>> sd = SpectralDistribution(data)
>>> sd = sd.interpolate(SpectralShape(500, 600, 1))
>>> with numpy_print_options(suppress=True):
...     print(sd.trim(SpectralShape(520, 580, 5)))
...
[[520.           0.0705   ...]
 [521.           0.0708155...]
 [522.           0.0711336...]
 [523.           0.0714547...]
 [524.           0.0717789...]
 [525.           0.0721063...]
 [526.           0.0724367...]
 [527.           0.0727698...]
 [528.           0.0731051...]
 [529.           0.0734423...]
 [530.           0.0737808...]
 [531.           0.0741203...]
 [532.           0.0744603...]
 [533.           0.0748006...]
 [534.           0.0751409...]
 [535.           0.0754813...]
 [536.           0.0758220...]
 [537.           0.0761633...]
 [538.           0.0765060...]
 [539.           0.0768511...]
 [540.           0.0772   ...]
 [541.           0.0775527...]
 [542.           0.0779042...]
 [543.           0.0782507...]
 [544.           0.0785908...]
 [545.           0.0789255...]
 [546.           0.0792576...]
 [547.           0.0795917...]
 [548.           0.0799334...]
 [549.           0.0802895...]
 [550.           0.0806671...]
 [551.           0.0810740...]
 [552.           0.0815176...]
 [553.           0.0820049...]
 [554.           0.0825423...]
 [555.           0.0831351...]
 [556.           0.0837873...]
 [557.           0.0845010...]
 [558.           0.0852763...]
 [559.           0.0861110...]
 [560.           0.087    ...]
 [561.           0.0879383...]
 [562.           0.0889300...]
 [563.           0.0899793...]
 [564.           0.0910876...]
 [565.           0.0922541...]
 [566.           0.0934760...]
 [567.           0.0947487...]
 [568.           0.0960663...]
 [569.           0.0974220...]
 [570.           0.0988081...]
 [571.           0.1002166...]
 [572.           0.1016394...]
 [573.           0.1030687...]
 [574.           0.1044972...]
 [575.           0.1059186...]
 [576.           0.1073277...]
 [577.           0.1087210...]
 [578.           0.1100968...]
 [579.           0.1114554...]
 [580.           0.1128   ...]]
normalise(factor: Real = 1) → Self[source]#

Normalise the spectral distribution with the specified normalization factor.

Parameters:

factor (Real) – Normalisation factor.

Returns:

Normalised spectral distribution.

Return type:

colour.SpectralDistribution

Examples

>>> from colour.utilities import numpy_print_options
>>> data = {
...     500: 0.0651,
...     520: 0.0705,
...     540: 0.0772,
...     560: 0.0870,
...     580: 0.1128,
...     600: 0.1360,
... }
>>> sd = SpectralDistribution(data)
>>> with numpy_print_options(suppress=True):
...     print(sd.normalise())
[[500.           0.4786764...]
 [520.           0.5183823...]
 [540.           0.5676470...]
 [560.           0.6397058...]
 [580.           0.8294117...]
 [600.           1.       ...]]