Colour is an open-source Python package providing a comprehensive number of algorithms and datasets for colour science.
It is freely available under the New BSD License terms.
Colour is an affiliated project of NumFOCUS, a 501(c)(3) nonprofit in the United States.
Table of Contents
1 Draft Release Notes¶
The draft release notes from the develop branch are available at this url.
2 Sponsors¶
We are grateful for the support of our sponsors. If you’d like to join them, please consider becoming a sponsor on OpenCollective.
3 Features¶
Colour features a rich dataset and collection of objects, please see the features page for more information.
4 Installation¶
Colour and its primary dependencies can be easily installed from the Python Package Index by issuing this command in a shell:
$ pip install --user colour-science
The detailed installation procedure for the secondary dependencies is described in the Installation Guide.
Colour is also available for Anaconda from Continuum Analytics via conda-forge:
$ conda install -c conda-forge colour-science
5 Documentation¶
5.1 Tutorial¶
The static tutorial provides an introduction to Colour. An interactive version is available via Google Colab.
5.2 How-To Guide¶
The How-To guide for Colour shows various techniques to solve specific problems and highlights some interesting use cases.
5.3 API Reference¶
The main technical reference for Colour and its API is the Colour Manual.
Colour Manual¶
Tutorial¶
Note
An interactive version of the tutorial is available via Google Colab.
Colour spreads over various domains of Colour Science, from colour models to optical phenomena, this tutorial does not give a complete overview of the API but is a good introduction to the main concepts.
Note
A directory with examples is available at this path in Colour installation: colour/examples. It can also be explored directly on Github.
from colour.plotting import *
colour_style()
plot_visible_spectrum()
Overview¶
Colour is organised around various sub-packages:
adaptation: Chromatic adaptation models and transformations.
algebra: Algebra utilities.
appearance: Colour appearance models.
biochemistry: Biochemistry computations.
blindness: Colour vision deficiency models.
continuous: Base objects for continuous data representation.
contrast: Objects for contrast sensitivity computation.
characterisation: Colour correction, camera and display characterisation.
colorimetry: Core objects for colour computations.
constants: CIE and CODATA constants.
corresponding: Corresponding colour chromaticities computations.
difference: Colour difference computations.
examples: Examples for the sub-packages.
geometry: Geometry primitives generation.
graph: Graph for automatic colour conversions.
io: Input / output objects for reading and writing data.
models: Colour models.
notation: Colour notation systems.
phenomena: Computation of various optical phenomena.
plotting: Diagrams, figures, etc…
quality: Colour quality computation.
recovery: Reflectance recovery.
temperature: Colour temperature and correlated colour temperature computation.
utilities: Various utilities and data structures.
volume: Colourspace volumes computation and optimal colour stimuli.
Most of the public API is available from the root colour namespace:
import colour
print(colour.__all__[:5] + ['...'])
['domain_range_scale', 'get_domain_range_scale', 'set_domain_range_scale', 'CHROMATIC_ADAPTATION_METHODS', 'CHROMATIC_ADAPTATION_TRANSFORMS', '...']
The various sub-packages also expose their public API:
from pprint import pprint
for sub_package in ('adaptation', 'algebra', 'appearance', 'biochemistry',
'blindness', 'characterisation', 'colorimetry',
'constants', 'continuous', 'contrast', 'corresponding',
'difference', 'geometry', 'graph', 'io', 'models',
'notation', 'phenomena', 'plotting', 'quality',
'recovery', 'temperature', 'utilities', 'volume'):
print(sub_package.title())
pprint(getattr(colour, sub_package).__all__[:5] + ['...'])
print('\n')
Adaptation
['CHROMATIC_ADAPTATION_TRANSFORMS',
'CAT_XYZ_SCALING',
'CAT_VON_KRIES',
'CAT_BRADFORD',
'CAT_SHARP',
'...']
Algebra
['cartesian_to_spherical',
'spherical_to_cartesian',
'cartesian_to_polar',
'polar_to_cartesian',
'cartesian_to_cylindrical',
'...']
Appearance
['InductionFactors_Hunt',
'VIEWING_CONDITIONS_HUNT',
'CAM_Specification_Hunt',
'XYZ_to_Hunt',
'CAM_Specification_ATD95',
'...']
Biochemistry
['reaction_rate_MichealisMenten',
'substrate_concentration_MichealisMenten',
'...']
Blindness
['CVD_MATRICES_MACHADO2010',
'msds_cmfs_anomalous_trichromacy_Machado2009',
'matrix_anomalous_trichromacy_Machado2009',
'matrix_cvd_Machado2009',
'...']
Characterisation
['RGB_CameraSensitivities',
'RGB_DisplayPrimaries',
'MSDS_ACES_RICD',
'MSDS_CAMERA_SENSITIVITIES',
'CCS_COLOURCHECKERS',
'...']
Colorimetry
['SpectralShape',
'SPECTRAL_SHAPE_DEFAULT',
'SpectralDistribution',
'MultiSpectralDistributions',
'sds_and_msds_to_sds',
'...']
Constants
['CONSTANT_K_M',
'CONSTANT_KP_M',
'CONSTANT_AVOGADRO',
'CONSTANT_BOLTZMANN',
'CONSTANT_LIGHT_SPEED',
'...']
Continuous
['AbstractContinuousFunction', 'Signal', 'MultiSignals', '...']
Contrast
['optical_MTF_Barten1999',
'pupil_diameter_Barten1999',
'sigma_Barten1999',
'retinal_illuminance_Barten1999',
'maximum_angular_size_Barten1999',
'...']
Corresponding
['BRENEMAN_EXPERIMENTS',
'BRENEMAN_EXPERIMENT_PRIMARIES_CHROMATICITIES',
'CorrespondingColourDataset',
'CorrespondingChromaticitiesPrediction',
'corresponding_chromaticities_prediction_CIE1994',
'...']
Difference
['delta_E_CAM02LCD',
'delta_E_CAM02SCD',
'delta_E_CAM02UCS',
'delta_E_CAM16LCD',
'delta_E_CAM16SCD',
'...']
Geometry
['PLANE_TO_AXIS_MAPPING',
'primitive_grid',
'primitive_cube',
'PRIMITIVE_METHODS',
'primitive',
'...']
Graph
['CONVERSION_GRAPH',
'CONVERSION_GRAPH_NODE_LABELS',
'describe_conversion_path',
'convert',
'...']
Io
['SpectralDistribution_IESTM2714',
'AbstractLUTSequenceOperator',
'LUT1D',
'LUT3x1D',
'LUT3D',
'...']
Models
['Jab_to_JCh',
'JCh_to_Jab',
'COLOURSPACE_MODELS',
'COLOURSPACE_MODELS_AXIS_LABELS',
'XYZ_to_colourspace_model',
'...']
Notation
['MUNSELL_COLOURS_ALL',
'MUNSELL_COLOURS_1929',
'MUNSELL_COLOURS_REAL',
'MUNSELL_COLOURS',
'munsell_value',
'...']
Phenomena
['scattering_cross_section',
'rayleigh_optical_depth',
'rayleigh_scattering',
'sd_rayleigh_scattering',
'...']
Plotting
['SD_ASTMG173_ETR',
'SD_ASTMG173_GLOBAL_TILT',
'SD_ASTMG173_DIRECT_CIRCUMSOLAR',
'CONSTANTS_COLOUR_STYLE',
'CONSTANTS_ARROW_STYLE',
'...']
Quality
['SDS_TCS',
'SDS_VS',
'ColourRendering_Specification_CRI',
'colour_rendering_index',
'ColourRendering_Specification_CQS',
'...']
Recovery
['SPECTRAL_SHAPE_sRGB_MALLETT2019',
'MSDS_BASIS_FUNCTIONS_sRGB_MALLETT2019',
'SPECTRAL_SHAPE_OTSU2018',
'BASIS_FUNCTIONS_OTSU2018',
'CLUSTER_MEANS_OTSU2018',
'...']
Temperature
['xy_to_CCT_CIE_D',
'CCT_to_xy_CIE_D',
'xy_to_CCT_Hernandez1999',
'CCT_to_xy_Hernandez1999',
'xy_to_CCT_Kang2002',
'...']
Utilities
['Lookup',
'Structure',
'CaseInsensitiveMapping',
'LazyCaseInsensitiveMapping',
'handle_numpy_errors',
'...']
Volume
['OPTIMAL_COLOUR_STIMULI_ILLUMINANTS',
'is_within_macadam_limits',
'is_within_mesh_volume',
'is_within_pointer_gamut',
'generate_pulse_waves',
'...']
The codebase is documented and most docstrings have usage examples:
print(colour.temperature.CCT_to_uv_Ohno2013.__doc__)
Returns the *CIE UCS* colourspace *uv* chromaticity coordinates from given
correlated colour temperature :math:`T_{cp}`, :math:`\Delta_{uv}` and
colour matching functions using *Ohno (2013)* method.
Parameters
----------
CCT_D_uv : ndarray
Correlated colour temperature :math:`T_{cp}`, :math:`\Delta_{uv}`.
cmfs : XYZ_ColourMatchingFunctions, optional
Standard observer colour matching functions.
Returns
-------
ndarray
*CIE UCS* colourspace *uv* chromaticity coordinates.
References
----------
:cite:`Ohno2014a`
Examples
--------
>>> from colour.colorimetry import (
... SPECTRAL_SHAPE_DEFAULT, MSDS_CMFS_STANDARD_OBSERVER)
>>> cmfs = (
... MSDS_CMFS_STANDARD_OBSERVER['CIE 1931 2 Degree Standard Observer'].
... copy().align(SPECTRAL_SHAPE_DEFAULT)
... )
>>> CCT_D_uv = np.array([6507.4342201047066, 0.003223690901513])
>>> CCT_to_uv_Ohno2013(CCT_D_uv, cmfs) # doctest: +ELLIPSIS
array([ 0.1977999..., 0.3122004...])
At the core of Colour is the colour.colorimetry sub-package, it defines
the objects needed for spectral computations and many others:
pprint(colour.colorimetry.__all__)
['SpectralShape',
'SPECTRAL_SHAPE_DEFAULT',
'SpectralDistribution',
'MultiSpectralDistributions',
'sds_and_msds_to_sds',
'sds_and_msds_to_msds',
'sd_blackbody',
'blackbody_spectral_radiance',
'planck_law',
'LMS_ConeFundamentals',
'RGB_ColourMatchingFunctions',
'XYZ_ColourMatchingFunctions',
'MSDS_CMFS',
'MSDS_CMFS_LMS',
'MSDS_CMFS_RGB',
'MSDS_CMFS_STANDARD_OBSERVER',
'CCS_ILLUMINANTS',
'SDS_BASIS_FUNCTIONS_CIE_ILLUMINANT_D_SERIES',
'TVS_ILLUMINANTS_HUNTERLAB',
'SDS_ILLUMINANTS',
'CCS_LIGHT_SOURCES',
'SDS_LIGHT_SOURCES',
'SDS_LEFS',
'SDS_LEFS_PHOTOPIC',
'SDS_LEFS_SCOTOPIC',
'sd_constant',
'sd_zeros',
'sd_ones',
'msds_constant',
'msds_zeros',
'msds_ones',
'SD_GAUSSIAN_METHODS',
'sd_gaussian',
'sd_gaussian_normal',
'sd_gaussian_fwhm',
'SD_SINGLE_LED_METHODS',
'sd_single_led',
'sd_single_led_Ohno2005',
'SD_MULTI_LEDS_METHODS',
'sd_multi_leds',
'sd_multi_leds_Ohno2005',
'SD_TO_XYZ_METHODS',
'MSDS_TO_XYZ_METHODS',
'sd_to_XYZ',
'msds_to_XYZ',
'SPECTRAL_SHAPE_ASTME308',
'lagrange_coefficients_ASTME2022',
'tristimulus_weighting_factors_ASTME2022',
'adjust_tristimulus_weighting_factors_ASTME308',
'sd_to_XYZ_integration',
'sd_to_XYZ_tristimulus_weighting_factors_ASTME308',
'sd_to_XYZ_ASTME308',
'msds_to_XYZ_integration',
'msds_to_XYZ_ASTME308',
'wavelength_to_XYZ',
'BANDPASS_CORRECTION_METHODS',
'bandpass_correction',
'bandpass_correction_Stearns1988',
'sd_CIE_standard_illuminant_A',
'sd_CIE_illuminant_D_series',
'daylight_locus_function',
'sd_mesopic_luminous_efficiency_function',
'mesopic_weighting_function',
'LIGHTNESS_METHODS',
'lightness',
'lightness_Glasser1958',
'lightness_Wyszecki1963',
'lightness_CIE1976',
'lightness_Fairchild2010',
'lightness_Fairchild2011',
'intermediate_lightness_function_CIE1976',
'LUMINANCE_METHODS',
'luminance',
'luminance_Newhall1943',
'luminance_ASTMD1535',
'luminance_CIE1976',
'luminance_Fairchild2010',
'luminance_Fairchild2011',
'intermediate_luminance_function_CIE1976',
'dominant_wavelength',
'complementary_wavelength',
'excitation_purity',
'colorimetric_purity',
'luminous_flux',
'luminous_efficiency',
'luminous_efficacy',
'RGB_10_degree_cmfs_to_LMS_10_degree_cmfs',
'RGB_2_degree_cmfs_to_XYZ_2_degree_cmfs',
'RGB_10_degree_cmfs_to_XYZ_10_degree_cmfs',
'LMS_2_degree_cmfs_to_XYZ_2_degree_cmfs',
'LMS_10_degree_cmfs_to_XYZ_10_degree_cmfs',
'WHITENESS_METHODS',
'whiteness',
'whiteness_Berger1959',
'whiteness_Taube1960',
'whiteness_Stensby1968',
'whiteness_ASTME313',
'whiteness_Ganz1979',
'whiteness_CIE2004',
'YELLOWNESS_METHODS',
'yellowness',
'yellowness_ASTMD1925',
'yellowness_ASTME313']
Colour computations leverage a comprehensive quantity of datasets available
in most sub-packages, for example the colour.colorimetry.datasets defines
the following components:
pprint(colour.colorimetry.datasets.__all__)
['MSDS_CMFS',
'MSDS_CMFS_LMS',
'MSDS_CMFS_RGB',
'MSDS_CMFS_STANDARD_OBSERVER',
'CCS_ILLUMINANTS',
'SDS_BASIS_FUNCTIONS_CIE_ILLUMINANT_D_SERIES',
'TVS_ILLUMINANTS_HUNTERLAB',
'SDS_ILLUMINANTS',
'CCS_LIGHT_SOURCES',
'SDS_LIGHT_SOURCES',
'SDS_LEFS',
'SDS_LEFS_PHOTOPIC',
'SDS_LEFS_SCOTOPIC']
From Spectral Distribution¶
Whether it be a sample spectral distribution, colour matching functions or
illuminants, spectral data is manipulated using an object built with the
colour.SpectralDistribution class or based on it:
# Defining a sample spectral distribution data.
data_sample = {
380: 0.048,
385: 0.051,
390: 0.055,
395: 0.060,
400: 0.065,
405: 0.068,
410: 0.068,
415: 0.067,
420: 0.064,
425: 0.062,
430: 0.059,
435: 0.057,
440: 0.055,
445: 0.054,
450: 0.053,
455: 0.053,
460: 0.052,
465: 0.052,
470: 0.052,
475: 0.053,
480: 0.054,
485: 0.055,
490: 0.057,
495: 0.059,
500: 0.061,
505: 0.062,
510: 0.065,
515: 0.067,
520: 0.070,
525: 0.072,
530: 0.074,
535: 0.075,
540: 0.076,
545: 0.078,
550: 0.079,
555: 0.082,
560: 0.087,
565: 0.092,
570: 0.100,
575: 0.107,
580: 0.115,
585: 0.122,
590: 0.129,
595: 0.134,
600: 0.138,
605: 0.142,
610: 0.146,
615: 0.150,
620: 0.154,
625: 0.158,
630: 0.163,
635: 0.167,
640: 0.173,
645: 0.180,
650: 0.188,
655: 0.196,
660: 0.204,
665: 0.213,
670: 0.222,
675: 0.231,
680: 0.242,
685: 0.251,
690: 0.261,
695: 0.271,
700: 0.282,
705: 0.294,
710: 0.305,
715: 0.318,
720: 0.334,
725: 0.354,
730: 0.372,
735: 0.392,
740: 0.409,
745: 0.420,
750: 0.436,
755: 0.450,
760: 0.462,
765: 0.465,
770: 0.448,
775: 0.432,
780: 0.421}
sd = colour.SpectralDistribution(data_sample, name='Sample')
print(repr(sd))
SpectralDistribution([[ 3.80000000e+02, 4.80000000e-02],
[ 3.85000000e+02, 5.10000000e-02],
[ 3.90000000e+02, 5.50000000e-02],
[ 3.95000000e+02, 6.00000000e-02],
[ 4.00000000e+02, 6.50000000e-02],
[ 4.05000000e+02, 6.80000000e-02],
[ 4.10000000e+02, 6.80000000e-02],
[ 4.15000000e+02, 6.70000000e-02],
[ 4.20000000e+02, 6.40000000e-02],
[ 4.25000000e+02, 6.20000000e-02],
[ 4.30000000e+02, 5.90000000e-02],
[ 4.35000000e+02, 5.70000000e-02],
[ 4.40000000e+02, 5.50000000e-02],
[ 4.45000000e+02, 5.40000000e-02],
[ 4.50000000e+02, 5.30000000e-02],
[ 4.55000000e+02, 5.30000000e-02],
[ 4.60000000e+02, 5.20000000e-02],
[ 4.65000000e+02, 5.20000000e-02],
[ 4.70000000e+02, 5.20000000e-02],
[ 4.75000000e+02, 5.30000000e-02],
[ 4.80000000e+02, 5.40000000e-02],
[ 4.85000000e+02, 5.50000000e-02],
[ 4.90000000e+02, 5.70000000e-02],
[ 4.95000000e+02, 5.90000000e-02],
[ 5.00000000e+02, 6.10000000e-02],
[ 5.05000000e+02, 6.20000000e-02],
[ 5.10000000e+02, 6.50000000e-02],
[ 5.15000000e+02, 6.70000000e-02],
[ 5.20000000e+02, 7.00000000e-02],
[ 5.25000000e+02, 7.20000000e-02],
[ 5.30000000e+02, 7.40000000e-02],
[ 5.35000000e+02, 7.50000000e-02],
[ 5.40000000e+02, 7.60000000e-02],
[ 5.45000000e+02, 7.80000000e-02],
[ 5.50000000e+02, 7.90000000e-02],
[ 5.55000000e+02, 8.20000000e-02],
[ 5.60000000e+02, 8.70000000e-02],
[ 5.65000000e+02, 9.20000000e-02],
[ 5.70000000e+02, 1.00000000e-01],
[ 5.75000000e+02, 1.07000000e-01],
[ 5.80000000e+02, 1.15000000e-01],
[ 5.85000000e+02, 1.22000000e-01],
[ 5.90000000e+02, 1.29000000e-01],
[ 5.95000000e+02, 1.34000000e-01],
[ 6.00000000e+02, 1.38000000e-01],
[ 6.05000000e+02, 1.42000000e-01],
[ 6.10000000e+02, 1.46000000e-01],
[ 6.15000000e+02, 1.50000000e-01],
[ 6.20000000e+02, 1.54000000e-01],
[ 6.25000000e+02, 1.58000000e-01],
[ 6.30000000e+02, 1.63000000e-01],
[ 6.35000000e+02, 1.67000000e-01],
[ 6.40000000e+02, 1.73000000e-01],
[ 6.45000000e+02, 1.80000000e-01],
[ 6.50000000e+02, 1.88000000e-01],
[ 6.55000000e+02, 1.96000000e-01],
[ 6.60000000e+02, 2.04000000e-01],
[ 6.65000000e+02, 2.13000000e-01],
[ 6.70000000e+02, 2.22000000e-01],
[ 6.75000000e+02, 2.31000000e-01],
[ 6.80000000e+02, 2.42000000e-01],
[ 6.85000000e+02, 2.51000000e-01],
[ 6.90000000e+02, 2.61000000e-01],
[ 6.95000000e+02, 2.71000000e-01],
[ 7.00000000e+02, 2.82000000e-01],
[ 7.05000000e+02, 2.94000000e-01],
[ 7.10000000e+02, 3.05000000e-01],
[ 7.15000000e+02, 3.18000000e-01],
[ 7.20000000e+02, 3.34000000e-01],
[ 7.25000000e+02, 3.54000000e-01],
[ 7.30000000e+02, 3.72000000e-01],
[ 7.35000000e+02, 3.92000000e-01],
[ 7.40000000e+02, 4.09000000e-01],
[ 7.45000000e+02, 4.20000000e-01],
[ 7.50000000e+02, 4.36000000e-01],
[ 7.55000000e+02, 4.50000000e-01],
[ 7.60000000e+02, 4.62000000e-01],
[ 7.65000000e+02, 4.65000000e-01],
[ 7.70000000e+02, 4.48000000e-01],
[ 7.75000000e+02, 4.32000000e-01],
[ 7.80000000e+02, 4.21000000e-01]],
interpolator=SpragueInterpolator,
interpolator_args={},
extrapolator=Extrapolator,
extrapolator_args={u'right': None, u'method': u'Constant', u'left': None})
The sample spectral distribution can be easily plotted against the visible spectrum:
# Plotting the sample spectral distribution.
plot_single_sd(sd)
With the sample spectral distribution defined, its shape is retrieved as follows:
# Displaying the sample spectral distribution shape.
print(sd.shape)
(380.0, 780.0, 5.0)
The returned shape is an instance of the colour.SpectralShape class:
repr(sd.shape)
'SpectralShape(380.0, 780.0, 5.0)'
The colour.SpectralShape class is used throughout Colour to define
spectral dimensions and is instantiated as follows:
# Using *colour.SpectralShape* with iteration.
shape = colour.SpectralShape(start=0, end=10, interval=1)
for wavelength in shape:
print(wavelength)
# *colour.SpectralShape.range* method is providing the complete range of values.
shape = colour.SpectralShape(0, 10, 0.5)
shape.range()
0.0
1.0
2.0
3.0
4.0
5.0
6.0
7.0
8.0
9.0
10.0
array([ 0. , 0.5, 1. , 1.5, 2. , 2.5, 3. , 3.5, 4. ,
4.5, 5. , 5.5, 6. , 6.5, 7. , 7.5, 8. , 8.5,
9. , 9.5, 10. ])
Colour defines three convenient objects to create constant spectral distributions:
colour.sd_constantcolour.sd_zeroscolour.sd_ones
# Defining a constant spectral distribution.
sd_constant = colour.sd_constant(100)
print('"Constant Spectral Distribution"')
print(sd_constant.shape)
print(sd_constant[400])
# Defining a zeros filled spectral distribution.
print('\n"Zeros Filled Spectral Distribution"')
sd_zeros = colour.sd_zeros()
print(sd_zeros.shape)
print(sd_zeros[400])
# Defining a ones filled spectral distribution.
print('\n"Ones Filled Spectral Distribution"')
sd_ones = colour.sd_ones()
print(sd_ones.shape)
print(sd_ones[400])
"Constant Spectral Distribution"
(360.0, 780.0, 1.0)
100.0
"Zeros Filled Spectral Distribution"
(360.0, 780.0, 1.0)
0.0
"Ones Filled Spectral Distribution"
(360.0, 780.0, 1.0)
1.0
By default the shape used by colour.sd_constant,
colour.sd_zeros and colour.sd_ones is the one defined by the
colour.DEFAULT_SPECTRAL_SHAPE attribute and based on ASTM E308-15
practise shape.
print(repr(colour.DEFAULT_SPECTRAL_SHAPE))
SpectralShape(360, 780, 1)
A custom shape can be passed to construct a constant spectral distribution with user defined dimensions:
colour.sd_ones(colour.SpectralShape(400, 700, 5))[450]
1.0
The colour.SpectralDistribution class supports the following
arithmetical operations:
addition
subtraction
multiplication
division
exponentiation
sd1 = colour.sd_ones()
print('"Ones Filled Spectral Distribution"')
print(sd1[400])
print('\n"x2 Constant Multiplied"')
print((sd1 * 2)[400])
print('\n"+ Spectral Distribution"')
print((sd1 + colour.sd_ones())[400])
"Ones Filled Spectral Distribution"
1.0
"x2 Constant Multiplied"
2.0
"+ Spectral Distribution"
2.0
Often interpolation of the spectral distribution is required, this is achieved
with the colour.SpectralDistribution.interpolate method. Depending on the
wavelengths uniformity, the default interpolation method will differ.
Following CIE 167:2005 recommendation: The method developed by
Sprague (1880) should be used for interpolating functions having a uniformly
spaced independent variable and a Cubic Spline method for non-uniformly spaced
independent variable [].
The uniformity of the sample spectral distribution is assessed as follows:
# Checking the sample spectral distribution uniformity.
print(sd.is_uniform())
True
In this case, since the sample spectral distribution is uniform the
interpolation defaults to the colour.SpragueInterpolator interpolator.
Note
Interpolation happens in place and may alter the original data, use the
colour.SpectralDistribution.copy method to generate a copy of the
spectral distribution before interpolation.
# Copying the sample spectral distribution.
sd_copy = sd.copy()
# Interpolating the copied sample spectral distribution.
sd_copy.interpolate(colour.SpectralShape(400, 770, 1))
sd_copy[401]
0.065809599999999996
# Comparing the interpolated spectral distribution with the original one.
plot_multi_sds([sd, sd_copy], bounding_box=[730,780, 0.25, 0.5])
Extrapolation although dangerous can be used to help aligning two spectral distributions together. CIE publication CIE 15:2004 “Colorimetry” recommends that unmeasured values may be set equal to the nearest measured value of the appropriate quantity in truncation []:
# Extrapolating the copied sample spectral distribution.
sd_copy.extrapolate(colour.SpectralShape(340, 830))
sd_copy[340], sd_copy[830]
(0.065000000000000002, 0.44800000000000018)
The underlying interpolator can be swapped for any of the Colour interpolators:
pprint([
export for export in colour.algebra.interpolation.__all__
if 'Interpolator' in export
])
[u'KernelInterpolator',
u'LinearInterpolator',
u'SpragueInterpolator',
u'CubicSplineInterpolator',
u'PchipInterpolator',
u'NullInterpolator']
# Changing interpolator while trimming the copied spectral distribution.
sd_copy.interpolate(
colour.SpectralShape(400, 700, 10), interpolator=colour.LinearInterpolator)
SpectralDistribution([[ 4.00000000e+02, 6.50000000e-02],
[ 4.10000000e+02, 6.80000000e-02],
[ 4.20000000e+02, 6.40000000e-02],
[ 4.30000000e+02, 5.90000000e-02],
[ 4.40000000e+02, 5.50000000e-02],
[ 4.50000000e+02, 5.30000000e-02],
[ 4.60000000e+02, 5.20000000e-02],
[ 4.70000000e+02, 5.20000000e-02],
[ 4.80000000e+02, 5.40000000e-02],
[ 4.90000000e+02, 5.70000000e-02],
[ 5.00000000e+02, 6.10000000e-02],
[ 5.10000000e+02, 6.50000000e-02],
[ 5.20000000e+02, 7.00000000e-02],
[ 5.30000000e+02, 7.40000000e-02],
[ 5.40000000e+02, 7.60000000e-02],
[ 5.50000000e+02, 7.90000000e-02],
[ 5.60000000e+02, 8.70000000e-02],
[ 5.70000000e+02, 1.00000000e-01],
[ 5.80000000e+02, 1.15000000e-01],
[ 5.90000000e+02, 1.29000000e-01],
[ 6.00000000e+02, 1.38000000e-01],
[ 6.10000000e+02, 1.46000000e-01],
[ 6.20000000e+02, 1.54000000e-01],
[ 6.30000000e+02, 1.63000000e-01],
[ 6.40000000e+02, 1.73000000e-01],
[ 6.50000000e+02, 1.88000000e-01],
[ 6.60000000e+02, 2.04000000e-01],
[ 6.70000000e+02, 2.22000000e-01],
[ 6.80000000e+02, 2.42000000e-01],
[ 6.90000000e+02, 2.61000000e-01],
[ 7.00000000e+02, 2.82000000e-01]],
interpolator=SpragueInterpolator,
interpolator_args={},
extrapolator=Extrapolator,
extrapolator_args={u'right': None, u'method': u'Constant', u'left': None})
The extrapolation behaviour can be changed for Linear method instead
of the Constant default method or even use arbitrary constant left
and right values:
# Extrapolating the copied sample spectral distribution with *Linear* method.
sd_copy.extrapolate(
colour.SpectralShape(340, 830),
extrapolator_args={'method': 'Linear',
'right': 0})
sd_copy[340], sd_copy[830]
(0.046999999999999348, 0.0)
Aligning a spectral distribution is a convenient way to first interpolates the current data within its original bounds, then, if required, extrapolate any missing values to match the requested shape:
# Aligning the cloned sample spectral distribution.
# The spectral distribution is first trimmed as above.
sd_copy.interpolate(colour.SpectralShape(400, 700))
sd_copy.align(colour.SpectralShape(340, 830, 5))
sd_copy[340], sd_copy[830]
(0.065000000000000002, 0.28199999999999975)
The colour.SpectralDistribution class also supports various arithmetic
operations like addition, subtraction, multiplication, division or
exponentiation with numeric and array_like variables or other
colour.SpectralDistribution class instances:
sd = colour.SpectralDistribution({
410: 0.25,
420: 0.50,
430: 0.75,
440: 1.0,
450: 0.75,
460: 0.50,
480: 0.25
})
print((sd.copy() + 1).values)
print((sd.copy() * 2).values)
print((sd * [0.35, 1.55, 0.75, 2.55, 0.95, 0.65, 0.15]).values)
print((sd * colour.sd_constant(2, sd.shape) * colour.sd_constant(3, sd.shape)).values)
[ 1.25 1.5 1.75 2. 1.75 1.5 1.25]
[ 0.5 1. 1.5 2. 1.5 1. 0.5]
[ 0.0875 0.775 0.5625 2.55 0.7125 0.325 0.0375]
[ 1.5 3. 4.5 6. 4.5 3. nan 1.5]
The spectral distribution can be normalised with an arbitrary factor:
print(sd.normalise().values)
print(sd.normalise(100).values)
[ 0.25 0.5 0.75 1. 0.75 0.5 0.25]
[ 25. 50. 75. 100. 75. 50. 25.]
A the heart of the colour.SpectralDistribution class is the
colour.continuous.Signal class which implements the
colour.continuous.Signal.function method.
Evaluating the function for any independent domain \(x \in \mathbb{R}\) variable returns a corresponding range \(y \in \mathbb{R}\) variable.
It adopts an interpolating function encapsulated inside an extrapolating
function. The resulting function independent domain, stored as discrete
values in the colour.continuous.Signal.domain attribute corresponds
with the function dependent and already known range stored in the
colour.continuous.Signal.range attribute.
Describing the colour.continuous.Signal class is beyond the scope of
this tutorial but the core capability can be described.
import numpy as np
range_ = np.linspace(10, 100, 10)
signal = colour.continuous.Signal(range_)
print(repr(signal))
Signal([[ 0., 10.],
[ 1., 20.],
[ 2., 30.],
[ 3., 40.],
[ 4., 50.],
[ 5., 60.],
[ 6., 70.],
[ 7., 80.],
[ 8., 90.],
[ 9., 100.]],
interpolator=KernelInterpolator,
interpolator_args={},
extrapolator=Extrapolator,
extrapolator_args={u'right': nan, u'method': u'Constant', u'left': nan})
# Returning the corresponding range *y* variable for any arbitrary independent domain *x* variable.
signal[np.random.uniform(0, 9, 10)]
array([ 55.91309735, 65.4172615 , 65.54495059, 88.17819416,
61.88860248, 10.53878826, 55.25130534, 46.14659783,
86.41406136, 84.59897703])
Convert to Tristimulus Values¶
From a given spectral distribution, CIE XYZ tristimulus values can be calculated:
sd = colour.SpectralDistribution(data_sample)
cmfs = colour.MSDS_CMFS['CIE 1931 2 Degree Standard Observer']
illuminant = colour.SDS_ILLUMINANTS['D65']
# Calculating the sample spectral distribution *CIE XYZ* tristimulus values.
XYZ = colour.sd_to_XYZ(sd, cmfs, illuminant)
print(XYZ)
[ 10.97085572 9.70278591 6.05562778]
From CIE XYZ Colourspace¶
CIE XYZ is the central colourspace for Colour Science from which many computations are available, expanding to even more computations:
# Displaying objects interacting directly with the *CIE XYZ* colourspace.
pprint([name for name in colour.__all__ if name.startswith('XYZ_to')])
['XYZ_to_ATD95',
'XYZ_to_CAM16',
'XYZ_to_CIECAM02',
'XYZ_to_Hunt',
'XYZ_to_LLAB',
'XYZ_to_Nayatani95',
'XYZ_to_RLAB',
'XYZ_to_Hunter_Lab',
'XYZ_to_Hunter_Rdab',
'XYZ_to_IPT',
'XYZ_to_JzAzBz',
'XYZ_to_K_ab_HunterLab1966',
'XYZ_to_Lab',
'XYZ_to_Luv',
'XYZ_to_OSA_UCS',
'XYZ_to_RGB',
'XYZ_to_UCS',
'XYZ_to_UVW',
'XYZ_to_hdr_CIELab',
'XYZ_to_hdr_IPT',
'XYZ_to_sRGB',
'XYZ_to_xy',
'XYZ_to_xyY',
'XYZ_to_sd']
Convert to Display Colours¶
CIE XYZ tristimulus values can be converted into sRGB colourspace RGB values in order to display them on screen:
# The output domain of *colour.sd_to_XYZ* is [0, 100] and the input
# domain of *colour.XYZ_to_sRGB* is [0, 1]. It needs to be accounted for,
# thus the input *CIE XYZ* tristimulus values are scaled.
RGB = colour.XYZ_to_sRGB(XYZ / 100)
print(RGB)
[ 0.45675795 0.30986982 0.24861924]
# Plotting the *sRGB* colourspace colour of the *Sample* spectral distribution.
plot_single_colour_swatch(
ColourSwatch('Sample', RGB),
text_kwargs={'size': 'x-large'})
Generate Colour Rendition Charts¶
Likewise, colour values from a colour rendition chart sample can be computed.
Note
This is useful for render time checks in the VFX industry, where a synthetic colour chart can be inserted into a render to ensure the colour management is acting as expected.
The colour.characterisation sub-package contains the dataset for
various colour rendition charts:
# Colour rendition charts chromaticity coordinates.
print(sorted(colour.characterisation.CCS_COLOURCHECKERS.keys()))
# Colour rendition charts spectral distributions.
print(sorted(colour.characterisation.SDS_COLOURCHECKERS.keys()))
['BabelColor Average', 'ColorChecker 1976', 'ColorChecker 2005', 'ColorChecker24 - After November 2014', 'ColorChecker24 - Before November 2014', 'babel_average', 'cc2005', 'cca2014', 'ccb2014']
['BabelColor Average', 'ColorChecker N Ohta', 'babel_average', 'cc_ohta']
Note
The above cc2005, babel_average and cc_ohta keys are
convenient aliases for respectively ColorChecker 2005, BabelColor Average
and ColorChecker N Ohta keys.
# Plotting the *sRGB* colourspace colour of *neutral 5 (.70 D)* patch.
patch_name = 'neutral 5 (.70 D)'
patch_sd = colour.SDS_COLOURCHECKERS['ColorChecker N Ohta'][patch_name]
XYZ = colour.sd_to_XYZ(patch_sd, cmfs, illuminant)
RGB = colour.XYZ_to_sRGB(XYZ / 100)
plot_single_colour_swatch(
ColourSwatch(patch_name.title(), RGB),
text_kwargs={'size': 'x-large'})
Colour defines a convenient plotting object to draw synthetic colour rendition charts figures:
plot_single_colour_checker(
colour_checker='ColorChecker 2005', text_kwargs={'visible': False})
Convert to Chromaticity Coordinates¶
Given a spectral distribution, chromaticity coordinates CIE xy can be computed
using the colour.XYZ_to_xy definition:
# Computing *CIE xy* chromaticity coordinates for the *neutral 5 (.70 D)* patch.
xy = colour.XYZ_to_xy(XYZ)
print(xy)
[ 0.31259787 0.32870029]
Chromaticity coordinates CIE xy can be plotted into the CIE 1931 Chromaticity Diagram:
import matplotlib.pyplot as plt
# Plotting the *CIE 1931 Chromaticity Diagram*.
# The argument *standalone=False* is passed so that the plot doesn't get
# displayed and can be used as a basis for other plots.
plot_chromaticity_diagram_CIE1931(standalone=False)
# Plotting the *CIE xy* chromaticity coordinates.
x, y = xy
plt.plot(x, y, 'o-', color='white')
# Annotating the plot.
plt.annotate(patch_sd.name.title(),
xy=xy,
xytext=(-50, 30),
textcoords='offset points',
arrowprops=dict(arrowstyle='->', connectionstyle='arc3, rad=-0.2'))
# Displaying the plot.
render(
standalone=True,
limits=(-0.1, 0.9, -0.1, 0.9),
x_tighten=True,
y_tighten=True)
See More¶
Basics¶
This page puts an emphasis on basic concepts of Colour, those are important to understand.
Table of Contents
Object Name Categorisation¶
The API tries to bundle the objects by categories by naming them with common prefixes which makes introspection and auto-completion easier.
For example, in IPython or Jupyter Notebook, most of the definitions pertaining to the spectral distribution handling can be found as follows:
In [1]: import colour
In [2]: colour.sd_
sd_blackbody() sd_gaussian() sd_rayleigh_scattering() sd_zeros
sd_CIE_illuminant_D_series() sd_mesopic_luminous_efficiency_function() sd_single_led()
sd_CIE_standard_illuminant_A() sd_multi_leds() sd_to_aces_relative_exposure_values()
sd_constant() sd_ones() sd_to_XYZ
Likewise, for the spectral distribution handling related attributes:
In [2]: colour.SD
SD_GAUSSIAN_METHODS SD_TO_XYZ_METHODS SDS_ILLUMINANTS SDS_LIGHT_SOURCES
SD_MULTI_LEDS_METHODS SDS_COLOURCHECKERS SDS_LEFS
SD_SINGLE_LED_METHODS SDS_FILTERS SDS_LENSES
Similarly, all the RGB colourspaces can be individually accessed from the
colour.models namespace:
In [2]: colour.models.RGB_COLOURSPACE
RGB_COLOURSPACE_ACES2065_1 RGB_COLOURSPACE_ACESPROXY RGB_COLOURSPACE_APPLE_RGB RGB_COLOURSPACE_BT470_525
RGB_COLOURSPACE_ACESCC RGB_COLOURSPACE_ADOBE_RGB1998 RGB_COLOURSPACE_BEST_RGB RGB_COLOURSPACE_BT470_625
RGB_COLOURSPACE_ACESCCT RGB_COLOURSPACE_ADOBE_WIDE_GAMUT_RGB RGB_COLOURSPACE_BETA_RGB RGB_COLOURSPACE_BT709 >
RGB_COLOURSPACE_ACESCG RGB_COLOURSPACE_ALEXA_WIDE_GAMUT RGB_COLOURSPACE_BT2020 RGB_COLOURSPACE_CIE_RGB
Abbreviations¶
The following abbreviations are in use in Colour:
CAM : Colour Appearance Model
CCS : Chromaticity Coordinates
CCTF : Colour Component Transfer Function
CCT : Correlated Colour Temperature
CMY : Cyan, Magenta, Yellow
CMYK : Cyan, Magenta, Yellow, Black
CVD : Colour Vision Deficiency
CV : Code Value
EOTF : Electro-Optical Transfer Function
IDT : Input Device Transform
MSDS : Multi-Spectral Distributions
OETF : Optical-Electrical Transfer Function
OOTF : Optical-Optical Transfer Function
SD : Spectral Distribution
TVS : Tristimulus Values
N-Dimensional Array Support¶
Most of Colour definitions are fully vectorised and support n-dimensional array by leveraging Numpy.
While it is recommended to use ndarray as input for the API objects, it is possible to use tuples or lists:
import colour
xyY = (0.4316, 0.3777, 0.1008)
colour.xyY_to_XYZ(xyY)
array([ 0.11518475, 0.1008 , 0.05089373])
xyY = [0.4316, 0.3777, 0.1008]
colour.xyY_to_XYZ(xyY)
array([ 0.11518475, 0.1008 , 0.05089373])
xyY = [
(0.4316, 0.3777, 0.1008),
(0.4316, 0.3777, 0.1008),
(0.4316, 0.3777, 0.1008),
]
colour.xyY_to_XYZ(xyY)
array([[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373]])
As shown in the above example, there is widespread support for n-dimensional arrays:
import numpy as np
xyY = np.array([0.4316, 0.3777, 0.1008])
xyY = np.tile(xyY, (6, 1))
colour.xyY_to_XYZ(xyY)
array([[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373]])
colour.xyY_to_XYZ(xyY.reshape([2, 3, 3]))
array([[[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373]],
[[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373],
[ 0.11518475, 0.1008 , 0.05089373]]])
Which enables image processing:
RGB = colour.read_image('_static/Logo_Small_001.png')
RGB = RGB[..., 0:3] # Discarding alpha channel.
XYZ = colour.sRGB_to_XYZ(RGB)
colour.plotting.plot_image(XYZ, text_kwargs={'text': 'sRGB to XYZ'})
Spectral Representation and Continuous Signal¶
Floating Point Wavelengths¶
Colour current representation of spectral data is atypical and has been influenced by the failures and shortcomings of the previous implementation that required less than ideal code to support floating point wavelengths. Wavelengths should not have to be defined as integer values and it is effectively common to get data from instruments whose domain is returned as floating point values.
For example, the data from an Ocean Insight (Optics) STS-VIS spectrometer is typically saved with 3 digits decimal precision:
Data from Subt2_14-36-15-210.txt Node
Date: Sat Nov 17 14:36:15 NZDT 2018
User: kelsolaar
Spectrometer: S12286
Trigger mode: 0
Resolution mode: 1024 pixels
Integration Time (sec): 5.000000E0
Scans to average: 3
Nonlinearity correction enabled: true
Boxcar width: 3
Baseline correction enabled: true
XAxis mode: Wavelengths
Number of Pixels in Spectrum: 1024
>>>>>Begin Spectral Data<<<<<
338.028 279.71
338.482 285.43
338.936 291.33
...
821.513 3112.65
822.008 3133.74
822.503 3107.11
A solution to the problem is to quantize the data at integer values but it is often non-desirable. The spectra representation implementation prior to Colour 0.3.11 was relying on a custom mutable mapping which was allowing to retrieve decimal keys within a given precision:
data_1 = {0.1999999998: 'Nemo', 0.2000000000: 'John'}
apm_1 = ArbitraryPrecisionMapping(data_1, key_decimals=10)
tuple(apm_1.keys())
(0.1999999998, 0.2)
apm_2 = ArbitraryPrecisionMapping(data_1, key_decimals=7)
tuple(apm_2.keys())
(0.2,)
While functional, the approach was brittle and not elegant which triggered a significant amount of rework.
Continuous Signal¶
All the spectral distributions in Colour are instances of the
colour.SpectralDistribution class (or its sub-classes), a sub-class of
the colour.continuous.Signal class which is itself an implementation
of the colour.continuous.AbstractContinuousFunction ABCMeta
class:
Likewise, the multi-spectral distributions are instances
colour.MultiSpectralDistributions class (or its sub-classes), a
sub-class of the colour.continuous.MultiSignals class which is a
container for multiple colour.continuous.Signal sub-class instances
and also implements the colour.continuous.AbstractContinuousFunction
ABCMeta class.
The colour.continuous.Signal class implements the
Signal.function() method so that evaluating the function for any
independent domain \(x \in\mathbb{R}\) variable returns a corresponding
range \(y \in\mathbb{R}\) variable.
It adopts an interpolating function encapsulated inside an extrapolating
function. The resulting function independent domain, stored as discrete values
in the colour.continuous.Signal.domain attribute corresponds with the
function dependent and already known range stored in the
colour.continuous.Signal.range attribute.
Consequently, it is possible to get the value of a spectral distribution at any given wavelength:
data = {
500: 0.0651,
520: 0.0705,
540: 0.0772,
560: 0.0870,
580: 0.1128,
600: 0.1360
}
sd = colour.SpectralDistribution(data)
sd[555.5]
0.083453673782958995
Getting, Setting, Indexing and Slicing¶
Attention
Indexing a spectral distribution (or multi-spectral distribution) with a numeric (or a numeric sequence) returns the corresponding value(s). Indexing a spectral distribution (or multi-spectral distribution) with a slice returns the values for the corresponding wavelength indexes.
While it is tempting to think that the colour.SpectralDistribution
and colour.MultiSpectralDistributions classes behave like Numpy’s
ndarray,
they do not entirely and some peculiarities exist that make them different.
An important difference lies in the behaviour with respect to getting and setting the values of the data.
Getting the value(s) for a single (or multiple wavelengths) is done by indexing
the colour.SpectralDistribution (or
colour.MultiSpectralDistributions) class with the a single numeric
or array of numeric wavelengths, e.g. sd[555.5] or
sd[555.25, 555.25, 555.75].
However, if getting the values using a slice class instance, e.g.
sd[0:3], the underlying discrete values for the indexes represented by the
slice class instance are returned instead.
As shown in the previous section, getting the value of a wavelength is done as follows:
data = {
500: 0.0651,
520: 0.0705,
540: 0.0772,
560: 0.0870,
580: 0.1128,
600: 0.1360
}
sd = colour.SpectralDistribution(data)
sd[555]
0.083135180664062502,
Multiple wavelength values can be retrieved as follows:
sd[(555.0, 556.25, 557.5, 558.75, 560.0)]
array([ 0.08313518, 0.08395997, 0.08488108, 0.085897 , 0.087 ])
However, slices will return the values for the corresponding wavelength indexes:
sd[0:3]
array([ 0.0651, 0.0705, 0.0772])
sd[:]
array([ 0.0651, 0.0705, 0.0772, 0.087 , 0.1128, 0.136 ])
Note
Indexing a multi-spectral distribution is achieved similarly, it can however be sliced along multiple axes because the data is2-dimensional, e.g. msds[0:3, 0:2].
A copy of the underlying colour.SpectralDistribution and
colour.MultiSpectralDistributions classes discretized data can be
accessed via the wavelengths and values properties. However, it cannot
be changed directly via the properties or slicing:
Attention
The data returned by the wavelengths and values properties is a
copy of the underlying colour.SpectralDistribution and
colour.MultiSpectralDistributions classes discretized data: It
can only be changed indirectly.
data = {
500: 0.0651,
520: 0.0705,
540: 0.0772,
560: 0.0870,
580: 0.1128,
600: 0.1360
}
sd = colour.SpectralDistribution(data)
# Note: The wavelength 500nm is at index 0.
sd.values[0] = 0
sd[500]
0.065100000000000019
Instead, the values can be set indirectly:
values = sd.values
values[0] = 0
sd.values = values
sd.values
array([ 0. , 0.0705, 0.0772, 0.087 , 0.1128, 0.136 ])
Domain-Range Scales¶
Note
This section contains important information.
Colour adopts 4 main input domains and output ranges:
Scalars usually in domain-range [0, 1] (or [0, 10] for Munsell Value).
Percentages usually in domain-range [0, 100].
Degrees usually in domain-range [0, 360].
Integers usually in domain-range [0, 2**n -1] where n is the bit depth.
It is error prone but it is also a direct consequence of the inconsistency of the colour science field itself. We have discussed at length about this and we were leaning toward normalisation of the whole API to domain-range [0, 1], we never committed for reasons highlighted by the following points:
Colour Scientist performing computations related to Munsell Renotation System would be very surprised if the output Munsell Value was in range [0, 1] or [0, 100].
A Visual Effect Industry artist would be astonished to find out that conversion from CIE XYZ to sRGB was yielding values in range [0, 100].
However benefits of having a consistent and predictable domain-range scale are numerous thus with Colour 0.3.12 we have introduced a mechanism to allow users to work within one of the two available domain-range scales.
Scale - Reference¶
‘Reference’ is the default domain-range scale of Colour, objects adopt the implemented reference, i.e. paper, publication, etc.., domain-range scale.
The ‘Reference’ domain-range scale is inconsistent, e.g. colour appearance
models, spectral conversions are typically in domain-range [0, 100] while RGB
models will operate in domain-range [0, 1]. Some objects, e.g.
colour.colorimetry.lightness_Fairchild2011() definition have mismatched
domain-range: input domain [0, 1] and output range [0, 100].
Scale - 1¶
‘1’ is a domain-range scale converting all the relevant objects from Colour public API to domain-range [0, 1]:
Scalars in domain-range [0, 10], e.g Munsell Value are scaled by 10.
Percentages in domain-range [0, 100] are scaled by 100.
Degrees in domain-range [0, 360] are scaled by 360.
Integers in domain-range [0, 2**n -1] where n is the bit depth are scaled by 2**n -1.
Dimensionless values are unaffected and are indicated with DN.
Unaffected values are unaffected and are indicated with UN.
Warning
The conversion to ‘1’ domain-range scale is a soft normalisation and
similarly to the ‘Reference’ domain-range scale it is normal to
encounter values exceeding 1, e.g. High Dynamic Range Imagery (HDRI) or
negative values, e.g. out-of-gamut RGB colourspace values. Some definitions
such as colour.models.eotf_ST2084() which decodes absolute luminance
values are not affected by any domain-range scales and are indicated with
UN.
Understanding the Domain-Range Scale of an Object¶
Using colour.adaptation.chromatic_adaptation_CIE1994() definition
docstring as an example, the Notes section features two tables.
The first table is for the domain, and lists the input arguments affected by the two domain-range scales and which normalisation they should adopt depending the domain-range scale in use:
Domain |
Scale - Reference |
Scale - 1 |
|---|---|---|
|
[0, 100] |
[0, 1] |
|
[0, 100] |
[0, 1] |
The second table is for the range and lists the return value of the definition:
Range |
Scale - Reference |
Scale - 1 |
|---|---|---|
|
[0, 100] |
[0, 1] |
Working with the Domain-Range Scales¶
The current domain-range scale is returned with the
colour.get_domain_range_scale() definition:
import colour
colour.get_domain_range_scale()
u'reference'
Changing from the ‘Reference’ default domain-range scale to ‘1’ is done
with the colour.set_domain_range_scale() definition:
XYZ_1 = [28.00, 21.26, 5.27]
xy_o1 = [0.4476, 0.4074]
xy_o2 = [0.3127, 0.3290]
Y_o = 20
E_o1 = 1000
E_o2 = 1000
colour.adaptation.chromatic_adaptation_CIE1994(XYZ_1, xy_o1, xy_o2, Y_o, E_o1, E_o2)
array([ 24.03379521, 21.15621214, 17.64301199])
colour.set_domain_range_scale('1')
XYZ_1 = [0.2800, 0.2126, 0.0527]
Y_o = 0.2
colour.adaptation.chromatic_adaptation_CIE1994(XYZ_1, xy_o1, xy_o2, Y_o, E_o1, E_o2)
array([ 0.24033795, 0.21156212, 0.17643012])
The output tristimulus values with the ‘1’ domain-range scale are equal to those from ‘Reference’ default domain-range scale divided by 100.
Passing incorrectly scaled values to the
colour.adaptation.chromatic_adaptation_CIE1994() definition
would result in unexpected values and a warning in that case:
colour.set_domain_range_scale('Reference')
colour.adaptation.chromatic_adaptation_CIE1994(XYZ_1, xy_o1, xy_o2, Y_o, E_o1, E_o2)
File "<ipython-input-...>", line 4, in <module>
E_o2)
File "/colour-science/colour/colour/adaptation/cie1994.py", line 134, in chromatic_adaptation_CIE1994
warning(('"Y_o" luminance factor must be in [18, 100] domain, '
/colour-science/colour/colour/utilities/verbose.py:207: ColourWarning: "Y_o" luminance factor must be in [18, 100] domain, unpredictable results may occur!
warn(*args, **kwargs)
array([ 0.17171825, 0.13731098, 0.09972054])
Setting the ‘1’ domain-range scale has the following effect on the
colour.adaptation.chromatic_adaptation_CIE1994() definition:
As it expects values in domain [0, 100], scaling occurs and the
relevant input values, i.e. the values listed in the domain table, XYZ_1
and Y_o are converted from domain [0, 1] to domain [0, 100] by
colour.utilities.to_domain_100() definition and conversely
return value XYZ_2 is converted from range [0, 100] to range [0, 1] by
colour.utilities.from_range_100() definition.
A convenient alternative to the colour.set_domain_range_scale()
definition is the colour.domain_range_scale context manager and
decorator. It temporarily overrides Colour domain-range scale with given
scale value:
with colour.domain_range_scale('1'):
colour.adaptation.chromatic_adaptation_CIE1994(XYZ_1, xy_o1, xy_o2, Y_o, E_o1, E_o2)
[ 0.24033795 0.21156212 0.17643012]
Multiprocessing on Windows with Domain-Range Scales¶
Windows does not have a fork system call, a consequence is that child processes do not necessarily inherit from changes made to global variables.
It has crucial consequences as Colour stores the current domain-range scale into a global variable.
The solution is to define an initialisation definition that defines the scale upon child processes spawning.
The colour.utilities.multiprocessing_pool context manager conveniently
performs the required initialisation so that the domain-range scale is
propagated appropriately to child processes.
Advanced¶
This page describes some advanced usage scenarios of Colour.
Table of Contents
Environment¶
Various environment variables can be used to modify Colour behaviour at runtime:
COLOUR_SCIENCE__FLOAT_PRECISION: Sets the float precision for most of Colour computations. Possible values are float16, float32 and float64 (default). Changing float precision might result in various Colour functionality breaking entirely. With great power comes great responsibility.
COLOUR_SCIENCE__INT_PRECISION: Sets the integer precision for most of Colour computations. Possible values are int8, int16, int32, and int64 (default). Changing integer precision will almost certainly break Colour! With great power comes great responsibility.
COLOUR_SCIENCE__COLOUR__SHOW_WARNINGS_WITH_TRACEBACK: results in the
warnings.showwarning()definition to be replaced with thecolour.utilities.show_warning()definition and thus providing complete traceback from the point where the warning occurred.
Using Colour without Scipy¶
With the release of Colour 0.3.8, SciPy became a requirement.
Scipy is notoriously hard to compile, especially on Windows. Some Digital Content Creation (DCC) applications are shipping Python interpreters compiled with versions of Visual Studio such as 2011 or 2015. Those are incompatible with the Python Wheels commonly built with Visual Studio 2008 (Python 2.7) or Visual Studio 2017 (Python 3.6).
It is however possible to use Colour in a partially broken and mock Scipy by using the mock_for_colour.py module.
Assuming it is available for import, a typical usage would be as follows:
import sys
from mock_for_colour import MockModule
for module in ('scipy', 'scipy.interpolate', 'scipy.spatial',
'scipy.spatial.distance', 'scipy.optimize'):
sys.modules[str(module)] = MockModule(str(module))
import colour
xyY = (0.4316, 0.3777, 0.1008)
colour.xyY_to_XYZ(xyY)
array([ 0.11518475, 0.1008 , 0.05089373])
Or directly using the mock_scipy_for_colour definition:
from mock_for_colour import mock_scipy_for_colour
mock_scipy_for_colour()
import colour
xyY = (0.4316, 0.3777, 0.1008)
colour.xyY_to_XYZ(xyY)
array([ 0.11518475, 0.1008 , 0.05089373])
Anything relying on the spectral code will be unusable, but a great amount of useful functionality will still be available.
Reference¶
Colour¶
Chromatic Adaptation¶
colour
|
Adapts given stimulus from test viewing conditions to reference viewing conditions. |
Supported chromatic adaptation methods. |
|
Reference CMCCAT2000 chromatic adaptation model viewing conditions. |
Dataset
colour
Chromatic adaptation transforms. |
colour.adaptation
|
Adapts given stimulus CIE XYZ_1 tristimulus values from test viewing conditions to reference viewing conditions using Fairchild (1990) chromatic adaptation model. |
colour.adaptation
|
Adapts given stimulus CIE XYZ_1 tristimulus values from test viewing conditions to reference viewing conditions using CIE 1994 chromatic adaptation model. |
colour.adaptation
|
Adapts given stimulus CIE XYZ tristimulus values using given viewing conditions. |
Reference CMCCAT2000 chromatic adaptation model viewing conditions. |
Ancillary Objects
colour.adaptation
|
Adapts given stimulus CIE XYZ tristimulus values from test viewing conditions to reference viewing conditions using CMCCAT2000 forward chromatic adaptation model. |
Adapts given stimulus corresponding colour CIE XYZ tristimulus values from reference viewing conditions to test viewing conditions using CMCCAT2000 inverse chromatic adaptation model. |
|
CMCCAT2000 chromatic adaptation model induction factors. |
colour.adaptation
|
Adapts given stimulus from test viewing conditions to reference viewing conditions. |
Chromatic adaptation transforms. |
Dataset
colour.adaptation
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
Ancillary Objects
colour.adaptation
|
Computes the chromatic adaptation matrix from test viewing conditions to reference viewing conditions. |
Algebra¶
colour
|
Extrapolates the 1-D function of given interpolator. |
colour
|
Kernel based interpolation of a 1-D function. |
|
A nearest-neighbour interpolator. |
|
Linearly interpolates a 1-D function. |
|
Performs 1-D function null interpolation, i.e. a call within given tolerances will return existing \(y\) variable values and |
|
Interpolates a 1-D function using Piecewise Cubic Hermite Interpolating Polynomial interpolation. |
|
Constructs a fifth-order polynomial that passes through \(y\) dependent variable. |
|
Computes the Lagrange Coefficients at given point \(r\) for degree \(n\). |
Supported table interpolation methods. |
|
|
Performs interpolation of given \(V_{xyz}\) values using given interpolation table. |
Interpolation Kernels
colour
Returns the nearest-neighbour kernel evaluated at given samples. |
|
Returns the linear kernel evaluated at given samples. |
|
|
Returns the sinc kernel evaluated at given samples. |
|
Returns the lanczos kernel evaluated at given samples. |
|
Returns the cardinal spline kernel evaluated at given samples. |
Ancillary Objects
colour.algebra
|
Performs trilinear interpolation of given \(V_{xyz}\) values using given interpolation table. |
|
Performs tetrahedral interpolation of given \(V_{xyz}\) values using given interpolation table. |
colour.algebra
Transforms given cartesian coordinates array \(xyz\) to spherical coordinates array \(\rho\theta\phi\) (radial distance, inclination or elevation and azimuth). |
|
Transforms given spherical coordinates array \(\rho\theta\phi\) (radial distance, inclination or elevation and azimuth) to cartesian coordinates array \(xyz\). |
|
Transforms given cartesian coordinates array \(xy\) to polar coordinates array \(\rho\phi\) (radial coordinate, angular coordinate). |
|
Transforms given polar coordinates array \(\rho\phi\) (radial coordinate, angular coordinate) to cartesian coordinates array \(xy\). |
|
Transforms given cartesian coordinates array \(xyz\) to cylindrical coordinates array \(\rho\phi z\) (radial distance, azimuth and height). |
|
Transforms given cylindrical coordinates array \(\rho\phi z\) (radial distance, azimuth and height) to cartesian coordinates array \(xyz\). |
colour.algebra
Normalises given vector \(a\). |
|
|
Returns the euclidean distance between point arrays \(a\) and \(b\). |
|
Extends the line segment defined by point arrays \(a\) and \(b\) by given distance and return the new end point. |
|
Computes \(l_1\) line segments intersections with \(l_2\) line segments. |
|
Returns the general form ellipse coefficients from given canonical form ellipse coefficients. |
|
Returns the canonical form ellipse coefficients from given general form ellipse coefficients. |
|
Returns the coordinates of the point at angle \(\phi\) in degrees on the ellipse with given canonical form coefficients. |
Supported ellipse fitting methods. |
|
|
Returns the coefficients of the implicit second-order polynomial/quadratic curve that fits given point array \(a\) using given method. |
Ancillary Objects
colour.algebra
Defines the specification for intersection of line segments \(l_1\) and \(l_2\) returned by |
|
Returns the coefficients of the implicit second-order polynomial/quadratic curve that fits given point array \(a\) using Halir and Flusser (1998) method. |
colour.algebra
|
Returns if \(a\) array is an identity matrix. |
colour.algebra
|
Returns a generator yielding random triplets. |
colour.algebra
Computes the least-squares mapping from dependent variable \(y\) to independent variable \(x\) using Moore-Penrose inverse. |
colour.algebra
Returns whether Colour safe / symmetrical power function is enabled. |
|
|
Sets Colour safe / symmetrical power function enabled state. |
|
A context manager and decorator temporarily setting Colour safe / symmetrical power function enabled state. |
|
Raises given array \(a\) to the power \(p\) as follows: \(sign(a) * |a|^p\). |
|
Evaluates the smoothstep sigmoid-like function on array \(x\). |
Colour Appearance Models¶
colour
|
Computes the ATD (1995) colour vision model correlates. |
|
Defines the ATD (1995) colour vision model specification. |
colour
|
Computes the CIECAM02 colour appearance model correlates from given CIE XYZ tristimulus values. |
|
Converts from CIECAM02 specification to CIE XYZ tristimulus values. |
|
Defines the CIECAM02 colour appearance model specification. |
Reference CIECAM02 colour appearance model viewing conditions. |
Ancillary Objects
colour.appearance
|
CIECAM02 colour appearance model induction factors. |
colour
|
Computes the CAM16 colour appearance model correlates from given CIE XYZ tristimulus values. |
|
Converts from CAM16 specification to CIE XYZ tristimulus values. |
|
Defines the CAM16 colour appearance model specification. |
Reference CAM16 colour appearance model viewing conditions. |
Ancillary Objects
colour.appearance
|
CAM16 colour appearance model induction factors. |
colour
|
Computes the Hunt colour appearance model correlates. |
|
Defines the Hunt colour appearance model specification. |
Reference Hunt colour appearance model viewing conditions. |
colour
|
Computes the :math:`LLAB(l:c)` colour appearance model correlates. |
|
Defines the :math:`LLAB(l:c)` colour appearance model specification. |
Reference \(LLAB(l:c)\) colour appearance model viewing conditions. |
Ancillary Objects
colour.appearance
|
:math:`LLAB(l:c)` colour appearance model induction factors. |
colour
|
Computes the Nayatani (1995) colour appearance model correlates. |
|
Defines the Nayatani (1995) colour appearance model specification. |
colour
|
Computes the RLAB model color appearance correlates. |
|
Defines the RLAB colour appearance model specification. |
Reference RLAB colour appearance model viewing conditions. |
Ancillary Objects
colour.appearance
RLAB colour appearance model Discounting-the-Illuminant factor values. |
Biochemistry¶
colour.biochemistry
|
Describes the rate of enzymatic reactions, by relating reaction rate \(v\) to concentration of a substrate \(S\). |
Describes the rate of enzymatic reactions, by relating concentration of a substrate \(S\) to reaction rate \(v\). |
Colour Vision Deficiency¶
colour
Shifts given LMS cone fundamentals colour matching functions with given \(\Delta_{LMS}\) shift amount in nanometers to simulate anomalous trichromacy using Machado et al. (2009) method. |
|
Computes the Machado et al. (2009) CVD matrix for given LMS cone fundamentals colour matching functions and display primaries tri-spectral distributions with given \(\Delta_{LMS}\) shift amount in nanometers to simulate anomalous trichromacy. |
|
|
Computes Machado et al. (2009) CVD matrix for given deficiency and severity using the pre-computed matrices dataset. |
Dataset
colour
Machado (2010) Simulation matrices \(\Phi_{CVD}\). |
Colour Characterisation¶
colour
|
Converts given spectral distribution to ACES2065-1 colourspace relative exposure values. |
Ancillary Objects
colour.characterisation
Implements support for a camera RGB sensitivities. |
colour
|
Computes an Input Device Transform (IDT) matrix for given camera RGB spectral sensitivities, illuminant, training data, standard observer colour matching functions and optimization settings according to RAW to ACES v1 and P-2013-001 procedures. |
Ancillary Objects
colour.characterisation
Reads the RAW to ACES v1 190 patches. |
|
Generates a series of illuminants according to RAW to ACES v1: |
|
|
Computes the RGB white balance multipliers for given camera RGB spectral sensitivities and illuminant. |
|
Normalises given illuminant with given camera RGB spectral sensitivities. |
|
Converts given training data to RGB tristimulus values using given illuminant and given camera RGB spectral sensitivities. |
|
Converts given training data to CIE XYZ tristimulus values using given illuminant and given standard observer colour matching functions. |
|
Select the best illuminant for given RGB white balance multipliers, and sensitivities in given series of illuminants. |
Factory that returns the objective function and CIE XYZ colourspace to optimisation colourspace/colour model function according to RAW to ACES v1. |
|
Factory that returns the objective function and CIE XYZ colourspace to optimisation colourspace/colour model function based on the \(J_zA_zB_z\) colourspace. |
colour
Supported polynomial expansion methods. |
|
|
Performs polynomial expansion of given \(a\) array. |
Supported colour correction matrix methods. |
|
|
Computes a colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array. |
Supported colour correction methods. |
|
|
Performs colour correction of given RGB colourspace array using the colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array. |
Ancillary Objects
colour.characterisation
|
Performs polynomial expansion of given RGB colourspace array using Cheung et al. (2004) method. |
|
Performs polynomial expansion of given RGB colourspace array using Finlayson et al. (2015) method. |
|
Performs polynomial expansion of given \(a\) array using Vandermonde method. |
|
Computes a colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array using Cheung et al. (2004) method. |
|
Computes a colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array using Finlayson et al. (2015) method. |
|
Computes a colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array using Vandermonde method. |
|
Performs colour correction of given RGB colourspace array using the colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array using Cheung et al. (2004) method. |
|
Performs colour correction of given RGB colourspace array using the colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array using Finlayson et al. (2015) method. |
|
Performs colour correction of given RGB colourspace array using the colour correction matrix from given \(M_T\) colour array to \(M_R\) colour array using Vandermonde method. |
Dataset
colour
Chromaticity coordinates of the colour checkers. |
|
Spectral distributions of the colour checkers. |
Ancillary Objects
colour.characterisation
|
Colour Checker data. |
colour.characterisation
|
Implements support for a camera RGB sensitivities. |
Dataset
colour
Multi-spectral distributions of camera sensitivities. |
colour.characterisation
|
Implements support for a RGB display (such as a CRT or LCD) primaries multi-spectral distributions. |
Dataset
colour
Primaries multi-spectral distributions of displays. |
Dataset
colour
Spectral distributions of filters. |
Dataset
colour
Spectral distributions of lenses. |
Colorimetry¶
colour
|
Defines the base object for spectral distribution shape. |
|
Defines the spectral distribution: the base object for spectral computations. |
|
Defines the multi-spectral distributions: the base object for multi spectral computations. |
(360, 780, 1). |
|
(360, 780, 1). |
colour
|
CIE Standard Illuminant A is intended to represent typical, domestic, tungsten-filament lighting. |
|
Returns the spectral distribution of given CIE Illuminant D Series using given CIE xy chromaticity coordinates. |
|
Returns 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\)). |
|
Returns a spectral distribution of given spectral shape filled with constant \(k\) values. |
|
Returns a spectral distribution of given spectral shape filled with ones. |
|
Returns a spectral distribution of given spectral shape filled with zeros. |
|
Returns the multi-spectral distributions with given labels and given spectral shape filled with constant \(k\) values. |
|
Returns the multi-spectral distributionss with given labels and given spectral shape filled with ones. |
|
Returns the multi-spectral distributionss with given labels and given spectral shape filled with zeros. |
Supported gaussian spectral distribution computation methods. |
|
|
Returns a gaussian spectral distribution of given spectral shape using given method. |
Supported single LED spectral distribution computation methods. |
|
|
Returns a single LED spectral distribution of given spectral shape at given peak wavelength and full width at half maximum according to given method. |
Supported multi LED spectral distribution computation methods. |
|
|
Returns a multi LED spectral distribution of given spectral shape at given peak wavelengths and full widths at half maximum according to given method. |
colour.colorimetry
|
Returns the spectral radiance of a blackbody at thermodynamic temperature \(T[K]\) in a medium having index of refraction \(n\). |
Returns the daylight locus as CIE xy chromaticity coordinates. |
|
|
Returns a gaussian spectral distribution of given spectral shape at given mean wavelength \(\mu\) and standard deviation \(sigma\). |
|
Returns a gaussian spectral distribution of given spectral shape at given peak wavelength and full width at half maximum. |
|
Returns a single LED spectral distribution of given spectral shape at given peak wavelength and full width at half maximum according to Ohno (2005) method. |
|
Returns a multi LED spectral distribution of given spectral shape at given peak wavelengths and full widths at half maximum according to Ohno (2005) method. |
|
Converts given spectral and multi-spectral distributions to a flat list of spectral distributions. |
|
Converts given spectral and multi-spectral distributions to multi-spectral distributions. |
Aliases
colour.colorimetry
|
Returns the spectral radiance of a blackbody at thermodynamic temperature \(T[K]\) in a medium having index of refraction \(n\). |
colour
|
Converts given spectral distribution to CIE XYZ tristimulus values using given colour matching functions, illuminant and method. |
Supported spectral distribution to CIE XYZ tristimulus values conversion methods. |
|
|
Converts given multi-spectral distributions to CIE XYZ tristimulus values using given colour matching functions and illuminant. |
Supported multi-spectral array to CIE XYZ tristimulus values conversion methods. |
|
|
Converts given wavelength \(\lambda\) to CIE XYZ tristimulus values using given colour matching functions. |
colour.colorimetry
|
Converts given spectral distribution to CIE XYZ tristimulus values using given colour matching functions and illuminant according to practise ASTM E308-15 method. |
|
Converts 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
Converts 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. |
|
Adjusts 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. |
|
|
Computes the Lagrange Coefficients for given interval size using practise ASTM E2022-11 method. |
Returns a table of tristimulus weighting factors for given colour matching functions and illuminant using practise ASTM E2022-11 method. |
colour.colorimetry
|
Converts given spectral distribution to CIE XYZ tristimulus values using given colour matching functions and illuminant according to classical integration method. |
|
Converts given multi-spectral distributions to CIE XYZ tristimulus values using given colour matching functions and illuminant. |
colour
|
Implements spectral bandpass dependence correction on given spectral distribution using given method. |
Supported spectral bandpass dependence correction methods. |
colour.colorimetry
Implements spectral bandpass dependence correction on given spectral distribution using Stearns and Stearns (1988) method. |
colour.colorimetry
|
Implements support for the Stockman and Sharpe LMS cone fundamentals colour matching functions. |
|
Implements support for the CIE RGB colour matching functions. |
|
Implements support for the CIE Standard Observers XYZ colour matching functions. |
Dataset
colour
Multi-spectral distributions of the colour matching functions. |
Ancillary Objects
colour.colorimetry
Multi-spectral distributions of the LMS colour matching functions. |
|
Multi-spectral distributions of the RGB colour matching functions. |
|
Multi-spectral distributions of the CIE Standard Observer colour matching functions. |
Ancillary Objects
colour.colorimetry
Converts Wright & Guild 1931 2 Degree RGB CMFs colour matching functions into the CIE 1931 2 Degree Standard Observer colour matching functions. |
|
Converts Stiles & Burch 1959 10 Degree RGB CMFs colour matching functions into the CIE 1964 10 Degree Standard Observer colour matching functions. |
|
Converts Stiles & Burch 1959 10 Degree RGB CMFs colour matching functions into the Stockman & Sharpe 10 Degree Cone Fundamentals spectral sensitivity functions. |
|
Converts Stockman & Sharpe 2 Degree Cone Fundamentals colour matching functions into the CIE 2012 2 Degree Standard Observer colour matching functions. |
|
Converts Stockman & Sharpe 10 Degree Cone Fundamentals colour matching functions into the CIE 2012 10 Degree Standard Observer colour matching functions. |
Dataset
colour
Chromaticity coordinates of the illuminants. |
|
Spectral distributions of the illuminants. |
|
Chromaticity coordinates of the light sources. |
|
Spectral distributions of the light sources. |
|
Tristimulus values of the HunterLab illuminants. |
Ancillary Objects
colour.colorimetry
CIE Illuminant D Series \(S_n(\lambda)\) spectral distributions. |
colour
|
Returns 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. |
|
Returns 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. |
|
Returns the excitation purity \(P_e\) for given colour stimulus \(xy\). |
|
Returns the colorimetric purity \(P_c\) for given colour stimulus \(xy\). |
colour
|
Returns the luminous efficacy in \(lm\cdot W^{-1}\) of given spectral distribution using given luminous efficiency function. |
|
Returns the luminous efficiency of given spectral distribution using given luminous efficiency function. |
|
Returns the luminous flux for given spectral distribution using given luminous efficiency function. |
Returns the mesopic luminous efficiency function \(V_m(\lambda)\) for given photopic luminance \(L_p\). |
Dataset
colour
Spectral distributions of the luminous efficiency functions. |
Ancillary Objects
colour.colorimetry
Spectral distributions of the photopic luminous efficiency functions. |
|
Spectral distributions of the scotopic luminous efficiency functions. |
colour
|
Returns the Lightness \(L\) of given luminance \(Y\) using given method. |
Supported Lightness computation methods. |
colour.colorimetry
Returns the Lightness \(L\) of given luminance \(Y\) using Glasser et al. (1958) method. |
colour.colorimetry
Returns the Lightness \(W\) of given luminance \(Y\) using Wyszecki (1963) method. |
colour.colorimetry
|
Returns the Lightness \(L^*\) of given luminance \(Y\) using given reference white luminance \(Y_n\) as per CIE 1976 recommendation. |
|
Returns 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. |
colour.colorimetry
|
Computes Lightness \(L_{hdr}\) of given luminance \(Y\) using Fairchild and Wyble (2010) method according to Michealis-Menten kinetics. |
colour.colorimetry
|
Computes Lightness \(L_{hdr}\) of given luminance \(Y\) using Fairchild and Chen (2011) method according to Michealis-Menten kinetics. |
colour
|
Returns the luminance \(Y\) of given Lightness \(L^*\) or given Munsell value \(V\). |
Supported luminance computation methods. |
colour.colorimetry
Returns the luminance \(R_Y\) of given Munsell value \(V\) using Newhall et al. (1943) method. |
colour.colorimetry
|
Returns the luminance \(Y\) of given Lightness \(L^*\) with given reference white luminance \(Y_n\). |
Returns 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. |
colour.colorimetry
Returns the luminance \(Y\) of given Munsell value \(V\) using ASTM D1535-08e1 method. |
colour.colorimetry
|
Computes luminance \(Y\) of given Lightness \(L_{hdr}\) using Fairchild and Wyble (2010) method according to Michealis-Menten kinetics. |
colour.colorimetry
|
Computes luminance \(Y\) of given Lightness \(L_{hdr}\) using Fairchild and Chen (2011) method according to Michealis-Menten kinetics. |
colour
|
Returns the whiteness \(W\) using given method. |
Supported whiteness computation methods. |
colour.colorimetry
|
Returns the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using Berger (1959) method. |
colour.colorimetry
|
Returns the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using Taube (1960) method. |
colour.colorimetry
Returns the whiteness index \(WI\) of given sample CIE L*a*b* colourspace array using Stensby (1968) method. |
colour.colorimetry
|
Returns the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using ASTM E313 method. |
colour.colorimetry
|
Returns the whiteness index \(W\) and tint \(T\) of given sample CIE xy chromaticity coordinates using Ganz and Griesser (1979) method. |
colour.colorimetry
|
Returns the whiteness \(W\) or \(W_{10}\) and tint \(T\) or \(T_{10}\) of given sample CIE xy chromaticity coordinates using CIE 2004 method. |
colour
|
Returns the yellowness \(W\) using given method. |
Supported yellowness computation methods. |
colour.colorimetry
|
Returns the yellowness index \(YI\) of given sample CIE XYZ tristimulus values using ASTM D1925 method. |
colour.colorimetry
|
Returns the yellowness index \(YI\) of given sample CIE XYZ tristimulus values using ASTM E313 method. |
Constants¶
colour.constants
Rounded maximum photopic luminous efficiency \(K_m\) value in \(lm\cdot W^{-1}\). |
|
Rounded maximum scotopic luminous efficiency \(K^{\prime}_m\) value in \(lm\cdot W^{-1}\). |
colour.constants
Avogadro constant. |
|
Boltzmann constant. |
|
Speed of light in vacuum. |
|
Planck constant. |
colour.constants
alias of |
|
alias of |
|
Double-precision floating-point number type, compatible with Python float and C |
|
str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str |
|
Integer threshold value when checking if a floating point number is almost an integer. |
Contrast Sensitivity¶
colour
|
Returns the contrast sensitivity \(S\) of the human eye according to the contrast sensitivity function (CSF) described by given method. |
Supported contrast sensitivity methods. |
colour.contrast
Returns the contrast sensitivity \(S\) of the human eye according to the contrast sensitivity function (CSF) described by Barten (1999). |
Ancillary Objects
colour.contrast
|
Returns the optical modulation transfer function (MTF) \(M_{opt}\) of the eye using Barten (1999) method. |
|
Returns the pupil diameter for given luminance and object or stimulus angular size using Barten (1999) method. |
|
Returns the standard deviation \(\sigma\) of the line-spread function resulting from the convolution of the different elements of the convolution process using Barten (1999) method. |
|
Returns the retinal illuminance \(E\) in Trolands for given average luminance \(L\) and pupil diameter \(d\) using Barten (1999) method. |
|
Returns the maximum angular size \(X\) of the object considered using Barten (1999) method. |
Continuous Signal¶
colour.continuous
|
Defines the base class for abstract continuous function. |
|
Defines the base class for continuous signal. |
|
Defines the base class for multi-continuous signals, a container for multiple |
Corresponding Chromaticities¶
colour
Returns the corresponding chromaticities prediction for given chromatic adaptation model. |
|
Aggregated corresponding chromaticities prediction models. |
|
|
Defines a corresponding colour dataset. |
|
Defines a chromatic adaptation model prediction. |
Dataset
colour
Breneman (1987) experiments. |
|
Breneman (1987) experiments primaries chromaticities. |
colour.corresponding
|
Returns the corresponding chromaticities prediction for Fairchild (1990) chromatic adaptation model. |
colour.corresponding
Returns the corresponding chromaticities prediction for CIE 1994 chromatic adaptation model. |
colour.corresponding
Returns the corresponding chromaticities prediction for CMCCAT2000 chromatic adaptation model. |
colour.corresponding
Returns the corresponding chromaticities prediction for Von Kries chromatic adaptation model using given transform. |
Colour Difference¶
colour
|
Returns the difference \(\Delta E_{ab}\) between two given CIE L*a*b* or \(J'a'b'\) colourspace arrays using given method. |
Supported \(\Delta E_{ab}\) computation methods. |
colour.difference
Just Noticeable Difference (JND) according to CIE 1976 colour difference formula, i.e. Euclidean distance in CIE L*a*b* colourspace. |
|
|
Returns the difference \(\Delta E_{76}\) between two given CIE L*a*b* colourspace arrays using CIE 1976 recommendation. |
colour.difference
|
Returns the difference \(\Delta E_{94}\) between two given CIE L*a*b* colourspace arrays using CIE 1994 recommendation. |
colour.difference
|
Returns the difference \(\Delta E_{00}\) between two given CIE L*a*b* colourspace arrays using CIE 2000 recommendation. |
colour.difference
|
Returns the difference \(\Delta E_{CMC}\) between two given CIE L*a*b* colourspace arrays using Colour Measurement Committee recommendation. |
colour.difference
|
Returns the difference \(\Delta E'\) between two given Luo et al. (2006) CAM02-LCD colourspaces \(J'a'b'\) arrays. |
|
Returns the difference \(\Delta E'\) between two given Luo et al. (2006) CAM02-SCD colourspaces \(J'a'b'\) arrays. |
|
Returns the difference \(\Delta E'\) between two given Luo et al. (2006) CAM02-UCS colourspaces \(J'a'b'\) arrays. |
colour.difference
|
Returns the difference \(\Delta E'\) between two given Li et al. (2017) CAM16-LCD colourspaces \(J'a'b'\) arrays. |
|
Returns the difference \(\Delta E'\) between two given Li et al. (2017) CAM16-SCD colourspaces \(J'a'b'\) arrays. |
|
Returns the difference \(\Delta E'\) between two given Li et al. (2017) CAM16-UCS colourspaces \(J'a'b'\) arrays. |
colour.difference
|
Returns the difference \(\Delta E_{DIN99}\) between two given CIE L*a*b* colourspace arrays using DIN99 formula. |
Geometry Primitives Generation¶
colour
Supported geometry primitive generation methods. |
|
|
Returns a geometry primitive using given method. |
Ancillary Objects
colour.geometry
Plane to axis mapping. |
|
|
Generates vertices and indices for a filled and outlined grid primitive. |
|
Generates vertices and indices for a filled and outlined cube primitive. |
colour
Supported geometry primitive vertices generation methods. |
|
|
Returns the vertices of a geometry primitive using given method. |
colour.geometry
|
Returns the vertices of a quad primitive for use with Matplotlib |
|
Returns the vertices of a grid primitive made of quad primitives for use with Matplotlib |
|
Returns the vertices of a cube primitive made of grid primitives for use with Matplotlib |
|
Returns the vertices of a latitude-longitude sphere primitive. |
Automatic Colour Conversion Graph¶
colour
|
Converts given object \(a\) from source colour representation to target colour representation using the automatic colour conversion graph. |
|
Describes the conversion path from source colour representation to target colour representation using the automatic colour conversion graph. |
Input and Output¶
colour
Supported read image methods. |
|
|
Reads the image at given path using given method. |
Supported write image methods. |
|
|
Writes given image at given path using given method. |
Ancillary Objects
colour.io
|
Defines the an image specification attribute. |
|
Converts given array to given bit depth, the current bit depth of the array is used to determine the appropriate conversion path. |
|
Reads the image at given path using OpenImageIO. |
|
Writes given image at given path using OpenImageIO. |
|
Reads the image at given path using Imageio. |
|
Writes given image at given path using Imageio. |
colour
|
Defines the base class for a 1D LUT. |
|
Defines the base class for a 3x1D LUT. |
|
Defines the base class for a 3D LUT. |
|
Defines the base class for a LUT sequence, i.e. a series of LUTs. |
|
Reads given LUT file using given method. |
|
Writes given LUT to given file using given method. |
Ancillary Objects
colour.io
Defines the base class for LUT sequence operators. |
|
Converts given LUT to given |
|
Reads given Cinespace .csp LUT file. |
|
Writes given LUT to given Cinespace .csp LUT file. |
|
Reads given Iridas .cube LUT file. |
|
Writes given LUT to given Iridas .cube LUT file. |
|
Reads given Sony .spi1d LUT file. |
|
Writes given LUT to given Sony .spi1d LUT file. |
|
Reads given Sony .spi3d LUT file. |
|
Writes given LUT to given Sony .spi3d LUT file. |
colour
|
Reads the spectral data from given CSV file and return its content as an OrderedDict of |
|
Reads the spectral data from given CSV file in the following form. |
|
Writes the given spectral distributions to given CSV file. |
colour
|
Defines a IES TM-27-14 spectral distribution. |
colour
|
Reads the spectral data from given X-Rite file and returns it as an OrderedDict of |
Colour Models¶
colour
|
Converts from CIE XYZ tristimulus values to CIE xyY colourspace and reference illuminant. |
|
Converts from CIE xyY colourspace to CIE XYZ tristimulus values. |
|
Returns the CIE xy chromaticity coordinates from given CIE XYZ tristimulus values. |
|
Returns the CIE XYZ tristimulus values from given CIE xy chromaticity coordinates. |
|
Converts from CIE xyY colourspace to CIE xy chromaticity coordinates. |
|
Converts from CIE xy chromaticity coordinates to CIE xyY colourspace by extending the array last dimension with given \(Y\) luminance. |
colour.models
|
Converts from Jab* colour representation to JCh colour representation. |
|
Converts from JCh colour representation to Jab* colour representation. |
colour
|
Converts from CIE XYZ tristimulus values to CIE L*a*b* colourspace. |
|
Converts from CIE L*a*b* colourspace to CIE XYZ tristimulus values. |
|
Converts from CIE L*a*b* colourspace to CIE L*C*Hab colourspace. |
|
Converts from CIE L*C*Hab colourspace to CIE L*a*b* colourspace. |
colour
|
Converts from CIE XYZ tristimulus values to CIE L*u*v* colourspace. |
|
Converts from CIE L*u*v* colourspace to CIE XYZ tristimulus values. |
|
Converts from CIE L*u*v* colourspace to CIE L*C*Huv colourspace. |
|
Converts from CIE L*C*Huv colourspace to CIE L*u*v* colourspace. |
|
Returns the \(uv^p\) chromaticity coordinates from given CIE L*u*v* colourspace array. |
|
Returns the CIE L*u*v* colourspace array from given \(uv^p\) chromaticity coordinates by extending the array last dimension with given \(L\) Lightness. |
|
Returns the CIE xy chromaticity coordinates from given CIE L*u*v* colourspace \(uv^p\) chromaticity coordinates. |
|
Returns the CIE L*u*v* colourspace \(uv^p\) chromaticity coordinates from given CIE xy chromaticity coordinates. |
colour
|
Converts from CIE XYZ tristimulus values to CIE 1960 UCS colourspace. |
|
Converts from CIE 1960 UCS colourspace to CIE XYZ tristimulus values. |
|
Returns the uv chromaticity coordinates from given CIE 1960 UCS colourspace array. |
|
Returns the CIE 1960 UCS colourspace array from given uv chromaticity coordinates. |
|
Returns the CIE xy chromaticity coordinates from given CIE 1960 UCS colourspace uv chromaticity coordinates. |
|
Returns the CIE 1960 UCS colourspace uv chromaticity coordinates from given CIE xy chromaticity coordinates. |
colour
|
Converts from CIE XYZ tristimulus values to CIE 1964 U*V*W* colourspace. |
|
Converts CIE 1964 U*V*W* colourspace to CIE XYZ tristimulus values. |
colour
|
Converts from CIE XYZ tristimulus values to Hunter L,a,b colour scale. |
|
Converts from Hunter L,a,b colour scale to CIE XYZ tristimulus values. |
Converts from whitepoint CIE XYZ tristimulus values to Hunter L,a,b \(K_{a}\) and \(K_{b}\) chromaticity coefficients. |
colour
|
Converts from CIE XYZ tristimulus values to Hunter Rd,a,b colour scale. |
|
Converts from Hunter Rd,a,b colour scale to CIE XYZ tristimulus values. |
colour
|
Converts from CIE L*a*b* colourspace to DIN99 colourspace. |
|
Converts from DIN99 colourspace to CIE L*a*b* colourspace. |
colour
Converts from CIECAM02 \(JMh\) correlates array to Luo et al. (2006) CAM02-LCD colourspace \(J'a'b'\) array. |
|
|
Converts from Luo et al. (2006) CAM02-LCD colourspace \(J'a'b'\) array to CIECAM02 \(JMh\) correlates array. |
Converts from CIECAM02 \(JMh\) correlates array to Luo et al. (2006) CAM02-SCD colourspace \(J'a'b'\) array. |
|
|
Converts from Luo et al. (2006) CAM02-SCD colourspace \(J'a'b'\) array to CIECAM02 \(JMh\) correlates array. |
Converts from CIECAM02 \(JMh\) correlates array to Luo et al. (2006) CAM02-UCS colourspace \(J'a'b'\) array. |
|
|
Converts from Luo et al. (2006) CAM02-UCS colourspace \(J'a'b'\) array to CIECAM02 \(JMh\) correlates array. |
colour
|
Converts from CAM16 \(JMh\) correlates array to Li et al. (2017) CAM16-LCD colourspace \(J'a'b'\) array. |
|
Converts from Li et al. (2017) CAM16-LCD colourspace \(J'a'b'\) array to CAM16 \(JMh\) correlates array. |
|
Converts from CAM16 \(JMh\) correlates array to Li et al. (2017) CAM16-SCD colourspace \(J'a'b'\) array. |
|
Converts from Li et al. (2017) CAM16-SCD colourspace \(J'a'b'\) array to CAM16 \(JMh\) correlates array. |
|
Converts from CAM16 \(JMh\) correlates array to Li et al. (2017) CAM16-UCS colourspace \(J'a'b'\) array. |
|
Converts from Li et al. (2017) CAM16-UCS colourspace \(J'a'b'\) array to CAM16 \(JMh\) correlates array. |
colour
|
Converts from CIE XYZ tristimulus values to \(I_GP_GT_G\) colourspace. |
|
Converts from \(I_GP_GT_G\) colourspace to CIE XYZ tristimulus values. |
colour
|
Converts from CIE XYZ tristimulus values to IPT colourspace. |
|
Converts from IPT colourspace to CIE XYZ tristimulus values. |
|
Computes the hue angle in degrees from IPT colourspace. |
colour
|
Converts from CIE XYZ tristimulus values to hdr-CIELAB colourspace. |
|
Converts from hdr-CIELAB colourspace to CIE XYZ tristimulus values. |
Supported hdr-CIELAB colourspace computation methods. |
colour
|
Converts from CIE XYZ tristimulus values to hdr-IPT colourspace. |
|
Converts from hdr-IPT colourspace to CIE XYZ tristimulus values. |
Supported hdr-IPT colourspace computation methods. |
colour
|
Converts from CIE XYZ tristimulus values under the CIE 1964 10 Degree Standard Observer to OSA UCS colourspace. |
|
Converts from OSA UCS colourspace to CIE XYZ tristimulus values under the CIE 1964 10 Degree Standard Observer. |
colour
|
Converts from CIE XYZ tristimulus values to \(J_zA_zB_z\) colourspace. |
|
Converts from \(J_zA_zB_z\) colourspace to CIE XYZ tristimulus values. |
colour
|
Converts from CIE XYZ tristimulus values to RGB colourspace array. |
|
Converts given RGB colourspace array to CIE XYZ tristimulus values. |
|
Converts given RGB colourspace array from given input RGB colourspace to output RGB colourspace using given chromatic adaptation method. |
|
Computes the matrix \(M\) converting from given input RGB colourspace to output RGB colourspace using given chromatic adaptation method. |
Ancillary Objects
colour
|
Converts from CIE XYZ tristimulus values to sRGB colourspace. |
|
Converts from sRGB colourspace to CIE XYZ tristimulus values. |
colour
|
Computes the Normalised Primary Matrix (NPM) converting a RGB colourspace array to CIE XYZ tristimulus values using given primaries and whitepoint \(xy\) chromaticity coordinates. |
|
Chromatically adapts given primaries \(xy\) chromaticity coordinates from test |
|
Computes the primaries and whitepoint \(xy\) chromaticity coordinates using given Normalised Primary Matrix (NPM). |
|
Returns the luminance \(Y\) of given RGB components from given primaries and whitepoint. |
|
Returns the luminance equation from given primaries and whitepoint. |
colour
|
Implements support for the RGB colourspaces datasets from |
Aggregated RGB colourspaces. |
colour.models
ACES2065-1 colourspace, base encoding, used for exchange of full fidelity images and archiving. |
|
ACEScc colourspace, a working space for color correctors, target for ASC-CDL values created on-set. |
|
ACEScct colourspace, an alternative working space for colour correctors, intended to be transient and internal to software or hardware systems, and is specifically not intended for interchange or archiving. |
|
ACESproxy colourspace, a lightweight encoding for transmission over HD-SDI (or other production transmission schemes), onset look management. |
|
ACEScg colourspace, a working space for paint/compositor applications that don't support ACES2065-1 or ACEScc. |
|
Adobe RGB (1998) colourspace. |
|
Adobe Wide Gamut RGB colourspace. |
|
ARRI ALEXA Wide Gamut colourspace. |
|
Apple RGB colourspace. |
|
Best RGB colourspace. |
|
Beta RGB colourspace. |
|
ITU-R BT.470 - 525 colourspace. |
|
ITU-R BT.470 - 625 colourspace. |
|
ITU-R BT.709 colourspace. |
|
ITU-R BT.2020 colourspace. |
|
CIE RGB colourspace. |
|
Canon Cinema Gamut colourspace. |
|
ColorMatch RGB colourspace. |
|
DaVinci Wide Gamut colourspace. |
|
DCDM XYZ colourspace. |
|
DCI-P3 colourspace. |
|
DCI-P3+ colourspace. |
|
Display P3 colourspace. |
|
Don RGB 4 colourspace. |
|
ECI RGB v2 colourspace. |
|
Ekta Space PS 5 colourspace. |
|
Fujifilm F-Gamut colourspace. |
|
Protune Native colourspace. |
|
Max RGB colourspace. |
|
NTSC (1953) colourspace. |
|
NTSC (1987) colourspace. |
|
P3-D65 colourspace. |
|
Pal/Secam colourspace. |
|
REDcolor colourspace. |
|
REDcolor2 colourspace. |
|
REDcolor3 colourspace. |
|
REDcolor4 colourspace. |
|
REDWideGamutRGB colourspace. |
|
DRAGONcolor colourspace. |
|
DRAGONcolor2 colourspace. |
|
ROMM RGB colourspace. |
|
RIMM RGB colourspace. |
|
ERIMM RGB colourspace. |
|
ProPhoto RGB colourspace, an alias colourspace for ROMM RGB. |
|
Russell RGB colourspace. |
|
SMPTE 240M colourspace. |
|
Implements support for the RGB colourspaces datasets from |
|
S-Gamut colourspace. |
|
S-Gamut3 colourspace. |
|
S-Gamut3.Cine colourspace. |
|
Venice S-Gamut3 colourspace. |
|
Venice S-Gamut3.Cine colourspace. |
|
sRGB colourspace. |
|
Panasonic V-Gamut colourspace. |
|
Xtreme RGB colourspace. |
colour
|
Encodes linear \(RGB\) values to non linear \(R'G'B'\) values using given encoding colour component transfer function (Encoding CCTF). |
Supported encoding colour component transfer functions (Encoding CCTFs), a collection of the functions defined by |
|
|
Decodes non-linear \(R'G'B'\) values to linear \(RGB\) values using given decoding colour component transfer function (Decoding CCTF). |
Supported decoding colour component transfer functions (Decoding CCTFs), a collection of the functions defined by |
|
|
Defines a typical gamma encoding / decoding function. |
Defines a typical linear encoding / decoding function, essentially a pass-through function. |
colour.models
|
Defines the ProPhoto RGB encoding colour component transfer function (Encoding CCTF). |
|
Defines the ProPhoto RGB decoding colour component transfer function (Encoding CCTF). |
|
Defines the RIMM RGB encoding colour component transfer function (Encoding CCTF). |
|
Defines the RIMM RGB decoding colour component transfer function (Encoding CCTF). |
Aliases
colour.models
|
Defines the ProPhoto RGB encoding colour component transfer function (Encoding CCTF). |
|
Defines the ProPhoto RGB decoding colour component transfer function (Encoding CCTF). |
Ancillary Objects
colour.models
|
Defines the basic exponent transfer function. |
|
Defines the Monitor Curve exponent transfer function. |
|
Defines the basic logarithmic function. |
|
Defines the quasilog logarithmic function. |
|
Defines the camera logarithmic function. |
colour
|
Encodes estimated tristimulus values in a scene to \(R'G'B'\) video component signal value using given opto-electronic transfer function (OETF / OECF). |
Supported opto-electrical transfer functions (OETFs / OECFs). |
|
|
Decodes \(R'G'B'\) video component signal value to tristimulus values at the display using given inverse opto-electronic transfer function (OETF / OECF). |
Supported inverse opto-electrical transfer functions (OETFs / OECFs). |
colour.models
|
Defines ARIB STD-B67 (Hybrid Log-Gamma) opto-electrical transfer function (OETF / OECF). |
|
Defines ARIB STD-B67 (Hybrid Log-Gamma) inverse opto-electrical transfer function (OETF / OECF). |
|
Defines Recommendation ITU-R BT.2100 Reference HLG opto-electrical transfer function (OETF / OECF). |
|
Defines Recommendation ITU-R BT.2100 Reference HLG inverse opto-electrical transfer function (OETF / OECF). |
Defines Recommendation ITU-R BT.2100 Reference PQ opto-electrical transfer function (OETF / OECF). |
|
Defines Recommendation ITU-R BT.2100 Reference PQ inverse opto-electrical transfer function (OETF / OECF). |
|
|
Defines Recommendation ITU-R BT.601-7 opto-electronic transfer function (OETF / OECF). |
Defines Recommendation ITU-R BT.601-7 inverse opto-electronic transfer function (OETF / OECF). |
|
|
Defines Recommendation ITU-R BT.709-6 opto-electronic transfer function (OETF / OECF). |
Defines Recommendation ITU-R BT.709-6 inverse opto-electronic transfer function (OETF / OECF). |
|
|
Defines SMPTE 240M opto-electrical transfer function (OETF / OECF). |
colour
|
Decodes \(R'G'B'\) video component signal value to tristimulus values at the display using given electro-optical transfer function (EOTF / EOCF). |
Supported electro-optical transfer functions (EOTFs / EOCFs). |
|
|
Encodes estimated tristimulus values in a scene to \(R'G'B'\) video component signal value using given inverse electro-optical transfer function (EOTF / EOCF). |
Supported inverse electro-optical transfer functions (EOTFs / EOCFs). |
colour.models
|
Defines the DCDM electro-optical transfer function (EOTF / EOCF). |
|
Defines the DCDM inverse electro-optical transfer function (EOTF / EOCF). |
|
Defines the DICOM - Grayscale Standard Display Function electro-optical transfer function (EOTF / EOCF). |
|
Defines the DICOM - Grayscale Standard Display Function inverse electro-optical transfer function (EOTF / EOCF). |
|
Defines Recommendation ITU-R BT.1886 electro-optical transfer function (EOTF / EOCF). |
|
Defines Recommendation ITU-R BT.1886 inverse electro-optical transfer function (EOTF / EOCF). |
|
Defines Recommendation ITU-R BT.2020 electro-optical transfer function (EOTF / EOCF). |
|
Defines Recommendation ITU-R BT.2020 inverse electro-optical transfer function (EOTF / EOCF). |
Supported Recommendation ITU-R BT.2100 Reference HLG electro-optical transfer function (EOTF / EOCF). |
|
|
Defines Recommendation ITU-R BT.2100 Reference HLG electro-optical transfer function (EOTF / EOCF). |
Supported Recommendation ITU-R BT.2100 Reference HLG inverse electro-optical transfer function (EOTF / EOCF). |
|
|
Defines Recommendation ITU-R BT.2100 Reference HLG inverse electro-optical transfer function (EOTF / EOCF). |
|
Defines Recommendation ITU-R BT.2100 Reference PQ electro-optical transfer function (EOTF / EOCF). |
Defines Recommendation ITU-R BT.2100 Reference PQ inverse electro-optical transfer function (EOTF / EOCF). |
|
|
Defines SMPTE 240M electro-optical transfer function (EOTF / EOCF). |
|
Defines SMPTE ST 2084:2014 optimised perceptual electro-optical transfer function (EOTF / EOCF). |
|
Defines SMPTE ST 2084:2014 optimised perceptual inverse electro-optical transfer function (EOTF / EOCF). |
|
Defines the IEC 61966-2-1:1999 sRGB electro-optical transfer function (EOTF / EOCF). |
Defines the IEC 61966-2-1:1999 sRGB inverse electro-optical transfer function (EOTF / EOCF). |
colour
|
Maps relative scene linear light to display linear light using given opto-optical transfer function (OOTF / OOCF). |
Supported opto-optical transfer functions (OOTFs / OOCFs). |
|
|
Maps relative display linear light to scene linear light using given inverse opto-optical transfer function (OOTF / OOCF). |
Supported inverse opto-optical transfer functions (OOTFs / OOCFs). |
colour.models
Supported Recommendation ITU-R BT.2100 Reference HLG opto-optical transfer function (OOTF / OOCF). |
|
|
Defines Recommendation ITU-R BT.2100 Reference HLG opto-optical transfer function (OOTF / OOCF). |
Supported Recommendation ITU-R BT.2100 Reference HLG inverse opto-optical transfer function (OOTF / OOCF). |
|
|
Defines Recommendation ITU-R BT.2100 Reference HLG inverse opto-optical transfer function (OOTF / OOCF). |
Defines Recommendation ITU-R BT.2100 Reference PQ opto-optical transfer function (OOTF / OOCF). |
|
Defines Recommendation ITU-R BT.2100 Reference PQ inverse opto-optical transfer function (OOTF / OOCF). |
colour
|
Encodes linear-light values to \(R'G'B'\) video component signal value using given log function. |
Supported log encoding functions. |
|
|
Decodes \(R'G'B'\) video component signal value to linear-light values using given log function. |
Supported log decoding functions. |
colour.models
|
Defines the ACEScc colourspace log encoding / opto-electronic transfer function. |
|
Defines the ACEScc colourspace log decoding / electro-optical transfer function. |
|
Defines the ACEScct colourspace log encoding / opto-electronic transfer function. |
|
Defines the ACEScct colourspace log decoding / electro-optical transfer function. |
|
Defines the ACESproxy colourspace log encoding curve / opto-electronic transfer function. |
|
Defines the ACESproxy colourspace log decoding curve / electro-optical transfer function. |
|
Defines the ARRI ALEXA Log C log encoding curve / opto-electronic transfer function. |
|
Defines the ARRI ALEXA Log C log decoding curve / electro-optical transfer function. |
|
Defines the Canon Log 2 log encoding curve / opto-electronic transfer function. |
|
Defines the Canon Log 2 log decoding curve / electro-optical transfer function. |
|
Defines the Canon Log 3 log encoding curve / opto-electronic transfer function. |
|
Defines the Canon Log 3 log decoding curve / electro-optical transfer function. |
|
Defines the Canon Log log encoding curve / opto-electronic transfer function. |
|
Defines the Canon Log log decoding curve / electro-optical transfer function. |
|
Defines the Cineon log encoding curve / opto-electronic transfer function. |
|
Defines the Cineon log decoding curve / electro-optical transfer function. |
|
Defines the ERIMM RGB log encoding curve / opto-electronic transfer function (OETF / OECF). |
|
Defines the ERIMM RGB log decoding curve / electro-optical transfer function (EOTF / EOCF). |
|
Defines the Fujifilm F-Log log encoding curve / opto-electronic transfer function. |
|
Defines the Fujifilm F-Log log decoding curve / electro-optical transfer function. |
|
Defines the common Log2 encoding function. |
|
Defines the common Log2 decoding function. |
Supported Log3G10 log encoding curve / opto-electronic transfer function methods. |
|
|
Defines the Log3G10 log encoding curve / opto-electronic transfer function. |
Supported Log3G10 log decoding curve / electro-optical transfer function methods. |
|
|
Defines the Log3G10 log decoding curve / electro-optical transfer function. |
Defines the Log3G12 log encoding curve / opto-electronic transfer function. |
|
Defines the Log3G12 log decoding curve / electro-optical transfer function. |
|
|
Defines the Panalog log encoding curve / opto-electronic transfer function. |
|
Defines the Panalog log decoding curve / electro-optical transfer function. |
|
Defines the Josh Pines style Pivoted Log log encoding curve / opto-electronic transfer function. |
|
Defines the Josh Pines style Pivoted Log log decoding curve / electro-optical transfer function. |
Defines the Protune log encoding curve / opto-electronic transfer function. |
|
Defines the Protune log decoding curve / electro-optical transfer function. |
|
|
Defines the REDLog log encoding curve / opto-electronic transfer function. |
|
Defines the REDLog log decoding curve / electro-optical transfer function. |
|
Defines the REDLogFilm log encoding curve / opto-electronic transfer function. |
|
Defines the REDLogFilm log decoding curve / electro-optical transfer function. |
|
Defines the Sony S-Log log encoding curve / opto-electronic transfer function. |
|
Defines the Sony S-Log log decoding curve / electro-optical transfer function. |
|
Defines the Sony S-Log2 log encoding curve / opto-electronic transfer function. |
|
Defines the Sony S-Log2 log decoding curve / electro-optical transfer function. |
|
Defines the Sony S-Log3 log encoding curve / opto-electronic transfer function. |
|
Defines the Sony S-Log3 log decoding curve / electro-optical transfer function. |
|
Defines the Panasonic V-Log log encoding curve / opto-electronic transfer function. |
|
Defines the Panasonic V-Log log decoding curve / electro-optical transfer function. |
Defines the Viper Log log encoding curve / opto-electronic transfer function. |
|
Defines the Viper Log log decoding curve / electro-optical transfer function. |
colour
|
Converts an array of R'G'B' values to the corresponding Y'CbCr colour encoding values array. |
|
Converts an array of Y'CbCr colour encoding values to the corresponding R'G'B' values array. |
Implements a case-insensitive mutable mapping / dict object. |
|
|
Converts an array of RGB linear values to the corresponding Yc'Cbc'Crc' colour encoding values array. |
|
Converts an array of Yc'Cbc'Crc' colour encoding values to the corresponding RGB array of linear values. |
Ancillary Objects
colour
|
Converts given code value \(CV\) or float equivalent of a code value at a given bit depth from full range (full swing) to legal range (studio swing). |
|
Converts given code value \(CV\) or float equivalent of a code value at a given bit depth from legal range (studio swing) to full range (full swing). |
|
Returns the code value \(CV\) range for given bit depth, range legality and representation. |
colour
|
Converts an array of R'G'B' values to the corresponding YCoCg colour encoding values array. |
|
Converts an array of YCoCg colour encoding values to the corresponding R'G'B' values array. |
colour
|
Converts from ITU-R BT.2020 colourspace to \(IC_TC_P\) colour encoding. |
|
Converts from \(IC_TC_P\) colour encoding to ITU-R BT.2020 colourspace. |
colour
|
Converts from RGB colourspace to Prismatic \(L\rho\gamma\beta\) colourspace array. |
|
Converts from Prismatic \(L\rho\gamma\beta\) colourspace array to RGB colourspace. |
colour
|
Converts from RGB colourspace to HSV colourspace. |
|
Converts from HSV colourspace to RGB colourspace. |
colour
|
Converts from RGB colourspace to HSL colourspace. |
|
Converts from HSL colourspace to RGB colourspace. |
colour
|
Converts from RGB colourspace to CMY colourspace. |
|
Converts from CMY colourspace to CMY colourspace. |
|
Converts from CMY colourspace to CMYK colourspace. |
|
Converts from CMYK colourspace to CMY colourspace. |
colour
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
|
ndarray(shape, dtype=float, buffer=None, offset=0, |
Colour Notation Systems¶
colour
|
Converts given Munsell colour to CIE xyY colourspace. |
|
Converts from CIE xyY colourspace to Munsell colour. |
Dataset
colour
Aggregated Munsell colours. |
colour
|
Returns the Munsell value \(V\) of given luminance \(Y\) using given method. |
Supported Munsell value computation methods. |
colour.notation
Returns the Munsell value \(V\) of given luminance \(Y\) using Priest et al. (1920) method. |
colour.notation
Returns the Munsell value \(V\) of given luminance \(Y\) using Munsell et al. (1933) method. |
colour.notation
Returns the Munsell value \(V\) of given luminance \(Y\) using Moon and Spencer (1943) method. |
colour.notation
Returns the Munsell value \(V\) of given luminance \(Y\) using Saunderson and Milner (1944) method. |
colour.notation
Returns the Munsell value \(V\) of given luminance \(Y\) using Ladd and Pinney (1955) method. |
colour.notation
Returns the Munsell value \(V\) of given luminance \(Y\) using McCamy (1987) method. |
colour.notation
Returns the Munsell value \(V\) of given luminance \(Y\) using an inverse lookup table from ASTM D1535-08e1 method. |
colour.notation
|
Converts from RGB colourspace to hexadecimal representation. |
|
Converts from hexadecimal representation to RGB colourspace. |
Optical Phenomena¶
colour
|
Returns the Rayleigh optical depth \(T_r(\lambda)\) as function of wavelength \(\lambda\) in centimeters (cm). |
|
Returns the Rayleigh spectral distribution for given spectral shape. |
|
Returns the scattering cross section per molecule \(\sigma\) of dry air as function of wavelength \(\lambda\) in centimeters (cm) using given \(CO_2\) concentration in parts per million (ppm) and temperature \(T[K]\) in kelvin degrees following Van de Hulst (1957) method. |
colour.phenomena
|
Returns the Rayleigh optical depth \(T_r(\lambda)\) as function of wavelength \(\lambda\) in centimeters (cm). |
Plotting¶
colour.plotting
|
Returns Colour plotting style. |
|
Returns a colour cycle iterator using given colour map. |
|
Returns the current figure and its axes or creates a new one. |
|
Sets the camera settings. |
|
Renders the current figure while adjusting various settings such as the bounding box, the title or background transparency. |
|
Add labels above given rectangles. |
|
Sets equal aspect ratio to given 3d axes. |
|
Plots given colour swatch. |
|
Plots given colours swatches. |
|
Plots given function. |
|
Plots given functions. |
|
Plots given image. |
colour.plotting
|
Plots given spectral distribution. |
|
Plots given spectral distributions. |
|
Plots given colour matching functions. |
|
Plots given colour matching functions. |
|
Plots given single illuminant spectral distribution. |
|
Plots given illuminants spectral distributions. |
|
Plots the visible colours spectrum using given standard observer CIE XYZ colour matching functions. |
|
Plots given Lightness function. |
|
Plots given Lightness functions. |
|
Plots given Luminance function. |
|
Plots given Luminance functions. |
Plots given blackbody spectral radiance. |
|
|
Plots blackbody colours. |
colour.plotting
|
Performs colour vision deficiency simulation on given RGB colourspace array using Machado et al. (2009) model. |
colour.plotting
|
Plots given colour checker. |
|
Plots and compares given colour checkers. |
colour.plotting
Plots given chromatic adaptation model corresponding chromaticities prediction. |
colour.plotting
|
Plots the CIE 1931 Chromaticity Diagram. |
|
Plots the CIE 1960 UCS Chromaticity Diagram. |
|
Plots the CIE 1976 UCS Chromaticity Diagram. |
Plots given spectral distribution chromaticity coordinates into the CIE 1931 Chromaticity Diagram. |
|
Plots given spectral distribution chromaticity coordinates into the CIE 1960 UCS Chromaticity Diagram. |
|
Plots given spectral distribution chromaticity coordinates into the CIE 1976 UCS Chromaticity Diagram. |
Ancillary Objects
colour.plotting.diagrams
|
Plots the Spectral Locus according to given method. |
|
Plots the Chromaticity Diagram colours according to given method. |
|
Plots the Chromaticity Diagram according to given method. |
|
Plots given spectral distribution chromaticity coordinates into the Chromaticity Diagram using given method. |
colour.plotting
Plots given RGB colourspaces in the CIE 1931 Chromaticity Diagram. |
|
|
Plots given RGB colourspaces in the CIE 1960 UCS Chromaticity Diagram. |
|
Plots given RGB colourspaces in the CIE 1976 UCS Chromaticity Diagram. |
|
Plots given RGB colourspace array in the CIE 1931 Chromaticity Diagram. |
|
Plots given RGB colourspace array in the CIE 1960 UCS Chromaticity Diagram. |
|
Plots given RGB colourspace array in the CIE 1976 UCS Chromaticity Diagram. |
|
Plots MacAdam (1942) Ellipses (Observer PGN) in the CIE 1931 Chromaticity Diagram. |
|
Plots MacAdam (1942) Ellipses (Observer PGN) in the CIE 1960 UCS Chromaticity Diagram. |
|
Plots MacAdam (1942) Ellipses (Observer PGN) in the CIE 1976 UCS Chromaticity Diagram. |
|
Plots given colourspace colour component transfer function. |
|
Plots given colour component transfer functions. |
|
Plots given constant hue loci colour matches data such as that from [] or [] that are easily loaded with Colour - Datasets. |
Ancillary Objects
colour.plotting.models
|
Reorder the axes of given colourspace model \(a\) array according to the most common volume plotting axes order. |
|
Plots Pointer's Gamut according to given method. |
Plots given RGB colourspaces in the Chromaticity Diagram according to given method. |
|
Plots given RGB colourspace array in the Chromaticity Diagram according to given method. |
colour.plotting
|
Plots given Lightness function. |
Plots given Munsell value functions. |
colour.plotting
Plots a single Rayleigh scattering spectral distribution. |
|
|
Plots the blue sky. |
colour.plotting
Plots the Colour Rendering Index (CRI) of given illuminant or light source spectral distribution. |
|
Plots the Colour Rendering Index (CRI) of given illuminants or light sources spectral distributions. |
|
Plots the Colour Quality Scale (CQS) of given illuminant or light source spectral distribution. |
|
Plots the Colour Quality Scale (CQS) of given illuminants or light sources spectral distributions. |
Ancillary Objects
colour.plotting.quality
|
Plots the colour quality data of given illuminants or light sources colour quality specifications. |
colour.plotting
|
Generates the ANSI/IES TM-30-18 Colour Rendition Report for given spectral distribution according to given method. |
Ancillary Objects
colour.plotting.tm3018
Generates the full ANSI/IES TM-30-18 Colour Rendition Report for given spectral distribution. |
|
Generates the intermediate ANSI/IES TM-30-18 Colour Rendition Report for given spectral distribution. |
|
Generates the simple ANSI/IES TM-30-18 Colour Rendition Report for given spectral distribution. |
colour.plotting
|
Plots given RGB colourspaces gamuts in given reference colourspace. |
|
Plots given RGB colourspace array in a scatter plot. |
colour.plotting
|
Plots Colour automatic colour conversion graph using Graphviz and pyraphviz. |
Colour Quality¶
colour
Supported Colour Fidelity Index (CFI) computation methods. |
|
|
Returns the Colour Fidelity Index (CFI) \(R_f\) of given spectral distribution using given method. |
colour.quality
|
Defines the CIE 2017 Colour Fidelity Index (CFI) colour quality specification. |
|
Returns the CIE 2017 Colour Fidelity Index (CFI) \(R_f\) of given spectral distribution. |
Defines the ANSI/IES TM-30-18 Colour Fidelity Index (CFI) colour quality specification. |
|
|
Returns the ANSI/IES TM-30-18 Colour Fidelity Index (CFI) \(R_f\) of given spectral distribution. |
colour
|
Returns the Colour Rendering Index (CRI) \(Q_a\) of given spectral distribution. |
colour.quality
|
Defines the Colour Rendering Index (CRI) colour quality specification. |
colour
Supported Colour Quality Scale (CQS) computation methods. |
|
|
Returns the Colour Quality Scale (CQS) of given spectral distribution using given method. |
colour.quality
|
Defines the Colour Quality Scale (CQS) colour rendering (quality) specification. |
colour
|
Returns the Academy Spectral Similarity Index (SSI) of given test spectral distribution with given reference spectral distribution. |
Reflectance Recovery¶
colour
|
Recovers the spectral distribution of given CIE XYZ tristimulus values using given method. |
Supported spectral distribution recovery methods. |
colour.recovery
|
Recovers the spectral distribution of given RGB colourspace array using Jakob and Hanika (2019) method. |
Class for working with pre-computed lookup tables for the Jakob and Hanika (2019) spectral upsampling method. |
Ancillary Objects
colour.recovery
|
Returns a spectral distribution following the spectral model given by Jakob and Hanika (2019). |
|
Computes the coefficients for Jakob and Hanika (2019) reflectance spectral model. |
colour.recovery
|
Recovers the spectral distribution of given RGB colourspace array using Mallett and Yuksel (2019) method. |
Ancillary Objects
colour.recovery
the base object for multi spectral computations. |
|
Shape for Mallett and Yuksel (2019) sRGB colourspace basis functions: (380, 780, 5). |
|
Performs the spectral primary decomposition as described in Mallett and Yuksel (2019) for given RGB colourspace. |
colour.recovery
|
Recovers the spectral distribution of given CIE XYZ tristimulus values using Meng et al. (2015) method. |
colour.recovery
|
Recovers the spectral distribution of given CIE XYZ tristimulus values using Otsu et al. (2018) method. |
Ancillary Objects
colour.recovery
|
Stores all the information needed for the Otsu et al. (2018) spectral upsampling method. |
|
A sub-class of |
colour.recovery
|
Recovers the spectral distribution of given RGB colourspace array using Smits (1999) method. |
Smits (1999) spectral distributions. |
Colour Temperature¶
Utilities¶
colour
|
A context manager and decorator temporarily setting Colour domain-range scale. |
Returns the current Colour domain-range scale. |
|
|
Sets the current Colour domain-range scale. |
colour.utilities
|
Decorator for handling Numpy errors. |
|
Wrapper for given function. |
|
Wrapper for given function. |
|
Wrapper for given function. |
|
Wrapper for given function. |
|
Decorator for ignoring Python warnings. |
|
Returns a batch generator from given iterable. |
A context manager and decorator temporarily disabling Colour multiprocessing. |
|
|
A context manager providing a multiprocessing pool. |
|
Returns if Matplotlib is installed and available. |
|
Returns if NetworkX is installed and available. |
|
Returns if OpenImageIO is installed and available. |
|
Returns if Pandas is installed and available. |
|
Returns if tqdm is installed and available. |
|
A decorator checking if various requirements are satisfied. |
|
Returns if given \(a\) variable is iterable. |
|
Returns if given \(a\) variable is a string like variable. |
|
Returns if given \(a\) variable is a number. |
|
Returns if given \(a\) variable is an integer under given threshold. |
|
Returns whether given element type is present in given mapping types. |
|
Filters keyword arguments incompatible with the given function signature. |
|
Filters given mapping with given filterers. |
|
Return the first item of an iterable. |
|
Scales given array \(a\) to domain '1'. |
|
Scales given array \(a\) to domain '10', used by Munsell Renotation System. |
|
Scales given array \(a\) to domain '100'. |
|
Scales given array \(a\) to degrees domain. |
|
Scales given array \(a\) to int domain. |
|
Scales given array \(a\) from range '1'. |
|
Scales given array \(a\) from range '10', used by Munsell Renotation System. |
|
Scales given array \(a\) from range '100'. |
|
Scales given array \(a\) from degrees range. |
|
Scales given array \(a\) from int range. |
|
Copies a definition with same code, globals, defaults, closure, and name. |
colour.utilities
|
Converts given \(a\) variable to ndarray using given type. |
|
Converts given \(a\) variable to ndarray using given type. |
|
Converts given \(a\) variable to ndarray using given type. |
|
Converts given \(a\) variable to numeric. |
|
Attempts to converts given \(a\) variable to int using given type. |
|
Converts given \(a\) variable to numeric using given type. |
|
Sets Colour float precision by setting |
|
Sets Colour integer precision by setting |
|
Converts given \(a\) variable to given namedtuple class instance. |
|
Returns the \(a\) variable closest element indexes to reference \(b\) variable elements. |
|
Returns the \(a\) variable closest elements to reference \(b\) variable elements. |
|
Normalises given array_like \(a\) variable values by \(a\) variable maximum value and optionally clip them between. |
|
Returns the interval size of given distribution. |
|
Returns if given distribution is uniform. |
|
Tests whether each element of an array is also present in a second array within given tolerance. |
|
Stacks arrays in sequence along the last axis (tail). |
|
Splits arrays in sequence along the last axis (tail). |
Returns the per row diagonal matrices of the given array. |
|
|
Convenient wrapper around |
|
Convenient wrapper around |
|
Orient given array according to given |
|
Computes the centroid indexes of given \(a\) array. |
|
Performs a simple linear conversion of given array between the old and new ranges. |
|
Performs a simple linear interpolation between given array \(a\) and array \(b\) using \(c\) value. |
|
Fills given array NaNs according to given method. |
A context manager setting given array writeable to perform an operation and then read-only. |
|
|
Simple wrapper around |
|
Simple wrapper around |
|
Simple wrapper around |
colour.utilities
|
Computes the mean squared error (MSE) or mean squared deviation (MSD) between given array_like \(a\) and \(b\) variables. |
|
Computes the peak signal-to-noise ratio (PSNR) between given array_like \(a\) and \(b\) variables. |
colour.utilities
|
Implements a case-insensitive mutable mapping / dict object. |
|
Implements a lazy case-insensitive mutable mapping / dict object by inheriting from |
Extends dict type to provide a lookup by value(s). |
|
|
Defines a dict-like object allowing to access key values using dot syntax. |
colour.utilities
|
Prints a message inside a box. |
|
Issues a warning. |
|
Filters Colour and also optionally overall Python warnings. |
|
A context manager filtering Colour and also optionally overall Python warnings. |
|
A context manager implementing context changes to Numpy print behaviour. |
|
Describes Colour running environment, i.e. interpreter, runtime and development packages. |
Ancillary Objects
colour.utilities
This is the base class of Colour warnings. |
|
This is the base class of Colour usage warnings. |
|
This is the base class of Colour runtime warnings. |
Colour Volume¶
colour
|
Returns if given CIE xyY colourspace array is within MacAdam limits of given illuminant. |
Illuminants Optimal Colour Stimuli. |
colour
|
Returns if given points are within given mesh volume using Delaunay triangulation. |
colour
|
Returns if given CIE XYZ tristimulus values are within Pointer's Gamut volume. |
colour
|
Computes given RGB colourspace volume limits in CIE L*a*b* colourspace. |
Returns given RGB colourspace percentage coverage of Pointer's Gamut volume using Monte Carlo method. |
|
Returns given RGB colourspace percentage coverage of visible spectrum volume using Monte Carlo method. |
|
|
Performs given RGB colourspace volume computation using Monte Carlo method and multiprocessing. |
Returns given RGB colourspace percentage coverage of an arbitrary volume. |
colour
|
Returns if given CIE XYZ tristimulus values are within visible spectrum volume / given colour matching functions volume. |
Ancillary Objects
colour.volume
|
Generates the pulse waves of given number of bins necessary to totally stimulate the colour matching functions. |
|
Generates the CIE XYZ colourspace outer surface for given colour matching functions using multi-spectral conversion of pulse waves to CIE XYZ tristimulus values. |
Indices and tables¶
Bibliography¶
Indirect References¶
Some extra references used in the codebase but not directly part of the public api:
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
[]
5.4 Examples¶
Most of the objects are available from the colour namespace:
>>> import colour
5.4.1 Automatic Colour Conversion Graph - colour.graph¶
Starting with version 0.3.14, Colour implements an automatic colour conversion graph enabling easier colour conversions.
>>> sd = colour.SDS_COLOURCHECKERS['ColorChecker N Ohta']['dark skin']
>>> colour.convert(sd, 'Spectral Distribution', 'sRGB', verbose={'mode': 'Short'})
===============================================================================
* *
* [ Conversion Path ] *
* *
* "sd_to_XYZ" --> "XYZ_to_sRGB" *
* *
===============================================================================
array([ 0.45675795, 0.30986982, 0.24861924])
>>> illuminant = colour.SDS_ILLUMINANTS['FL2']
>>> colour.convert(sd, 'Spectral Distribution', 'sRGB', sd_to_XYZ={'illuminant': illuminant})
array([ 0.47924575, 0.31676968, 0.17362725])
5.4.2 Chromatic Adaptation - colour.adaptation¶
>>> XYZ = [0.20654008, 0.12197225, 0.05136952]
>>> D65 = colour.CCS_ILLUMINANTS['CIE 1931 2 Degree Standard Observer']['D65']
>>> A = colour.CCS_ILLUMINANTS['CIE 1931 2 Degree Standard Observer']['A']
>>> colour.chromatic_adaptation(
... XYZ, colour.xy_to_XYZ(D65), colour.xy_to_XYZ(A))
array([ 0.2533053 , 0.13765138, 0.01543307])
>>> sorted(colour.CHROMATIC_ADAPTATION_METHODS)
['CIE 1994', 'CMCCAT2000', 'Fairchild 1990', 'Von Kries']
5.4.3 Algebra - colour.algebra¶
5.4.3.1 Kernel Interpolation¶
>>> y = [5.9200, 9.3700, 10.8135, 4.5100, 69.5900, 27.8007, 86.0500]
>>> x = range(len(y))
>>> colour.KernelInterpolator(x, y)([0.25, 0.75, 5.50])
array([ 6.18062083, 8.08238488, 57.85783403])
5.4.3.2 Sprague (1880) Interpolation¶
>>> y = [5.9200, 9.3700, 10.8135, 4.5100, 69.5900, 27.8007, 86.0500]
>>> x = range(len(y))
>>> colour.SpragueInterpolator(x, y)([0.25, 0.75, 5.50])
array([ 6.72951612, 7.81406251, 43.77379185])
5.4.4 Colour Appearance Models - colour.appearance¶
>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952 * 100]
>>> XYZ_w = [95.05, 100.00, 108.88]
>>> L_A = 318.31
>>> Y_b = 20.0
>>> colour.XYZ_to_CIECAM02(XYZ, XYZ_w, L_A, Y_b)
CAM_Specification_CIECAM02(J=34.434525727858997, C=67.365010921125915, h=22.279164147957076, s=62.814855853327131, Q=177.47124941102123, M=70.024939419291385, H=2.689608534423904, HC=None)
5.4.5 Colour Blindness - colour.blindness¶
>>> import numpy as np
>>> cmfs = colour.LMS_CMFS['Stockman & Sharpe 2 Degree Cone Fundamentals']
>>> colour.msds_cmfs_anomalous_trichromacy_Machado2009(cmfs, np.array([15, 0, 0]))[450]
array([ 0.08912884, 0.0870524 , 0.955393 ])
>>> primaries = colour.MSDS_DISPLAY_PRIMARIES['Apple Studio Display']
>>> d_LMS = (15, 0, 0)
>>> colour.matrix_anomalous_trichromacy_Machado2009(cmfs, primaries, d_LMS)
array([[-0.27774652, 2.65150084, -1.37375432],
[ 0.27189369, 0.20047862, 0.52762768],
[ 0.00644047, 0.25921579, 0.73434374]])
5.4.6 Colour Correction - colour characterisation¶
>>> import numpy as np
>>> RGB = [0.17224810, 0.09170660, 0.06416938]
>>> M_T = np.random.random((24, 3))
>>> M_R = M_T + (np.random.random((24, 3)) - 0.5) * 0.5
>>> colour.colour_correction(RGB, M_T, M_R)
array([ 0.1806237 , 0.07234791, 0.07848845])
>>> sorted(colour.COLOUR_CORRECTION_METHODS)
['Cheung 2004', 'Finlayson 2015', 'Vandermonde']
5.4.7 ACES Input Transform - colour characterisation¶
>>> sensitivities = colour.MSDS_CAMERA_SENSITIVITIES['Nikon 5100 (NPL)']
>>> illuminant = colour.SDS_ILLUMINANTS['D55']
>>> colour.matrix_idt(sensitivities, illuminant)
array([[ 0.46579991, 0.13409239, 0.01935141],
[ 0.01786094, 0.77557292, -0.16775555],
[ 0.03458652, -0.16152926, 0.74270359]])
5.4.8 Colorimetry - colour.colorimetry¶
5.4.8.1 Spectral Computations¶
>>> colour.sd_to_XYZ(colour.SDS_LIGHT_SOURCES['Neodimium Incandescent'])
array([ 36.94726204, 32.62076174, 13.0143849 ])
>>> sorted(colour.SPECTRAL_TO_XYZ_METHODS)
['ASTM E308', 'Integration', 'astm2015']
5.4.8.2 Multi-Spectral Computations¶
>>> msds = np.array([
... [[0.01367208, 0.09127947, 0.01524376, 0.02810712, 0.19176012, 0.04299992],
... [0.00959792, 0.25822842, 0.41388571, 0.22275120, 0.00407416, 0.37439537],
... [0.01791409, 0.29707789, 0.56295109, 0.23752193, 0.00236515, 0.58190280]],
... [[0.01492332, 0.10421912, 0.02240025, 0.03735409, 0.57663846, 0.32416266],
... [0.04180972, 0.26402685, 0.03572137, 0.00413520, 0.41808194, 0.24696727],
... [0.00628672, 0.11454948, 0.02198825, 0.39906919, 0.63640803, 0.01139849]],
... [[0.04325933, 0.26825359, 0.23732357, 0.05175860, 0.01181048, 0.08233768],
... [0.02484169, 0.12027161, 0.00541695, 0.00654612, 0.18603799, 0.36247808],
... [0.03102159, 0.16815442, 0.37186235, 0.08610666, 0.00413520, 0.78492409]],
... [[0.11682307, 0.78883040, 0.74468607, 0.83375293, 0.90571451, 0.70054168],
... [0.06321812, 0.41898224, 0.15190357, 0.24591440, 0.55301750, 0.00657664],
... [0.00305180, 0.11288624, 0.11357290, 0.12924391, 0.00195315, 0.21771573]],
... ])
>>> colour.msds_to_XYZ(msds, method='Integration',
... shape=colour.SpectralShape(400, 700, 60))
array([[[ 7.68544647, 4.09414317, 8.49324254],
[ 17.12567298, 27.77681821, 25.52573685],
[ 19.10280411, 34.45851476, 29.76319628]],
[[ 18.03375827, 8.62340812, 9.71702574],
[ 15.03110867, 6.54001068, 24.53208465],
[ 37.68269495, 26.4411103 , 10.66361816]],
[[ 8.09532373, 12.75333339, 25.79613956],
[ 7.09620297, 2.79257389, 11.15039854],
[ 8.933163 , 19.39985815, 17.14915636]],
[[ 80.00969553, 80.39810464, 76.08184429],
[ 33.27611427, 24.38947838, 39.34919287],
[ 8.89425686, 11.05185138, 10.86767594]]])
>>> sorted(colour.MSDS_TO_XYZ_METHODS)
['ASTM E308', 'Integration', 'astm2015']
5.4.8.3 Blackbody Spectral Radiance Computation¶
>>> colour.sd_blackbody(5000)
SpectralDistribution([[ 3.60000000e+02, 6.65427827e+12],
[ 3.61000000e+02, 6.70960528e+12],
[ 3.62000000e+02, 6.76482512e+12],
...
[ 7.78000000e+02, 1.06068004e+13],
[ 7.79000000e+02, 1.05903327e+13],
[ 7.80000000e+02, 1.05738520e+13]],
interpolator=SpragueInterpolator,
interpolator_args={},
extrapolator=Extrapolator,
extrapolator_args={'right': None, 'method': 'Constant', 'left': None})
5.4.8.4 Dominant, Complementary Wavelength & Colour Purity Computation¶
>>> xy = [0.54369557, 0.32107944]
>>> xy_n = [0.31270000, 0.32900000]
>>> colour.dominant_wavelength(xy, xy_n)
(array(616.0),
array([ 0.68354746, 0.31628409]),
array([ 0.68354746, 0.31628409]))
5.4.8.5 Lightness Computation¶
>>> colour.lightness(12.19722535)
41.527875844653451
>>> sorted(colour.LIGHTNESS_METHODS)
['CIE 1976',
'Fairchild 2010',
'Fairchild 2011',
'Glasser 1958',
'Lstar1976',
'Wyszecki 1963']
5.4.8.6 Luminance Computation¶
>>> colour.luminance(41.52787585)
12.197225353400775
>>> sorted(colour.LUMINANCE_METHODS)
['ASTM D1535',
'CIE 1976',
'Fairchild 2010',
'Fairchild 2011',
'Newhall 1943',
'astm2008',
'cie1976']
5.4.8.7 Whiteness Computation¶
>>> XYZ = [95.00000000, 100.00000000, 105.00000000]
>>> XYZ_0 = [94.80966767, 100.00000000, 107.30513595]
>>> colour.whiteness(XYZ, XYZ_0)
array([ 93.756 , -1.33000001])
>>> sorted(colour.WHITENESS_METHODS)
['ASTM E313',
'Berger 1959',
'CIE 2004',
'Ganz 1979',
'Stensby 1968',
'Taube 1960',
'cie2004']
5.4.8.8 Yellowness Computation¶
>>> XYZ = [95.00000000, 100.00000000, 105.00000000]
>>> colour.yellowness(XYZ)
11.065000000000003
>>> sorted(colour.YELLOWNESS_METHODS)
['ASTM D1925', 'ASTM E313']
5.4.8.9 Luminous Flux, Efficiency & Efficacy Computation¶
>>> sd = colour.SDS_LIGHT_SOURCES['Neodimium Incandescent']
>>> colour.luminous_flux(sd)
23807.655527367202
>>> sd = colour.SDS_LIGHT_SOURCES['Neodimium Incandescent']
>>> colour.luminous_efficiency(sd)
0.19943935624521045
>>> sd = colour.SDS_LIGHT_SOURCES['Neodimium Incandescent']
>>> colour.luminous_efficacy(sd)
136.21708031547874
5.4.9 Contrast Sensitivity Function - colour.contrast¶
>>> colour.contrast_sensitivity_function(u=4, X_0=60, E=65)
358.51180789884984
>>> sorted(colour.CONTRAST_SENSITIVITY_METHODS)
['Barten 1999']
5.4.10 Colour Difference - colour.difference¶
>>> Lab_1 = [100.00000000, 21.57210357, 272.22819350]
>>> Lab_2 = [100.00000000, 426.67945353, 72.39590835]
>>> colour.delta_E(Lab_1, Lab_2)
94.035649026659485
>>> sorted(colour.DELTA_E_METHODS)
['CAM02-LCD',
'CAM02-SCD',
'CAM02-UCS',
'CAM16-LCD',
'CAM16-SCD',
'CAM16-UCS',
'CIE 1976',
'CIE 1994',
'CIE 2000',
'CMC',
'DIN99',
'cie1976',
'cie1994',
'cie2000']
5.4.11 IO - colour.io¶
5.4.11.1 Images¶
>>> RGB = colour.read_image('Ishihara_Colour_Blindness_Test_Plate_3.png')
>>> RGB.shape
(276, 281, 3)
5.4.11.2 Look Up Table (LUT) Data¶
>>> LUT = colour.read_LUT('ACES_Proxy_10_to_ACES.cube')
>>> print(LUT)
LUT3x1D - ACES Proxy 10 to ACES
-------------------------------
Dimensions : 2
Domain : [[0 0 0]
[1 1 1]]
Size : (32, 3)
>>> RGB = [0.17224810, 0.09170660, 0.06416938]
>>> LUT.apply(RGB)
array([ 0.00575674, 0.00181493, 0.00121419])
5.4.12 Colour Models - colour.models¶
5.4.12.1 CIE xyY Colourspace¶
>>> colour.XYZ_to_xyY([0.20654008, 0.12197225, 0.05136952])
array([ 0.54369557, 0.32107944, 0.12197225])
5.4.12.2 CIE L*a*b* Colourspace¶
>>> colour.XYZ_to_Lab([0.20654008, 0.12197225, 0.05136952])
array([ 41.52787529, 52.63858304, 26.92317922])
5.4.12.3 CIE L*u*v* Colourspace¶
>>> colour.XYZ_to_Luv([0.20654008, 0.12197225, 0.05136952])
array([ 41.52787529, 96.83626054, 17.75210149])
5.4.12.4 CIE 1960 UCS Colourspace¶
>>> colour.XYZ_to_UCS([0.20654008, 0.12197225, 0.05136952])
array([ 0.13769339, 0.12197225, 0.1053731 ])
5.4.12.5 CIE 1964 U*V*W* Colourspace¶
>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952* 100]
>>> colour.XYZ_to_UVW(XYZ)
array([ 94.55035725, 11.55536523, 40.54757405])
5.4.12.6 Hunter L,a,b Colour Scale¶
>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952* 100]
>>> colour.XYZ_to_Hunter_Lab(XYZ)
array([ 34.92452577, 47.06189858, 14.38615107])
5.4.12.7 Hunter Rd,a,b Colour Scale¶
>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952* 100]
>>> colour.XYZ_to_Hunter_Rdab(XYZ)
array([ 12.197225 , 57.12537874, 17.46241341])
5.4.12.8 CAM02-LCD, CAM02-SCD, and CAM02-UCS Colourspaces - Luo, Cui and Li (2006)¶
>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952* 100]
>>> XYZ_w = [95.05, 100.00, 108.88]
>>> L_A = 318.31
>>> Y_b = 20.0
>>> surround = colour.VIEWING_CONDITIONS_CIECAM02['Average']
>>> specification = colour.XYZ_to_CIECAM02(
XYZ, XYZ_w, L_A, Y_b, surround)
>>> JMh = (specification.J, specification.M, specification.h)
>>> colour.JMh_CIECAM02_to_CAM02UCS(JMh)
array([ 47.16899898, 38.72623785, 15.8663383 ])
5.4.12.9 CAM16-LCD, CAM16-SCD, and CAM16-UCS Colourspaces - Li et al. (2017)¶
>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952* 100]
>>> XYZ_w = [95.05, 100.00, 108.88]
>>> L_A = 318.31
>>> Y_b = 20.0
>>> surround = colour.VIEWING_CONDITIONS_CAM16['Average']
>>> specification = colour.XYZ_to_CAM16(
XYZ, XYZ_w, L_A, Y_b, surround)
>>> JMh = (specification.J, specification.M, specification.h)
>>> colour.JMh_CAM16_to_CAM16UCS(JMh)
array([ 46.55542238, 40.22460974, 14.25288392]
5.4.12.10 IGPGTG Colourspace¶
>>> colour.XYZ_to_IGPGTG([0.20654008, 0.12197225, 0.05136952])
array([ 0.42421258, 0.18632491, 0.10689223])
5.4.12.11 IPT Colourspace¶
>>> colour.XYZ_to_IPT([0.20654008, 0.12197225, 0.05136952])
array([ 0.38426191, 0.38487306, 0.18886838])
5.4.12.12 DIN99 Colourspace¶
>>> Lab = [41.52787529, 52.63858304, 26.92317922]
>>> colour.Lab_to_DIN99(Lab)
array([ 53.22821988, 28.41634656, 3.89839552])
5.4.12.13 hdr-CIELAB Colourspace¶
>>> colour.XYZ_to_hdr_CIELab([0.20654008, 0.12197225, 0.05136952])
array([ 51.87002062, 60.4763385 , 32.14551912])
5.4.12.14 hdr-IPT Colourspace¶
>>> colour.XYZ_to_hdr_IPT([0.20654008, 0.12197225, 0.05136952])
array([ 25.18261761, -22.62111297, 3.18511729])
5.4.12.15 OSA UCS Colourspace¶
>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952* 100]
>>> colour.XYZ_to_OSA_UCS(XYZ)
array([-3.0049979 , 2.99713697, -9.66784231])
5.4.12.16 JzAzBz Colourspace¶
>>> colour.XYZ_to_JzAzBz([0.20654008, 0.12197225, 0.05136952])
array([ 0.00535048, 0.00924302, 0.00526007])
5.4.12.17 Y’CbCr Colour Encoding¶
>>> colour.RGB_to_YCbCr([1.0, 1.0, 1.0])
array([ 0.92156863, 0.50196078, 0.50196078])
5.4.12.18 YCoCg Colour Encoding¶
>>> colour.RGB_to_YCoCg([0.75, 0.75, 0.0])
array([ 0.5625, 0.375 , 0.1875])
5.4.12.19 ICTCP Colour Encoding¶
>>> colour.RGB_to_ICTCP([0.45620519, 0.03081071, 0.04091952])
array([ 0.07351364, 0.00475253, 0.09351596])
5.4.12.20 HSV Colourspace¶
>>> colour.RGB_to_HSV([0.45620519, 0.03081071, 0.04091952])
array([ 0.99603944, 0.93246304, 0.45620519])
5.4.12.21 Prismatic Colourspace¶
>>> colour.RGB_to_Prismatic([0.25, 0.50, 0.75])
array([ 0.75 , 0.16666667, 0.33333333, 0.5 ])
5.4.12.22 RGB Colourspace and Transformations¶
>>> XYZ = [0.21638819, 0.12570000, 0.03847493]
>>> illuminant_XYZ = [0.34570, 0.35850]
>>> illuminant_RGB = [0.31270, 0.32900]
>>> chromatic_adaptation_transform = 'Bradford'
>>> matrix_XYZ_to_RGB = [
[3.24062548, -1.53720797, -0.49862860],
[-0.96893071, 1.87575606, 0.04151752],
[0.05571012, -0.20402105, 1.05699594]]
>>> colour.XYZ_to_RGB(
XYZ,
illuminant_XYZ,
illuminant_RGB,
matrix_XYZ_to_RGB,
chromatic_adaptation_transform)
array([ 0.45595571, 0.03039702, 0.04087245])
5.4.12.23 RGB Colourspace Derivation¶
>>> p = [0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700]
>>> w = [0.32168, 0.33767]
>>> colour.normalised_primary_matrix(p, w)
array([[ 9.52552396e-01, 0.00000000e+00, 9.36786317e-05],
[ 3.43966450e-01, 7.28166097e-01, -7.21325464e-02],
[ 0.00000000e+00, 0.00000000e+00, 1.00882518e+00]])
5.4.12.24 RGB Colourspaces¶
>>> sorted(colour.RGB_COLOURSPACES)
['ACES2065-1',
'ACEScc',
'ACEScct',
'ACEScg',
'ACESproxy',
'ALEXA Wide Gamut',
'Adobe RGB (1998)',
'Adobe Wide Gamut RGB',
'Apple RGB',
'Best RGB',
'Beta RGB',
'CIE RGB',
'Cinema Gamut',
'ColorMatch RGB',
'DaVinci Wide Gamut',
'DCDM XYZ',
'DCI-P3',
'DCI-P3+',
'DJI D-Gamut',
'DRAGONcolor',
'DRAGONcolor2',
'Display P3',
'Don RGB 4',
'ECI RGB v2',
'ERIMM RGB',
'Ekta Space PS 5',
'F-Gamut',
'FilmLight E-Gamut',
'ITU-R BT.2020',
'ITU-R BT.470 - 525',
'ITU-R BT.470 - 625',
'ITU-R BT.709',
'Max RGB',
'NTSC (1953)',
'NTSC (1987)',
'P3-D65',
'Pal/Secam',
'ProPhoto RGB',
'Protune Native',
'REDWideGamutRGB',
'REDcolor',
'REDcolor2',
'REDcolor3',
'REDcolor4',
'RIMM RGB',
'ROMM RGB',
'Russell RGB',
'S-Gamut',
'S-Gamut3',
'S-Gamut3.Cine',
'SMPTE 240M',
'SMPTE C',
'Sharp RGB',
'V-Gamut',
'Venice S-Gamut3',
'Venice S-Gamut3.Cine',
'Xtreme RGB',
'aces',
'adobe1998',
'prophoto',
5.4.12.25 OETFs¶
>>> sorted(colour.OETFS)
['ARIB STD-B67',
'ITU-R BT.2100 HLG',
'ITU-R BT.2100 PQ',
'ITU-R BT.601',
'ITU-R BT.709',
'SMPTE 240M']
5.4.12.26 OETFs Inverse¶
>>> sorted(colour.OETF_INVERSES)
['ARIB STD-B67',
'ITU-R BT.2100 HLG',
'ITU-R BT.2100 PQ',
'ITU-R BT.601',
'ITU-R BT.709']
5.4.12.27 EOTFs¶
>>> sorted(colour.EOTFS)
['DCDM',
'DICOM GSDF',
'ITU-R BT.1886',
'ITU-R BT.2020',
'ITU-R BT.2100 HLG',
'ITU-R BT.2100 PQ',
'SMPTE 240M',
'ST 2084',
'sRGB']
5.4.12.28 EOTFs Inverse¶
>>> sorted(colour.EOTF_INVERSES)
['DCDM',
'DICOM GSDF',
'ITU-R BT.1886',
'ITU-R BT.2020',
'ITU-R BT.2100 HLG',
'ITU-R BT.2100 PQ',
'ST 2084',
'sRGB']
5.4.12.29 OOTFs¶
>>> sorted(colour.OOTFS)
['ITU-R BT.2100 HLG', 'ITU-R BT.2100 PQ']
5.4.12.30 OOTFs Inverse¶
>>> sorted(colour.OOTF_INVERSES)
['ITU-R BT.2100 HLG', 'ITU-R BT.2100 PQ']
5.4.12.31 Log Encoding / Decoding¶
>>> sorted(colour.LOG_ENCODINGS)
['ACEScc',
'ACEScct',
'ACESproxy',
'ALEXA Log C',
'Canon Log',
'Canon Log 2',
'Canon Log 3',
'Cineon',
'D-Log',
'ERIMM RGB',
'F-Log',
'Filmic Pro 6',
'Log2',
'Log3G10',
'Log3G12',
'PLog',
'Panalog',
'Protune',
'REDLog',
'REDLogFilm',
'S-Log',
'S-Log2',
'S-Log3',
'T-Log',
'V-Log',
'ViperLog']
5.4.12.32 CCTFs Encoding / Decoding¶
>>> sorted(colour.CCTF_ENCODINGS)
['ACEScc',
'ACEScct',
'ACESproxy',
'ALEXA Log C',
'ARIB STD-B67',
'Canon Log',
'Canon Log 2',
'Canon Log 3',
'Cineon',
'D-Log',
'DCDM',
'DICOM GSDF',
'ERIMM RGB',
'F-Log',
'Filmic Pro 6',
'Gamma 2.2',
'Gamma 2.4',
'Gamma 2.6',
'ITU-R BT.1886',
'ITU-R BT.2020',
'ITU-R BT.2100 HLG',
'ITU-R BT.2100 PQ',
'ITU-R BT.601',
'ITU-R BT.709',
'Log2',
'Log3G10',
'Log3G12',
'PLog',
'Panalog',
'ProPhoto RGB',
'Protune',
'REDLog',
'REDLogFilm',
'RIMM RGB',
'ROMM RGB',
'S-Log',
'S-Log2',
'S-Log3',
'SMPTE 240M',
'ST 2084',
'T-Log',
'V-Log',
'ViperLog',
'sRGB']
5.4.13 Colour Notation Systems - colour.notation¶
5.4.13.1 Munsell Value¶
>>> colour.munsell_value(12.23634268)
4.0824437076525664
>>> sorted(colour.MUNSELL_VALUE_METHODS)
['ASTM D1535',
'Ladd 1955',
'McCamy 1987',
'Moon 1943',
'Munsell 1933',
'Priest 1920',
'Saunderson 1944',
'astm2008']
5.4.13.2 Munsell Colour¶
>>> colour.xyY_to_munsell_colour([0.38736945, 0.35751656, 0.59362000])
'4.2YR 8.1/5.3'
>>> colour.munsell_colour_to_xyY('4.2YR 8.1/5.3')
array([ 0.38736945, 0.35751656, 0.59362 ])
5.4.14 Optical Phenomena - colour.phenomena¶
>>> colour.rayleigh_scattering_sd()
SpectralDistribution([[ 3.60000000e+02, 5.99101337e-01],
[ 3.61000000e+02, 5.92170690e-01],
[ 3.62000000e+02, 5.85341006e-01],
...
[ 7.78000000e+02, 2.55208377e-02],
[ 7.79000000e+02, 2.53887969e-02],
[ 7.80000000e+02, 2.52576106e-02]],
interpolator=SpragueInterpolator,
interpolator_args={},
extrapolator=Extrapolator,
extrapolator_args={'right': None, 'method': 'Constant', 'left': None})
5.4.15 Light Quality - colour.quality¶
5.4.15.1 Colour Fidelity Index¶
>>> colour.colour_fidelity_index(colour.SDS_ILLUMINANTS['FL2'])
70.120825477833037
>>> sorted(colour.COLOUR_FIDELITY_INDEX_METHODS)
['ANSI/IES TM-30-18', 'CIE 2017']
5.4.15.2 Colour Rendering Index¶
>>> colour.colour_quality_scale(colour.SDS_ILLUMINANTS['FL2'])
64.111703163816699
>>> sorted(colour.COLOUR_QUALITY_SCALE_METHODS)
['NIST CQS 7.4', 'NIST CQS 9.0']
5.4.15.3 Colour Quality Scale¶
>>> colour.colour_rendering_index(colour.SDS_ILLUMINANTS['FL2'])
64.233724121664807
5.4.15.4 Academy Spectral Similarity Index (SSI)¶
>>> colour.spectral_similarity_index(colour.SDS_ILLUMINANTS['C'], colour.SDS_ILLUMINANTS['D65'])
94.0
5.4.16 Spectral Up-Sampling & Reflectance Recovery - colour.recovery¶
>>> colour.XYZ_to_sd([0.20654008, 0.12197225, 0.05136952])
SpectralDistribution([[ 3.60000000e+02, 8.37868873e-02],
[ 3.65000000e+02, 8.39337988e-02],
...
[ 7.70000000e+02, 4.46793405e-01],
[ 7.75000000e+02, 4.46872853e-01],
[ 7.80000000e+02, 4.46914431e-01]],
interpolator=SpragueInterpolator,
interpolator_kwargs={},
extrapolator=Extrapolator,
extrapolator_kwargs={'method': 'Constant', 'left': None, 'right': None})
>>> sorted(colour.REFLECTANCE_RECOVERY_METHODS)
['Jakob 2019', 'Mallett 2019', 'Meng 2015', 'Otsu 2018', 'Smits 1999']
5.4.18 Colour Volume - colour.volume¶
>>> colour.RGB_colourspace_volume_MonteCarlo(colour.RGB_COLOURSPACE_RGB['sRGB'])
821958.30000000005
5.4.19 Geometry Primitives Generation - colour.geometry¶
>>> colour.primitive('Grid')
(array([ ([-0.5, 0.5, 0. ], [ 0., 1.], [ 0., 0., 1.], [ 0., 1., 0., 1.]),
([ 0.5, 0.5, 0. ], [ 1., 1.], [ 0., 0., 1.], [ 1., 1., 0., 1.]),
([-0.5, -0.5, 0. ], [ 0., 0.], [ 0., 0., 1.], [ 0., 0., 0., 1.]),
([ 0.5, -0.5, 0. ], [ 1., 0.], [ 0., 0., 1.], [ 1., 0., 0., 1.])],
dtype=[('position', '<f4', (3,)), ('uv', '<f4', (2,)), ('normal', '<f4', (3,)), ('colour', '<f4', (4,))]), array([[0, 2, 1],
[2, 3, 1]], dtype=uint32), array([[0, 2],
[2, 3],
[3, 1],
[1, 0]], dtype=uint32))
>>> sorted(colour.PRIMITIVE_METHODS)
['Cube', 'Grid']
>>> colour.primitive_vertices('Quad MPL')
array([[ 0., 0., 0.],
[ 1., 0., 0.],
[ 1., 1., 0.],
[ 0., 1., 0.]])
>>> sorted(colour.PRIMITIVE_VERTICES_METHODS)
['Cube MPL', 'Grid MPL', 'Quad MPL', 'Sphere']
5.4.20 Plotting - colour.plotting¶
Most of the objects are available from the colour.plotting namespace:
>>> from colour.plotting import *
>>> colour_style()
5.4.20.1 Visible Spectrum¶
>>> plot_visible_spectrum('CIE 1931 2 Degree Standard Observer')
5.4.20.2 Spectral Distribution¶
>>> plot_single_illuminant_sd('FL1')
5.4.20.3 Blackbody¶
>>> blackbody_sds = [
... colour.sd_blackbody(i, colour.SpectralShape(0, 10000, 10))
... for i in range(1000, 15000, 1000)
... ]
>>> plot_multi_sds(
... blackbody_sds,
... y_label='W / (sr m$^2$) / m',
... plot_kwargs={
... use_sd_colours=True,
... normalise_sd_colours=True,
... },
... legend_location='upper right',
... bounding_box=(0, 1250, 0, 2.5e15))
5.4.20.4 Colour Matching Functions¶
>>> plot_single_cmfs(
... 'Stockman & Sharpe 2 Degree Cone Fundamentals',
... y_label='Sensitivity',
... bounding_box=(390, 870, 0, 1.1))
5.4.20.5 Luminous Efficiency¶
>>> sd_mesopic_luminous_efficiency_function = (
... colour.sd_mesopic_luminous_efficiency_function(0.2))
>>> plot_multi_sds(
... (sd_mesopic_luminous_efficiency_function,
... colour.PHOTOPIC_LEFS['CIE 1924 Photopic Standard Observer'],
... colour.SCOTOPIC_LEFS['CIE 1951 Scotopic Standard Observer']),
... y_label='Luminous Efficiency',
... legend_location='upper right',
... y_tighten=True,
... margins=(0, 0, 0, .1))
5.4.20.6 Colour Checker¶
>>> from colour.characterisation.dataset.colour_checkers.sds import (
... COLOURCHECKER_INDEXES_TO_NAMES_MAPPING)
>>> plot_multi_sds(
... [
... colour.SDS_COLOURCHECKERS['BabelColor Average'][value]
... for key, value in sorted(
... COLOURCHECKER_INDEXES_TO_NAMES_MAPPING.items())
... ],
... plot_kwargs={
... use_sd_colours=True,
... },
... title=('BabelColor Average - '
... 'Spectral Distributions'))
>>> plot_single_colour_checker(
... 'ColorChecker 2005', text_kwargs={'visible': False})
5.4.20.7 Chromaticities Prediction¶
>>> plot_corresponding_chromaticities_prediction(
... 2, 'Von Kries', 'Bianco 2010')
5.4.20.8 Colour Temperature¶
>>> plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(['A', 'B', 'C'])
5.4.20.9 Chromaticities¶
>>> import numpy as np
>>> RGB = np.random.random((32, 32, 3))
>>> plot_RGB_chromaticities_in_chromaticity_diagram_CIE1931(
... RGB, 'ITU-R BT.709',
... colourspaces=['ACEScg', 'S-Gamut'], show_pointer_gamut=True)
5.4.20.10 Colour Rendering Index¶
>>> plot_single_sd_colour_rendering_index_bars(
... colour.SDS_ILLUMINANTS['FL2'])
5.4.20.11 ANSI/IES TM-30-18 Colour Rendition Report¶
>>> plot_single_sd_colour_rendition_report(
... colour.SDS_ILLUMINANTS['FL2'])
6 Contributing¶
If you would like to contribute to Colour, please refer to the following Contributing guide.
7 Changes¶
The changes are viewable on the Releases page.
8 Bibliography¶
The bibliography is available on the Bibliography page.
It is also viewable directly from the repository in BibTeX format.
9 See Also¶
Here is a list of notable colour science packages sorted by languages:
Python
Colorio by Schlömer, N.
ColorPy by Kness, M.
Colorspacious by Smith, N. J., et al.
python-colormath by Taylor, G., et al.
Go
go-colorful by Beyer, L., et al.
.NET
Colourful by Pažourek, T., et al.
Julia
Colors.jl by Holy, T., et al.
Matlab & Octave
COLORLAB by Malo, J., et al.
Psychtoolbox by Brainard, D., et al.
The Munsell and Kubelka-Munk Toolbox by Centore, P.
10 Code of Conduct¶
The Code of Conduct, adapted from the Contributor Covenant 1.4, is available on the Code of Conduct page.