Colour Science for Python

Colour is a Python colour science package implementing a comprehensive number of colour theory transformations and algorithms.

It is open source and freely available under the New BSD License terms.

Features

Colour features a rich dataset and collection of objects, please see the features page for more information.

Installation

Anaconda from Continuum Analytics is the Python distribution we use to develop Colour: it ships all the scientific dependencies we require and is easily deployed cross-platform:

$ conda create -y -n python-colour
$ source activate python-colour
$ conda install -y -c conda-forge colour-science

Colour can be easily installed from the Python Package Index by issuing this command in a shell:

$ pip install colour-science

The detailed installation procedure is described in the Installation Guide.

Usage

The two main references for Colour usage are the Colour Manual and the Jupyter Notebooks with detailed historical and theoretical context and images:

Examples

Most of the objects are available from the colour namespace:

>>> import colour

Chromatic Adaptation

>>> XYZ = [0.20654008, 0.12197225, 0.05136952]
>>> D65 = colour.ILLUMINANTS['CIE 1931 2 Degree Standard Observer']['D65']
>>> A = colour.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.keys())
['CIE 1994', 'CMCCAT2000', 'Fairchild 1990', 'Von Kries']

Algebra

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])

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])

Spectral Computations

>>> colour.sd_to_XYZ(colour.LIGHT_SOURCES_SDS['Neodimium Incandescent'])
array([ 36.94726204,  32.62076174,  13.0143849 ])
>>> sorted(colour.SPECTRAL_TO_XYZ_METHODS.keys())
[u'ASTM E308-15', u'Integration', u'astm2015']

Multi-Spectral Computations

>>> msa = 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.multi_sd_to_XYZ(msa, colour.SpectralShape(400, 700, 60),
...                              cmfs, illuminant))
[[[  9.73192501   5.02105851   3.22790699]
  [ 16.08032168  24.47303359  10.28681006]
  [ 17.73513774  29.61865582  12.10713449]]
 [[ 25.69298792  11.72611193   3.70187275]
  [ 18.51208526   8.03720984   9.30361825]
  [ 48.55945054  32.30885571   4.09223401]]
 [[  5.7743232   10.10692925  10.08461311]
  [  8.81306527   3.65394599   4.20783881]
  [  8.06007398  15.87077693   7.02551086]]
 [[ 90.88877129  81.82966846  29.86765971]
  [ 38.64801062  26.70860262  15.08396538]
  [  8.77151115  10.56330761   4.28940206]]]
>>> sorted(colour.MULTI_SPECTRAL_TO_XYZ_METHODS.keys())
[u'Integration']

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={u'right': None, u'method': u'Constant', u'left': None})

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]))

Lightness Computation

>>> colour.lightness(12.19722535)
41.527875844653451
>>> sorted(colour.LIGHTNESS_METHODS.keys())
[u'CIE 1976',
 u'Fairchild 2010',
 u'Fairchild 2011',
 u'Glasser 1958',
 u'Lstar1976',
 u'Wyszecki 1963']

Luminance Computation

>>> colour.luminance(41.52787585)
12.197225353400775
>>> sorted(colour.LUMINANCE_METHODS.keys())
[u'ASTM D1535-08',
 u'CIE 1976',
 u'Fairchild 2010',
 u'Fairchild 2011',
 u'Newhall 1943',
 u'astm2008',
 u'cie1976']

Whiteness Computation

>>> colour.whiteness(xy=[0.3167, 0.3334], Y=100, xy_n=[0.3139, 0.3311])
array([ 93.85 ,  -1.305])
>>> sorted(colour.WHITENESS_METHODS.keys())
[u'ASTM E313',
 u'Berger 1959',
 u'CIE 2004',
 u'Ganz 1979',
 u'Stensby 1968',
 u'Taube 1960',
 u'cie2004']

Yellowness Computation

>>> XYZ = [95.00000000, 100.00000000, 105.00000000]
>>> colour.yellowness(XYZ)
11.065000000000003
>>> sorted(colour.YELLOWNESS_METHODS.keys())
[u'ASTM D1925', u'ASTM E313']

Luminous Flux, Efficiency & Efficacy Computation

Luminous Flux

>>> sd = colour.LIGHT_SOURCES_SDS['Neodimium Incandescent']
>>> colour.luminous_flux(sd)
3807.655527367202

Luminous Efficiency

>>> sd = colour.LIGHT_SOURCES_SDS['Neodimium Incandescent']
>>> colour.luminous_efficiency(sd)
0.19943935624521045

Luminous Efficacy

>>> sd = colour.LIGHT_SOURCES_SDS['Neodimium Incandescent']
>>> colour.luminous_efficacy(sd)
136.21708031547874

Colour Models

CIE xyY Colourspace

>>> colour.XYZ_to_xyY([0.20654008, 0.12197225, 0.05136952])
array([ 0.54369557,  0.32107944,  0.12197225])

CIE Lab* Colourspace

>>> colour.XYZ_to_Lab([0.20654008, 0.12197225, 0.05136952])
array([ 41.52787529,  52.63858304,  26.92317922])

CIE Luv* Colourspace

>>> colour.XYZ_to_Luv([0.20654008, 0.12197225, 0.05136952])
array([ 41.52787529,  96.83626054,  17.75210149])

CIE 1960 UCS Colourspace

>>> colour.XYZ_to_UCS([0.20654008, 0.12197225, 0.05136952])
array([ 0.13769339,  0.12197225,  0.1053731 ])

CIE 1964 UVW* Colourspace

