colorio 0.9.0

Tools for color models

Tools for color research.

Illuminants, observers, white points

Illuminants	CIE 1931 Observer

import colorio
import matplotlib.pyplot as plt

illu = colorio.illuminants.d65()
plt.plot(illu.lmbda_nm, illu.data)
plt.xlabel("wavelength [nm]")
plt.show()

The following illuminants are provided:

• Illuminant A ("indoor light", colorio.illuminants.a(resolution_in_nm))
• Illuminant C (obsolete, "North sky daylight", colorio.illuminants.c())
• Illuminants D ("natural daylight", colorio.illuminants.d(nominal_temp) or colorio.illuminants.d65() etc.)
• Illuminant E (equal energy, colorio.illuminants.e())
• Illuminant series F ("fluorescent lighting", colorio.illuminants.f2() etc.)

Observers:

• CIE 1931 Standard 2-degree observer (colorio.observers.colorio.observers.cie_1931_2())
• CIE 1964 Standard 10-degree observer (colorio.observers.colorio.observers.cie_1964_10())

Color coordinates and spaces

Color coordinates are handled as NumPy arrays or as ColorCoordinates, a thin wrapper that retains the color space information and has some handy helper methods:

from colorio.cs import ColorCoordinates, CIELAB, OKLAB

# you can also plug in large numpy arrays here
cc = ColorCoordinates([0.1, 0.5, 13.3], CIELAB())

cc.color_space
# access the raw numpy array:
cc.data

# get RGB represenations
cc.get_rgb1("clip")
cc.get_rgb_hex("clip")

# convert to other color space
cc_oklab = cc.convert(OKLAB())

All color spaces implement the two methods

vals = colorspace.from_xyz100(xyz)
xyz = colorspace.to_xyz100(vals)

for conversion from and to XYZ100. Adding new color spaces is as easy as writing a class that provides those two methods. The following color spaces are already implemented:

• XYZ (colorio.cs.XYZ(100), the parameter determining the scaling)

• xyY (colorio.cs.XYY(100), the paramter determining the scaling of Y)

• Linear sRGB (colorio.SrgbLinear()) This class has the additional methods

  [to,from]_rgb[1,255,_hex]()
  

  for conversion from and to standard RGB (Gamma correction).

• HSL and HSV (colorio.cs.HSL(), colorio.cs.HSV()) These classes have the two methods

  from_srgb1()
  to_srgb1()
  

  for conversion from and to standard RGB.

• OSA-UCS (colorio.cs.OsaUcs())

• CIELAB (colorio.cs.CIELAB())

• CIELUV (colorio.cs.CIELUV())

• RLAB (colorio.cs.RLAB())

• DIN99 and its variants DIN99{b,c,d} (colorio.cs.DIN99())

• ICtCp (colorio.cs.ICtCp())

• IPT (colorio.cs.IPT())

• CIECAM02 / CAM02-UCS

  import math
  import colorio
  
  ciecam02 = colorio.cs.CIECAM02(0.69, 20, 100)
  cam02 = colorio.cs.CAM02("UCS", 0.69, 20, 100)
  

  The implementation contains a few improvements over the CIECAM02 specification (see here).

• CAM16 / CAM16-UCS

  import math
  import colorio
  
  cam16 = colorio.cs.CAM16(0.69, 20, 100)
  cam16ucs = colorio.cs.CAM16UCS(0.69, 20, 100)
  

  The implementation contains a few improvements over the CAM16 specification (see here).

• J_za_zb_z (colorio.cs.JzAzBz())

• Oklab (colorio.cs.OKLAB())

• proLab (colorio.cs.PROLAB())

• SRLAB2 (colorio.cs.SRLAB2())

All methods in colorio are fully vectorized, i.e., computation is really fast.

Color difference formulas

colorio implements the following color difference formulas:

• CIE76

  colorio.diff.cie76(lab1, lab2)
  

• CIE94

  colorio.diff.cie94(lab1, lab2)
  

• CIEDE2000

  colorio.diff.ciede2000(lab1, lab2)
  

• CMC l:c

  colorio.diff.cmc(lab1, lab2)
  

Chromatic adaptation transforms

colorio implements the following CATs:

• von Kries

  cat, cat_inv = colorio.cat.von_kries(whitepoint_source, whitepoint_destination)
  xyz1 = cat @ xyz0
  

• Bradford (colorio.cat.bradford)
• sharp (colorio.cat.sharp)
• CMCCAT2000 (colorio.cat.cmccat2000)
• CAT02 (colorio.cat.cat02)
• CAT16 (colorio.cat.cat16)
• Bianco-Schettini (colorio.cat.bianco_schettini)

Gamut visualization

colorio provides a number of useful tools for analyzing and visualizing color spaces.

sRGB gamut

CIELAB	CAM16-UCS	Oklab

The sRGB gamut is a perfect cube in sRGB space, and takes curious shapes when translated into other color spaces. The above images show the sRGB gamut in different color spaces.

import colorio

colorspace = colorio.cs.CIELAB()
p = colorio.plot_rgb_gamut(colorspace, n=51, show_grid=True)
p.show()

For more visualization options, you can store the sRGB data in a file

import colorio

colorspace = colorio.cs.CIELAB()
colorio.save_rgb_gamut("srgb.vtk", colorspace, n=51)
# all formats supported by https://github.com/nschloe/meshio

