Colorimetry#

Spectral Data Structure#

colour

SpectralShape(start, end, interval)

Define the base object for spectral distribution shape.

SpectralDistribution([data, domain])

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

MultiSpectralDistributions([data, domain, ...])

Define the multi-spectral distributions: the base object for multi spectral computations.

SPECTRAL_SHAPE_ASTME308

(360, 780, 1).

SPECTRAL_SHAPE_DEFAULT

(360, 780, 1).

Ancillary Objects

colour.colorimetry

reshape_sd(sd[, shape, method, copy])

Reshape given spectral distribution with given spectral shape.

reshape_msds(msds[, shape, method, copy])

Reshape given multi-spectral distributions with given spectral shape.

sds_and_msds_to_sds(sds)

Convert given spectral and multi-spectral distributions to a list of spectral distributions.

sds_and_msds_to_msds(sds)

Convert given spectral and multi-spectral distributions to multi-spectral distributions.

Spectral Data Generation#

colour

sd_CIE_standard_illuminant_A([shape])

CIE Standard Illuminant A is intended to represent typical, domestic, tungsten-filament lighting.

sd_CIE_illuminant_D_series(xy[, ...])

Return the spectral distribution of given CIE Illuminant D Series using given CIE xy chromaticity coordinates.

sd_blackbody(temperature[, shape, c1, c2, n])

Return the spectral distribution of the planckian radiator for given temperature \(T[K]\) with values in watts per steradian per square metre per nanometer (\(W/sr/m^2/nm\)).

sd_rayleigh_jeans(temperature[, shape])

Return the spectral distribution of the planckian radiator for given temperature \(T[K]\) with values in watts per steradian per square metre per nanometer (\(W/sr/m^2/nm\)) according to Rayleigh-Jeans law.

sd_constant(k[, shape])

Return a spectral distribution of given spectral shape filled with constant \(k\) values.

sd_ones([shape])

Return a spectral distribution of given spectral shape filled with ones.

sd_zeros([shape])

Return a spectral distribution of given spectral shape filled with zeros.

msds_constant(k, labels[, shape])

Return the multi-spectral distributions with given labels and given spectral shape filled with constant \(k\) values.

msds_ones(labels[, shape])

Return the multi-spectral distributionss with given labels and given spectral shape filled with ones.

msds_zeros(labels[, shape])

Return the multi-spectral distributionss with given labels and given spectral shape filled with zeros.

SD_GAUSSIAN_METHODS

Supported gaussian spectral distribution computation methods.

sd_gaussian(mu_peak_wavelength, sigma_fwhm)

Return a gaussian spectral distribution of given spectral shape using given method.

SD_SINGLE_LED_METHODS

Supported single LED spectral distribution computation methods.

sd_single_led(peak_wavelength[, shape, method])

Return a single LED spectral distribution of given spectral shape at given peak wavelength according to given method.

SD_MULTI_LEDS_METHODS

Supported multi LED spectral distribution computation methods.

sd_multi_leds(peak_wavelengths[, shape, method])

Return a multi LED spectral distribution of given spectral shape at given peak wavelengths.

colour.colorimetry

blackbody_spectral_radiance(wavelength, ...)

Return the spectral radiance of a blackbody as a function of wavelength at thermodynamic temperature \(T[K]\) in a medium having index of refraction \(n\).

planck_law(wavelength, temperature[, c1, c2, n])

Return the spectral radiance of a blackbody as a function of wavelength at thermodynamic temperature \(T[K]\) in a medium having index of refraction \(n\).

rayleigh_jeans_law(wavelength, temperature)

Return the approximation of the spectral radiance of a blackbody as a function of wavelength at thermodynamic temperature \(T[K]\) according to Rayleigh-Jeans law.

daylight_locus_function(x_D)

Return the daylight locus as CIE xy chromaticity coordinates.

sd_gaussian_normal(mu, sigma[, shape])

Return a gaussian spectral distribution of given spectral shape at given mean wavelength \(\mu\) and standard deviation \(sigma\).

sd_gaussian_fwhm(peak_wavelength, fwhm[, shape])

Return a gaussian spectral distribution of given spectral shape at given peak wavelength and full width at half maximum.

sd_single_led_Ohno2005(peak_wavelength, ...)

Return a single LED spectral distribution of given spectral shape at given peak wavelength and half spectral width \(\Delta\lambda_{0.5}\) according to Ohno (2005) method.

sd_multi_leds_Ohno2005(peak_wavelengths, ...)

Return a multi LED spectral distribution of given spectral shape at given peak wavelengths, half spectral widths \(\Delta\lambda_{0.5}\) and peak power ratios according to Ohno (2005) method.

Aliases

colour.colorimetry

planck_law(wavelength, temperature[, c1, c2, n])

