colour.multi_sds_to_XYZ

colour.multi_sds_to_XYZ(msds, cmfs=XYZ_ColourMatchingFunctions(name='CIE 1931 2 Degree Standard Observer', ...), illuminant=SpectralDistribution(name='1 Constant', ...), k=None, method='ASTM E308', **kwargs)[source]

Converts given multi-spectral distributions to CIE XYZ tristimulus values using given colour matching functions and illuminant. For the Integration method, the multi-spectral distributions can be either a colour.MultiSpectralDistributions class instance or an array_like in which case the shape must be passed.

Parameters:
  • msds (MultiSpectralDistributions or array_like) – Multi-spectral distributions, if an array_like the wavelengths are expected to be in the last axis, e.g. for a 512x384 multi-spectral image with 77 bins, msds shape should be (384, 512, 77).
  • cmfs (XYZ_ColourMatchingFunctions) – Standard observer colour matching functions.
  • illuminant (SpectralDistribution, optional) – Illuminant spectral distribution.
  • k (numeric, optional) – Normalisation constant \(k\). For reflecting or transmitting object colours, \(k\) is chosen so that \(Y = 100\) for objects for which the spectral reflectance factor \(R(\lambda)\) of the object colour or the spectral transmittance factor \(\tau(\lambda)\) of the object is equal to unity for all wavelengths. For self-luminous objects and illuminants, the constants \(k\) is usually chosen on the grounds of convenience. If, however, in the CIE 1931 standard colorimetric system, the \(Y\) value is required to be numerically equal to the absolute value of a photometric quantity, the constant, \(k\), must be put equal to the numerical value of \(K_m\), the maximum spectral luminous efficacy (which is equal to 683 \(lm\cdot W^{-1}\)) and \(\Phi_\lambda(\lambda)\) must be the spectral concentration of the radiometric quantity corresponding to the photometric quantity required.
  • method (unicode, optional) – {‘ASTM E308’, ‘Integration’}, Computation method.
Other Parameters:
 
  • use_practice_range (bool, optional) – {colour.colorimetry.multi_sds_to_XYZ_ASTME308()}, Practise ASTM E308-15 working wavelengths range is [360, 780], if True this argument will trim the colour matching functions appropriately.
  • mi_5nm_omission_method (bool, optional) – {colour.colorimetry.multi_sds_to_XYZ_ASTME308()}, 5 nm measurement intervals multi-spectral distributions conversion to tristimulus values will use a 5 nm version of the colour matching functions instead of a table of tristimulus weighting factors.
  • mi_20nm_interpolation_method (bool, optional) – {colour.colorimetry.multi_sds_to_XYZ_ASTME308()}, 20 nm measurement intervals multi-spectral distributions conversion to tristimulus values will use a dedicated interpolation method instead of a table of tristimulus weighting factors.
  • shape (SpectralShape, optional) – {colour.colorimetry.multi_sds_to_XYZ_integration()}, Spectral shape of the multi-spectral distributions array \(msds\), cmfs and illuminant will be aligned to it.
Returns:

CIE XYZ tristimulus values, for a 512x384 multi-spectral image with 77 wavelengths, the output shape will be (384, 512, 3).

Return type:

array_like

Notes

Range Scale - Reference Scale - 1
XYZ [0, 100] [0, 1]
  • The code path using the array_like multi-spectral distributions produces results different to the code path using a colour.MultiSpectralDistributions class instance: the former favours execution speed by aligning the colour matching functions and illuminant to the given spectral shape while the latter favours precision by aligning the multi-spectral distributions to the colour matching functions.

References

[ASTMInternational2011a], [ASTMInternational2015b], [Wyszecki2000bf]

Examples