an open it with a tool of your choice. See here for how to open the file in ParaView.

For lightness slices of the sRGB gamut, use

import colorio

colorspace = colorio.cs.CIELAB()
p = colorio.plot_rgb_slice(colorspace, lightness=50.0, n=51)
p.show()
# or
# p.screenshot("screenshot.png")

Surface color gamut

XYZ	CIELAB	CAM16-UCS

Same as above, but with the surface color gamut visible under a given illuminant.

import colorio

illuminant = colorio.illuminants.d65()
observer = colorio.observers.cie_1931_2()

colorspace = colorio.cs.XYZ(100)

colorio.save_surface_gamut("surface.vtk", colorspace, observer, illuminant)
p = colorio.plot_surface_gamut(colorspace, observer, illuminant)
p.show()

The gamut is shown in grey since sRGB screens are not able to display the colors anyway.

The visible gamut

xyY	JzAzBz	Oklab

Same as above, but with the gamut of visible colors up to a given lightness Y.

import colorio

observer = colorio.observers.cie_1931_2()

colorspace = colorio.cs.XYZ(100)

p = colorio.plot_visible_gamut(colorspace, observer, max_Y1=1)
p.show()

The gamut is shown in grey since sRGB screens are not able to display the colors anyway.

For slices, use

import colorio

colorspace = colorio.cs.CIELAB()
plt = colorio.plot_visible_slice(colorspace, lightness=0.5)
plt.show()

Color gradients

With colorio, you can easily visualize the basic color gradients of any color space. This may make defects in color spaces obvious, e.g., the well-known blue-distortion of CIELAB and related spaces. (Compare with the hue linearity data below.)

import colorio

lab = colorio.cs.CIELAB()
plt = colorio.plot_primary_srgb_gradients(lab)
plt.show()

CIELAB	DIN99	OKLAB

Experimental data

colorio contains lots of experimental data sets some of which can be used to assess certain properties of color spaces. Most data sets can also be visualized.

Color differences

xyY	CIELAB	CAM16

Color difference data from MacAdam (1974). The above plots show the 43 color pairs that are of comparable lightness. The data is matched perfectly if the facing line stubs meet in one point.

import colorio

data = colorio.data.MacAdam1974()

cs = colorio.cs.CIELAB

plt = data.plot(cs)
plt.show()
print(colorio.data.MacAdam1974().stress(cs))

24.54774029343344

The same is available for

colorio.data.BfdP()
colorio.data.Leeds()
colorio.data.RitDupont()
colorio.data.Witt()

colorio.data.COMBVD()  # a weighted combination of the above

Munsell

xyY	CIELAB	CAM16

Munsell color data is visualized with

import colorio

cs = colorio.cs.CIELUV
plt = colorio.data.Munsell().plot(cs, V=5)
plt.show()

To retrieve the Munsell data in xyY format, use

import colorio

munsell = colorio.data.Munsell()

# munsell.h
# munsell.V
# munsell.C
# munsell.xyy

Ellipses

MacAdam ellipses (1942)

xyY (at Y=0.4)	CIELAB (at L=50)	CAM16 (at L=50)

The famous MacAdam ellipses (from this article) can be plotted with

import colorio

cs = colorio.cs.CIELUV
plt = colorio.data.MacAdam1942(50.0).plot(cs)
plt.show()

The better the colorspace matches the data, the closer the ellipses are to circles of the same size.

Luo-Rigg ellipses

xyY	CIELAB	CAM16

Likewise for Luo-Rigg.

import colorio

# xyy = colorio.cs.XYY(100)
# colorio.data.LuoRigg(8).show(xyy, 0.4)
# colorio.data.LuoRigg(8).savefig("luo-rigg-xyy.png", xyy, 0.4)

cieluv = colorio.cs.CIELUV()
plt = colorio.data.LuoRigg(8).plot(cieluv, 50)
plt.show()

Hue linearity

Ebner-Fairchild

xyY	CIELAB	CAM16

For example

import colorio

colorspace = colorio.cs.JzAzBz
plt = colorio.data.EbnerFairchild().plot(colorspace)
plt.show()

shows constant-hue data from the Ebner-Fairchild experiments in the hue-plane of some color spaces. (Ideally, all colors in one set sit on a line.)

Hung-Berns

Likewise for Hung-Berns:

xyY	CIELAB	CAM16

Note the dark blue distortion in CIELAB and CAM16.

import colorio

colorspace = colorio.cs.JzAzBz
plt = colorio.data.HungBerns().plot(colorspace)
plt.show()

Xiao et al.

Likewise for Xiao et al.:

xyY	CIELAB	CAM16

import colorio

colorspace = colorio.cs.CIELAB
plt = colorio.data.Xiao().plot(colorspace)
plt.show()

Lightness

Fairchild-Chen

xyY	CIELAB	CAM16

Lightness experiment by Fairchild-Chen.

import colorio

cs = colorio.cs.CIELAB
plt = colorio.data.FairchildChen("SL2").plot(cs)
plt.show()

Articles

• Algorithmic improvements for the CIECAM02 and CAM16 color appearance models, Nico Schlömer, 2018
• On the conversion from OSA-UCS to CIEXYZ, Nico Schlömer, 2019

Installation

colorio is available from the Python Package Index, so just use

pip install colorio

to install.

Testing

To run the tests, simply check out this repository and run

tox

License

This software is published under the GPLv3 license.