Return the spectral radiance of a blackbody as a function of wavelength at thermodynamic temperature \(T[K]\) in a medium having index of refraction \(n\).

Conversion to Tristimulus Values#

colour

sd_to_XYZ(sd[, cmfs, illuminant, k, method])

Convert given spectral distribution to CIE XYZ tristimulus values using given colour matching functions, illuminant and method.

SD_TO_XYZ_METHODS

Supported spectral distribution to CIE XYZ tristimulus values conversion methods.

msds_to_XYZ(msds[, cmfs, illuminant, k, method])

Convert given multi-spectral distributions to CIE XYZ tristimulus values using given colour matching functions and illuminant.

MSDS_TO_XYZ_METHODS

Supported multi-spectral array to CIE XYZ tristimulus values conversion methods.

wavelength_to_XYZ(wavelength[, cmfs])

Convert given wavelength \(\lambda\) to CIE XYZ tristimulus values using given colour matching functions.

Ancillary Objects

colour.colorimetry

handle_spectral_arguments([cmfs, ...])

Handle the spectral arguments of various Colour definitions performing spectral computations.

ASTM E308-15#

colour.colorimetry

sd_to_XYZ_ASTME308(sd[, cmfs, illuminant, ...])

Convert given spectral distribution to CIE XYZ tristimulus values using given colour matching functions and illuminant according to practise ASTM E308-15 method.

msds_to_XYZ_ASTME308(msds[, cmfs, ...])

Convert given multi-spectral distributions to CIE XYZ tristimulus values using given colour matching functions and illuminant according to practise ASTM E308-15 method.

Ancillary Objects

colour.colorimetry

sd_to_XYZ_tristimulus_weighting_factors_ASTME308(sd)

Convert given spectral distribution to CIE XYZ tristimulus values using given colour matching functions and illuminant using a table of tristimulus weighting factors according to practise ASTM E308-15 method.

adjust_tristimulus_weighting_factors_ASTME308(W, ...)

Adjust given table of tristimulus weighting factors to account for a shorter wavelengths range of the test spectral shape compared to the reference spectral shape using practise ASTM E308-15 method: Weights at the wavelengths for which data are not available are added to the weights at the shortest and longest wavelength for which spectral data are available.

lagrange_coefficients_ASTME2022([interval, ...])

Compute the Lagrange Coefficients for given interval size using practise ASTM E2022-11 method.

tristimulus_weighting_factors_ASTME2022(...)

Return a table of tristimulus weighting factors for given colour matching functions and illuminant using practise ASTM E2022-11 method.

Integration#

colour.colorimetry

sd_to_XYZ_integration(sd[, cmfs, ...])

Convert given spectral distribution to CIE XYZ tristimulus values using given colour matching functions and illuminant according to classical integration method.

msds_to_XYZ_integration(msds[, cmfs, ...])

Convert given multi-spectral distributions to CIE XYZ tristimulus values using given colour matching functions and illuminant.

Spectral Bandpass Dependence Correction#

colour

bandpass_correction(sd[, method])

Implement spectral bandpass dependence correction on given spectral distribution using given method.

BANDPASS_CORRECTION_METHODS

Supported spectral bandpass dependence correction methods.

Stearns and Stearns (1988)#

colour.colorimetry

bandpass_correction_Stearns1988(sd)

Implement spectral bandpass dependence correction on given spectral distribution using Stearns and Stearns (1988) method.

Colour Matching Functions#

colour.colorimetry

LMS_ConeFundamentals([data, domain, labels])

Implement support for the Stockman and Sharpe LMS cone fundamentals colour matching functions.

RGB_ColourMatchingFunctions([data, domain, ...])

Implement support for the CIE RGB colour matching functions.

XYZ_ColourMatchingFunctions([data, domain, ...])

Implement support for the CIE Standard Observers XYZ colour matching functions.

Dataset

colour

MSDS_CMFS

Multi-spectral distributions of the colour matching functions.

Ancillary Objects

colour.colorimetry

MSDS_CMFS_LMS

Multi-spectral distributions of the LMS colour matching functions.

MSDS_CMFS_RGB

Multi-spectral distributions of the RGB colour matching functions.

MSDS_CMFS_STANDARD_OBSERVER

Multi-spectral distributions of the CIE Standard Observer colour matching functions.

Colour Matching Functions Transformations#

Ancillary Objects

colour.colorimetry

RGB_2_degree_cmfs_to_XYZ_2_degree_cmfs(...)

Convert Wright & Guild 1931 2 Degree RGB CMFs colour matching functions into the CIE 1931 2 Degree Standard Observer colour matching functions.

RGB_10_degree_cmfs_to_XYZ_10_degree_cmfs(...)

