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 bothdata
anddomain
arguments are defined, the latter will be used to initialise thecolour.SpectralDistribution.wavelength
attribute.
- Other Parameters
name (unicode, optional) – Spectral distribution name.
interpolator (object, optional) – Interpolator class type to use as interpolating function.
interpolator_args (dict_like, optional) – Arguments to use when instantiating the interpolating function.
extrapolator (object, optional) – Extrapolator class type to use as extrapolating function.
extrapolator_args (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
¶
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_args={}, extrapolator=Extrapolator, extrapolator_args={...})
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_args={}, extrapolator=Extrapolator, extrapolator_args={...})
-
align
(shape, interpolator=None, interpolator_args=None, extrapolator=None, extrapolator_args=None)[source] Aligns the spectral distribution in-place to given spectral shape: Interpolates first then extrapolates to fit the given range.
- Parameters
shape (SpectralShape) – Spectral shape used for alignment.
interpolator (object, optional) – Interpolator class type to use as interpolating function.
interpolator_args (dict_like, optional) – Arguments to use when instantiating the interpolating function.
extrapolator (object, optional) – Extrapolator class type to use as extrapolating function.
extrapolator_args (dict_like, optional) – 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...]]
-
extrapolate
(shape, extrapolator=None, extrapolator_args=None)[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_args (dict_like, optional) – Arguments to use when instantiating the extrapolating function.
- Returns
Extrapolated spectral distribution.
- Return type
References
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_args=None)[source] Interpolates the spectral distribution in-place according to CIE 167:2005 recommendation or given interpolation arguments.
- Parameters
shape (SpectralShape, optional) – Spectral shape used for interpolation.
interpolator (object, optional) – Interpolator class type to use as interpolating function.
interpolator_args (dict_like, optional) – Arguments to use when instantiating the interpolating function.
- Returns
Interpolated spectral distribution.
- Return type
Notes
Interpolation will be performed over boundaries range, if you need 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(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 no-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
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
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
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