colour.SpectralDistribution

class colour.SpectralDistribution(data=None, domain=None, **kwargs)[source]

Bases: colour.continuous.signal.Signal

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

The spectral distribution will be initialised according to CIE 15:2004 recommendation: the method developed by Sprague (1880) will be used for interpolating functions having a uniformly spaced independent variable and the Cubic Spline method for non-uniformly spaced independent variable. Extrapolation is performed according to CIE 167:2005 recommendation.

Parameters
  • data (Series or Signal, SpectralDistribution or array_like or dict_like, optional) – Data to be stored in the spectral distribution.

  • domain (array_like, optional) – Values to initialise the colour.SpectralDistribution.wavelength attribute with. If both data and domain arguments are defined, the latter will be used to initialise the colour.SpectralDistribution.wavelength attribute.

Other Parameters
  • name (unicode, optional) – Spectral distribution name.

  • interpolator (object, optional) – Interpolator class type to use as interpolating function.

  • interpolator_kwargs (dict_like, optional) – Arguments to use when instantiating the interpolating function.

  • extrapolator (object, optional) – Extrapolator class type to use as extrapolating function.

  • extrapolator_kwargs (dict_like, optional) – Arguments to use when instantiating the extrapolating function.

  • strict_name (unicode, optional) – Spectral distribution name for figures, default to colour.SpectralDistribution.name attribute value.

strict_name
wavelengths
values
shape
__init_\_
interpolate()[source]
extrapolate()[source]
align()[source]
trim()[source]
normalise()[source]

References

[CIET13805a], [CIET13805c], [CIET14804h]

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 ]],
                     interpolator=SpragueInterpolator,
                     interpolator_kwargs={},
                     extrapolator=Extrapolator,
                     extrapolator_kwargs={...})

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  ]],
                     interpolator=CubicSplineInterpolator,
                     interpolator_kwargs={},
                     extrapolator=Extrapolator,
                     extrapolator_kwargs={...})
align(shape, interpolator=None, interpolator_kwargs=None, extrapolator=None, extrapolator_kwargs=None, **kwargs)[source]

Aligns the spectral distribution in-place to given spectral shape: Interpolates first then extrapolates to fit the given range.

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

The logic for choosing the interpolator class when interpolator is not given 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 given 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 (object, optional) – Interpolator class type to use as interpolating function.

  • interpolator_kwargs (dict_like, optional) – Arguments to use when instantiating the interpolating function.

  • extrapolator (object, optional) – Extrapolator class type to use as extrapolating function.

  • extrapolator_kwargs (dict_like, optional) – Arguments to use when instantiating the extrapolating function.

Other Parameters

**kwargs (dict, optional) – Keywords arguments for deprecation management.

Returns

Aligned spectral distribution.

Return type

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...]]
extrapolate(shape, extrapolator=None, extrapolator_kwargs=None, **kwargs)[source]

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

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

  • extrapolator (object, optional) – Extrapolator class type to use as extrapolating function.

  • extrapolator_kwargs (dict_like, optional) – Arguments to use when instantiating the extrapolating function.

Other Parameters

**kwargs (dict, optional) – Keywords arguments for deprecation management.

Returns

Extrapolated spectral distribution.

Return type

SpectralDistribution

References

[CIET13805c], [CIET14804h]

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)).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 ]]
interpolate(shape, interpolator=None, interpolator_kwargs=None, **kwargs)[source]

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

The logic for choosing the interpolator class when interpolator is not given 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 given is as follows:

if self.interpolator not in (SpragueInterpolator,
                             CubicSplineInterpolator):
    interpolator_kwargs = self.interpolator_kwargs
else:
    interpolator_kwargs = {}
Parameters
  • shape (SpectralShape, optional) – Spectral shape used for interpolation.

  • interpolator (object, optional) – Interpolator class type to use as interpolating function.

  • interpolator_kwargs (dict_like, optional) – Arguments to use when instantiating the interpolating function.

Other Parameters

**kwargs (dict, optional) – Keywords arguments for deprecation management.

Returns

Interpolated spectral distribution.

Return type

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(interval=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(interval=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    ...]]
normalise(factor=1)[source]

Normalises the spectral distribution using given normalization factor.

Parameters

factor (numeric, optional) – Normalization factor

Returns

Normalised spectral distribution.

Return type

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.       ...]]
property shape

Getter and setter property for the spectral distribution shape.

Returns

Spectral distribution shape.

Return type

SpectralShape

Notes

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

Warning

colour.SpectralDistribution.shape attribute is read only.

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)
property strict_name

Getter and setter property for the spectral distribution strict name.

Parameters

value (unicode) – Value to set the spectral distribution strict name with.

Returns

Spectral distribution strict name.

Return type

unicode

trim(shape)[source]

Trims the spectral distribution wavelengths to given spectral shape.

Parameters

shape (SpectralShape) – Spectral shape used for trimming.

Returns

Trimmed spectral distribution.

Return type

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(interval=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   ...]]
property values

Getter and setter property for the spectral distribution values.

Parameters

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

Returns

Spectral distribution values.

Return type

ndarray

property wavelengths

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

Parameters

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

Returns

Spectral distribution wavelengths \(\lambda_n\).

Return type

ndarray