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:
SignalDefine 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.wavelengthproperty with. If bothdataanddomainarguments are defined, the latter will be used to initialise thecolour.SpectralDistribution.wavelengthproperty.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.nameproperty 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:
data (TypeAliasForwardRef('ArrayLike') | dict | Series | Signal | ValuesView | None)
domain (TypeAliasForwardRef('ArrayLike') | SpectralShape | KeysView | None)
kwargs (Any)
- 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:
- 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:
- 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:
- property shape: SpectralShape#
Getter property for the spectral distribution shape.
- Returns:
Spectral distribution shape.
- Return type:
Notes
A spectral distribution with a non-uniformly spaced independent variable have multiple intervals, in that case
colour.SpectralDistribution.shapeproperty 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
interpolatoris 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_kwargsis 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:
Notes
Interpolation will be performed over boundaries range, if it is required to extend the range of the spectral distribution use the
colour.SpectralDistribution.extrapolate()orcolour.SpectralDistribution.align()methods.
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
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:
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
interpolatoris 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_kwargsis 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:
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:
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:
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. ...]]