>>> XYZ = [0.20654008 * 100, 0.12197225 * 100, 0.05136952* 100]
>>> colour.XYZ_to_UVW(XYZ)
array([ 94.55035725,  11.55536523,  40.54757405])

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])

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])

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.CIECAM02_VIEWING_CONDITIONS['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 ])

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.CAM16_VIEWING_CONDITIONS['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]

IPT Colourspace

>>> colour.XYZ_to_IPT([0.20654008, 0.12197225, 0.05136952])
array([ 0.38426191,  0.38487306,  0.18886838])

DIN99 Colourspace

>>> Lab = [41.52787529, 52.63858304, 26.92317922]
>>> colour.Lab_to_DIN99(Lab)
array([ 53.22821988,  28.41634656,   3.89839552])

hdr-CIELAB Colourspace

>>> colour.XYZ_to_hdr_CIELab([0.20654008, 0.12197225, 0.05136952])
array([ 51.87002062,  60.4763385 ,  32.14551912])

hdr-IPT Colourspace

>>> colour.XYZ_to_hdr_IPT([0.20654008, 0.12197225, 0.05136952])
array([ 25.18261761, -22.62111297,   3.18511729])

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])

JzAzBz Colourspace

>>> colour.XYZ_to_JzAzBz([0.20654008, 0.12197225, 0.05136952])
array([ 0.00535048,  0.00924302,  0.00526007])

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'
>>> XYZ_to_RGB_matrix = [
         [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,
         XYZ_to_RGB_matrix,
         chromatic_adaptation_transform)
array([ 0.45595571,  0.03039702,  0.04087245])

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]])

Y'CbCr Colour Encoding

>>> colour.RGB_to_YCbCr([1.0, 1.0, 1.0])
array([ 0.92156863,  0.50196078,  0.50196078])

YCoCg Colour Encoding

>>> colour.RGB_to_YCoCg([0.75, 0.75, 0.0])
array([ 0.5625,  0.375 ,  0.1875])

ICTCP Colour Encoding

>>> colour.RGB_to_ICTCP([0.45620519, 0.03081071, 0.04091952])
array([ 0.07351364,  0.00475253,  0.09351596])

HSV Colourspace

>>> colour.RGB_to_HSV([0.45620519, 0.03081071, 0.04091952])
array([ 0.99603944,  0.93246304,  0.45620519])

Prismatic Colourspace

>>> colour.RGB_to_Prismatic([0.25, 0.50, 0.75])
array([ 0.75      ,  0.16666667,  0.33333333,  0.5       ])

RGB Colourspaces

>>> sorted(colour.RGB_COLOURSPACES.keys())
[u'ACES2065-1',
 u'ACEScc',
 u'ACEScct',
 u'ACEScg',
 u'ACESproxy',
 u'ALEXA Wide Gamut',
 u'Adobe RGB (1998)',
 u'Adobe Wide Gamut RGB',
 u'Apple RGB',
 u'Best RGB',
 u'Beta RGB',
 u'CIE RGB',
 u'Cinema Gamut',
 u'ColorMatch RGB',
 u'DCDM XYZ',
 u'DCI-P3',
 u'DCI-P3+',
 u'DRAGONcolor',
 u'DRAGONcolor2',
 u'Don RGB 4',
 u'ECI RGB v2',
 u'ERIMM RGB',
 u'Ekta Space PS 5',
 u'ITU-R BT.2020',
 u'ITU-R BT.470 - 525',
 u'ITU-R BT.470 - 625',
 u'ITU-R BT.709',
 u'Max RGB',
 u'NTSC',
 u'P3-D65',
 u'Pal/Secam',
 u'ProPhoto RGB',
 u'Protune Native',
 u'REDWideGamutRGB',
 u'REDcolor',
 u'REDcolor2',
 u'REDcolor3',
 u'REDcolor4',
 u'RIMM RGB',
 u'ROMM RGB',
 u'Russell RGB',
 u'S-Gamut',
 u'S-Gamut3',
 u'S-Gamut3.Cine',
 u'SMPTE 240M',
 u'Sharp RGB',
 u'V-Gamut',
 u'Xtreme RGB',
 'aces',
 'adobe1998',
 'prophoto',
 u'sRGB']

OETFs

>>> sorted(colour.OETFS.keys())
['ARIB STD-B67',
 'DCI-P3',
 'P3-D65',
 'DICOM GSDF',
 'ITU-R BT.2020',
 'ITU-R BT.2100 HLG',
 'ITU-R BT.2100 PQ',
 'ITU-R BT.601',
 'ITU-R BT.709',
 'ProPhoto RGB',
 'RIMM RGB',
 'ROMM RGB',
 'SMPTE 240M',
 'ST 2084',
 'sRGB']

EOTFs

>>> sorted(colour.EOTFS.keys())
['DCI-P3',
 'DICOM GSDF',
 'ITU-R BT.1886',
 'ITU-R BT.2020',
 'ITU-R BT.2100 HLG',
 'ITU-R BT.2100 PQ',
 'ProPhoto RGB',
 'RIMM RGB',
 'ROMM RGB',
 'SMPTE 240M',
 'ST 2084']

Name		Name	Last commit message	Last commit date
Latest commit History 2,362 Commits
colour		colour
docs		docs
utilities		utilities
.coveragerc		.coveragerc
.gitignore		.gitignore
.style.yapf		.style.yapf
.travis.yml		.travis.yml
BIBLIOGRAPHY.bib		BIBLIOGRAPHY.bib
CHANGES.rst		CHANGES.rst
CONTRIBUTING.rst		CONTRIBUTING.rst
CONTRIBUTORS.rst		CONTRIBUTORS.rst
GRANTS		GRANTS
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.rst		README.rst
TODO.rst		TODO.rst
azure-pipelines.yml		azure-pipelines.yml
setup.py		setup.py
tasks.py		tasks.py

License

kimkuang/colour

Folders and files

Latest commit

History

Repository files navigation