Convert Stiles & Burch 1959 10 Degree RGB CMFs colour matching functions into the CIE 1964 10 Degree Standard Observer colour matching functions.

RGB_10_degree_cmfs_to_LMS_10_degree_cmfs(...)

Convert Stiles & Burch 1959 10 Degree RGB CMFs colour matching functions into the Stockman & Sharpe 10 Degree Cone Fundamentals spectral sensitivity functions.

LMS_2_degree_cmfs_to_XYZ_2_degree_cmfs(...)

Convert Stockman & Sharpe 2 Degree Cone Fundamentals colour matching functions into the CIE 2015 2 Degree Standard Observer colour matching functions.

LMS_10_degree_cmfs_to_XYZ_10_degree_cmfs(...)

Convert Stockman & Sharpe 10 Degree Cone Fundamentals colour matching functions into the CIE 2015 10 Degree Standard Observer colour matching functions.

Illuminants and Light Sources#

Dataset

colour

CCS_ILLUMINANTS

Chromaticity coordinates of the illuminants.

SDS_ILLUMINANTS

Spectral distributions of the illuminants.

CCS_LIGHT_SOURCES

Chromaticity coordinates of the light sources.

SDS_LIGHT_SOURCES

Spectral distributions of the light sources.

TVS_ILLUMINANTS

CIE XYZ tristimulus values of the illuminants.

TVS_ILLUMINANTS_HUNTERLAB

CIE XYZ tristimulus values of the HunterLab illuminants.

Ancillary Objects

colour.colorimetry

SDS_BASIS_FUNCTIONS_CIE_ILLUMINANT_D_SERIES

CIE Illuminant D Series \(S_n(\lambda)\) spectral distributions.

Dominant Wavelength and Purity#

colour

dominant_wavelength(xy, xy_n[, cmfs, inverse])

Return the dominant wavelength \(\lambda_d\) for given colour stimulus \(xy\) and the related \(xy_wl\) first and \(xy_{cw}\) second intersection coordinates with the spectral locus.

complementary_wavelength(xy, xy_n[, cmfs])

Return the complementary wavelength \(\lambda_c\) for given colour stimulus \(xy\) and the related \(xy_wl\) first and \(xy_{cw}\) second intersection coordinates with the spectral locus.

excitation_purity(xy, xy_n[, cmfs])

Return the excitation purity \(P_e\) for given colour stimulus \(xy\).

colorimetric_purity(xy, xy_n[, cmfs])

Return the colorimetric purity \(P_c\) for given colour stimulus \(xy\).

Luminous Efficiency Functions#

colour

luminous_efficacy(sd[, lef])

Return the luminous efficacy in \(lm\cdot W^{-1}\) of given spectral distribution using given luminous efficiency function.

luminous_efficiency(sd[, lef])

Return the luminous efficiency of given spectral distribution using given luminous efficiency function.

luminous_flux(sd[, lef, K_m])

Return the luminous flux for given spectral distribution using given luminous efficiency function.

sd_mesopic_luminous_efficiency_function(L_p)

Return the mesopic luminous efficiency function \(V_m(\lambda)\) for given photopic luminance \(L_p\).

Dataset

colour

SDS_LEFS

Spectral distributions of the luminous efficiency functions.

Ancillary Objects

colour.colorimetry

SDS_LEFS_PHOTOPIC

Spectral distributions of the photopic luminous efficiency functions.

SDS_LEFS_SCOTOPIC

Spectral distributions of the scotopic luminous efficiency functions.

Spectral Uniformity#

colour

spectral_uniformity(sds[, ...])

Compute the spectral uniformity (or spectral flatness) of given spectral distributions.

Lightness Computation#

colour

lightness(Y[, method])

Return the Lightness \(L\) of given luminance \(Y\) using given method.

LIGHTNESS_METHODS

Supported Lightness computation methods.

Glasser, Mckinney, Reilly and Schnelle (1958)#

colour.colorimetry

lightness_Glasser1958(Y)

Return the Lightness \(L\) of given luminance \(Y\) using Glasser et al. (1958) method.

Wyszecki (1963)#

colour.colorimetry

lightness_Wyszecki1963(Y)

Return the Lightness \(W\) of given luminance \(Y\) using Wyszecki (1963) method.

CIE 1976#

colour.colorimetry

lightness_CIE1976(Y[, Y_n])

Return the Lightness \(L^*\) of given luminance \(Y\) using given reference white luminance \(Y_n\) as per CIE 1976 recommendation.

intermediate_lightness_function_CIE1976(Y[, Y_n])

Return the intermediate value \(f(Y/Yn)\) in the Lightness \(L^*\) computation for given luminance \(Y\) using given reference white luminance \(Y_n\) as per CIE 1976 recommendation.

Fairchild and Wyble (2010)#