>>> shape = SpectralShape(400, 700, 60)
>>> data = np.array([
...     [0.0137, 0.0159, 0.0096, 0.0111, 0.0179, 0.1057, 0.0433,
...      0.0258, 0.0248, 0.0186, 0.0310, 0.0473],
...     [0.0913, 0.3145, 0.2582, 0.0709, 0.2971, 0.4620, 0.2683,
...      0.0831, 0.1203, 0.1292, 0.1682, 0.3221],
...     [0.0152, 0.0842, 0.4139, 0.0220, 0.5630, 0.1918, 0.2373,
...      0.0430, 0.0054, 0.0079, 0.3719, 0.2268],
...     [0.0281, 0.0907, 0.2228, 0.1249, 0.2375, 0.5625, 0.0518,
...      0.3230, 0.0065, 0.4006, 0.0861, 0.3161],
...     [0.1918, 0.7103, 0.0041, 0.1817, 0.0024, 0.4209, 0.0118,
...      0.2302, 0.1860, 0.9404, 0.0041, 0.1124],
...     [0.0430, 0.0437, 0.3744, 0.0020, 0.5819, 0.0027, 0.0823,
...      0.0081, 0.3625, 0.3213, 0.7849, 0.0024],
... ])
>>> msds = MultiSpectralDistributions(data, shape.range())
>>> multi_sds_to_XYZ(msds, method='Integration', shape=shape)
... # doctest: +ELLIPSIS
array([[  8.2415862...,   4.2543993...,   7.6100842...],
       [ 29.6144619...,  16.1158465...,  25.9015472...],
       [ 16.6799560...,  27.2350547...,  22.9413337...],
       [ 12.5597688...,   9.0667136...,   5.9670327...],
       [ 18.5804689...,  33.6618109...,  26.9249733...],
       [ 47.7113308...,  40.4573249...,  39.6439145...],
       [  7.830207 ...,  12.3689624...,  23.3742655...],
       [ 24.1695370...,  20.0629815...,   7.2718670...],
       [  7.2333751...,   2.7982097...,  10.0688374...],
       [ 48.7358074...,  30.2417164...,  10.6753233...],
       [  8.3231013...,  18.6791507...,  15.8228184...],
       [ 24.6452277...,  26.0809382...,  27.7106399...]])
>>> msds = np.array([
...     [
...         [0.0137, 0.0913, 0.0152, 0.0281, 0.1918, 0.0430],
...         [0.0159, 0.3145, 0.0842, 0.0907, 0.7103, 0.0437],
...         [0.0096, 0.2582, 0.4139, 0.2228, 0.0041, 0.3744],
...         [0.0111, 0.0709, 0.0220, 0.1249, 0.1817, 0.0020],
...         [0.0179, 0.2971, 0.5630, 0.2375, 0.0024, 0.5819],
...         [0.1057, 0.4620, 0.1918, 0.5625, 0.4209, 0.0027],
...     ],
...     [
...         [0.0433, 0.2683, 0.2373, 0.0518, 0.0118, 0.0823],
...         [0.0258, 0.0831, 0.0430, 0.3230, 0.2302, 0.0081],
...         [0.0248, 0.1203, 0.0054, 0.0065, 0.1860, 0.3625],
...         [0.0186, 0.1292, 0.0079, 0.4006, 0.9404, 0.3213],
...         [0.0310, 0.1682, 0.3719, 0.0861, 0.0041, 0.7849],
...         [0.0473, 0.3221, 0.2268, 0.3161, 0.1124, 0.0024],
...     ],
... ])
>>> multi_sds_to_XYZ(msds, method='Integration', shape=shape)
... # doctest: +ELLIPSIS
array([[[  7.6862675...,   4.0925470...,   8.4950412...],
        [ 27.4119366...,  15.5014764...,  29.2825122...],
        [ 17.1283666...,  27.7798651...,  25.5232032...],
        [ 11.9824544...,   8.8127109...,   6.6518695...],
        [ 19.1030682...,  34.4597818...,  29.7653804...],
        [ 46.8243374...,  39.9551652...,  43.6541858...]],
<BLANKLINE>
       [[  8.0978189...,  12.7544378...,  25.8004512...],
        [ 23.4360673...,  19.6127966...,   7.9342408...],
        [  7.0933208...,   2.7894394...,  11.1527704...],
        [ 45.6313772...,  29.0068105...,  11.9934522...],
        [  8.9327884...,  19.4008147...,  17.1534186...],
        [ 24.6610235...,  26.1093760...,  30.7298791...]]])