colour.colorimetry

lightness_Fairchild2010(Y[, epsilon])

Compute Lightness \(L_{hdr}\) of given luminance \(Y\) using Fairchild and Wyble (2010) method according to Michaelis-Menten kinetics.

Fairchild and Chen (2011)#

colour.colorimetry

lightness_Fairchild2011(Y[, epsilon, method])

Compute Lightness \(L_{hdr}\) of given luminance \(Y\) using Fairchild and Chen (2011) method according to Michaelis-Menten kinetics.

Abebe, Pouli, Larabi and Reinhard (2017)#

colour.colorimetry

lightness_Abebe2017(Y[, Y_n, method])

Compute Lightness \(L\) of given luminance \(Y\) using Abebe, Pouli, Larabi and Reinhard (2017) method according to Michaelis-Menten kinetics or Stevens's Power Law.

Luminance Computation#

colour

luminance(LV[, method])

Return the luminance \(Y\) of given Lightness \(L^*\) or given Munsell value \(V\).

LUMINANCE_METHODS

Supported luminance computation methods.

Newhall, Nickerson and Judd (1943)#

colour.colorimetry

luminance_Newhall1943(V)

Return the luminance \(R_Y\) of given Munsell value \(V\) using Newhall et al. (1943) method.

CIE 1976#

colour.colorimetry

luminance_CIE1976(L_star[, Y_n])

Return the luminance \(Y\) of given Lightness \(L^*\) with given reference white luminance \(Y_n\).

intermediate_luminance_function_CIE1976(f_Y_Y_n)

Return the luminance \(Y\) in the luminance \(Y\) computation for given intermediate value \(f(Y/Yn)\) using given reference white luminance \(Y_n\) as per CIE 1976 recommendation.

ASTM D1535-08e1#

colour.colorimetry

luminance_ASTMD1535(V)

Return the luminance \(Y\) of given Munsell value \(V\) using ASTM D1535-08e1 method.

Fairchild and Wyble (2010)#

colour.colorimetry

luminance_Fairchild2010(L_hdr[, epsilon])

Compute luminance \(Y\) of given Lightness \(L_{hdr}\) using Fairchild and Wyble (2010) method according to Michaelis-Menten kinetics.

Fairchild and Chen (2011)#

colour.colorimetry

luminance_Fairchild2011(L_hdr[, epsilon, method])

Compute luminance \(Y\) of given Lightness \(L_{hdr}\) using Fairchild and Chen (2011) method according to Michaelis-Menten kinetics.

Whiteness Computation#

colour

whiteness(XYZ, XYZ_0[, method])

Return the whiteness \(W\) using given method.

WHITENESS_METHODS

Supported whiteness computation methods.

Berger (1959)#

colour.colorimetry

whiteness_Berger1959(XYZ, XYZ_0)

Return the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using Berger (1959) method.

Taube (1960)#

colour.colorimetry

whiteness_Taube1960(XYZ, XYZ_0)

Return the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using Taube (1960) method.

Stensby (1968)#

colour.colorimetry

whiteness_Stensby1968(Lab)

Return the whiteness index \(WI\) of given sample CIE L*a*b* colourspace array using Stensby (1968) method.

ASTM E313#

colour.colorimetry

whiteness_ASTME313(XYZ)

Return the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using ASTM E313 method.

Ganz and Griesser (1979)#

colour.colorimetry

whiteness_Ganz1979(xy, Y)

Return the whiteness index \(W\) and tint \(T\) of given sample CIE xy chromaticity coordinates using Ganz and Griesser (1979) method.

CIE 2004#

colour.colorimetry

whiteness_CIE2004(xy, Y, xy_n[, observer])

Return the whiteness \(W\) or \(W_{10}\) and tint \(T\) or \(T_{10}\) of given sample CIE xy chromaticity coordinates using CIE 2004 method.

Yellowness Computation#

colour

yellowness(XYZ[, method])

Return the yellowness \(W\) using given method.

YELLOWNESS_METHODS

Supported yellowness computation methods.

ASTM D1925#

colour.colorimetry

yellowness_ASTMD1925(XYZ)

Return the yellowness index \(YI\) of given sample CIE XYZ tristimulus values using ASTM D1925 method.

ASTM E313#

colour.colorimetry

yellowness_ASTME313_alternative(XYZ)

Return the yellowness index \(YI\) of given sample CIE XYZ tristimulus values using the alternative ASTM E313 method.

YELLOWNESS_COEFFICIENTS_ASTME313

Coefficients \(C_X\) and \(C_Z\) for the ASTM E313 yellowness index \(YI\) computation method.

yellowness_ASTME313(XYZ[, C_XZ])

Return the yellowness index \(YI\) of given sample CIE XYZ tristimulus values using ASTM E313 method.