Tools for color research.
Installation
Install Coloria from PyPI with
pip install coloria
To run Coloria, you need a license. See here
for more info.
Illuminants, observers, white points
Illuminants | CIE 1931 Observer |
---|
| |
import coloria
import matplotlib.pyplot as plt
illu = coloria.illuminants.d65()
plt.plot(illu.lmbda_nm, illu.data)
plt.xlabel("wavelength [nm]")
plt.show()
The following illuminants are provided:
- Illuminant A ("indoor light",
coloria.illuminants.a(resolution_in_nm)
) - Illuminant C (obsolete, "North sky daylight",
coloria.illuminants.c()
) - Illuminants D ("natural daylight",
coloria.illuminants.d(nominal_temp)
or
coloria.illuminants.d65()
etc.) - Illuminant E (equal energy,
coloria.illuminants.e()
) - Illuminant series F ("fluorescent lighting",
coloria.illuminants.f2()
etc.)
Observers:
- CIE 1931 Standard 2-degree observer (
coloria.observers.coloria.observers.cie_1931_2()
) - CIE 1964 Standard 10-degree observer (
coloria.observers.coloria.observers.cie_1964_10()
)
Color appearance models
Color appearance models (CAMs) predicts all kinds of parameters in color perception,
e.g., lightness, brightness, chroma, colorfulness, saturation etc. Since these
values depend on various factors, such as the surrouning, the models are initialized
with various different parameters.
CAMs can be used to construct color spaces (see below).
The color appearance models available in coloria are
-
CIECAM02 / CAM02-UCS
import coloria
ciecam02 = coloria.cam.CIECAM02("average", 20, 100)
xyz = [19.31, 23.93, 10.14]
corr = ciecam02.from_xyz100(xyz)
corr.lightness
corr.brightness
corr.chroma
corr.hue_composition
corr.hue_angle_degrees
corr.colorfulness
corr.saturation
-
CAM16 / CAM16-UCS
import coloria
cam16 = coloria.cam.CAM16("average", 20, 100)
-
ZCAM
import coloria
cam16 = coloria.cam.ZCAM("average", 20, 100, 20)
Color coordinates and spaces
Color coordinates are handled as NumPy arrays or as ColorCoordinates
, a thin
wrapper around the data that retains the color space information and has some
handy helper methods. Color spaces can be instantiated from the classes in
coloria.cs
, e.g.,
import coloria
coloria.cs.CIELAB()
Most methods that accept such a colorspace also accept a string, e.g.,
cielab
.
As an example, to interpolate two sRGB colors in OKLAB, and return the sRGB:
from coloria.cs import ColorCoordinates
c0 = ColorCoordinates([1.0, 1.0, 0.0], "srgb1")
c1 = ColorCoordinates([0.0, 0.0, 1.0], "srgb1")
c0.convert("oklab")
c1.convert("oklab")
c2 = (c0 + c1) * 0.5
c2.convert("srgbhex", mode="clip")
print(c2.color_space)
print(c2.data)
<coloria color space sRGB-hex>
#6cabc7
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 (coloria.cs.XYZ(100)
, the
parameter determining the scaling)
-
xyY
(coloria.cs.XYY(100)
, the parameter determining the scaling of Y
)
-
sRGB (coloria.cs.SRGBlinear()
,
coloria.cs.SRGB1()
, coloria.cs.SRGB255()
, coloria.cs.SRGBhex()
)
-
HSL and HSV (coloria.cs.HSL()
,
coloria.cs.HSV()
)
These classes also have the two methods
from_srgb1()
to_srgb1()
for direct conversion from and to standard RGB.
-
OSA-UCS (coloria.cs.OsaUcs()
), 1947
-
CIELAB (coloria.cs.CIELAB()
), 1976
-
CIELUV (coloria.cs.CIELUV()
), 1976
-
RLAB (coloria.cs.RLAB()
), 1993
-
IPT
(coloria.cs.IPT()
),
1998
-
DIN99 and its variants DIN99{b,c,d} (coloria.cs.DIN99()
), 1999
-
CAM02-UCS, 2002
import coloria
cam02 = coloria.cs.CAM02("UCS", "average", 20, 100)
The implementation contains a few improvements over the CIECAM02
specification (see here).
-
CAM16-UCS, 2016
import coloria
cam16ucs = coloria.cs.CAM16UCS("average", 20, 100)
The implementation contains a few improvements over the CAM16
specification (see here).
-
SRLAB2 (coloria.cs.SRLAB2()
)
-
Jzazbz
(coloria.cs.JzAzBz()
), 2017
-
ICtCp (coloria.cs.ICtCp()
), 2018
-
IGPGTG
(coloria.cs.IGPGTG()
),
2020
-
proLab (coloria.cs.PROLAB()
), 2020
-
Oklab (coloria.cs.OKLAB()
), 2020
-
OkLCh (coloria.cs.OKLCH()
), 2020
-
HCT (coloria.cs.HCT()
/ HCTLAB
(coloria.cs.HCTLAB()
),
2022
All methods in coloria are fully vectorized, i.e., computation is really
fast.
Color difference formulas
coloria implements the following color difference formulas:
- CIE76
coloria.diff.cie76(lab1, lab2)
- CIE94
coloria.diff.cie94(lab1, lab2)
- CIEDE2000
coloria.diff.ciede2000(lab1, lab2)
- CMC l:c
coloria.diff.cmc(lab1, lab2)
Chromatic adaptation transforms
coloria implements the following CATs:
Gamut visualization
coloria provides a number of useful tools for analyzing and visualizing color spaces.
sRGB gamut
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 coloria
p = coloria.plot_rgb_gamut(
"cielab",
n=51,
show_grid=True,
)
p.show()
For more visualization options, you can store the sRGB data in a file
import coloria
coloria.save_rgb_gamut("srgb.vtk", "cielab", n=51)
and 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 coloria
p = coloria.plot_rgb_slice("cielab", lightness=50.0, n=51)
p.show()
Surface color gamut
Same as above, but with the surface color gamut visible under a given illuminant.
import coloria
illuminant = coloria.illuminants.d65()
observer = coloria.observers.cie_1931_2()
p = coloria.plot_surface_gamut(
"xyz100",
observer,
illuminant,
)
p.show()
The gamut is shown in grey since sRGB screens are not able to display the colors anyway.
The visible gamut
Same as above, but with the gamut of visible colors up to a given lightness Y
.
import coloria
observer = coloria.observers.cie_1931_2()
colorspace = coloria.cs.XYZ(100)
p = coloria.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 coloria
plt = coloria.plot_visible_slice("cielab", lightness=0.5)
plt.show()
Color gradients
With coloria, 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 coloria
plt = coloria.plot_primary_srgb_gradients("cielab")
plt.show()
Experimental data
coloria 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
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 coloria
data = coloria.data.MacAdam1974()
cs = coloria.cs.CIELAB
plt = data.plot(cs)
plt.show()
print(coloria.data.MacAdam1974().stress(cs))
24.54774029343344
The same is available for
coloria.data.BfdP()
coloria.data.Leeds()
coloria.data.RitDupont()
coloria.data.Witt()
coloria.data.COMBVD() # a weighted combination of the above
Munsell
Munsell color data is
visualized with
import coloria
cs = coloria.cs.CIELUV
plt = coloria.data.Munsell().plot(cs, V=5)
plt.show()
To retrieve the Munsell data in xyY format, use
import coloria
munsell = coloria.data.Munsell()
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 coloria
cs = coloria.cs.CIELUV
plt = coloria.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
Likewise for Luo-Rigg.
import coloria
cieluv = coloria.cs.CIELUV()
plt = coloria.data.LuoRigg(8).plot(cieluv, 50)
plt.show()
Hue linearity
Ebner-Fairchild
For example
import coloria
colorspace = coloria.cs.JzAzBz
plt = coloria.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:
Note the dark blue distortion in CIELAB and CAM16.
import coloria
colorspace = coloria.cs.JzAzBz
plt = coloria.data.HungBerns().plot(colorspace)
plt.show()
Xiao et al.
Likewise for Xiao et al.:
import coloria
colorspace = coloria.cs.CIELAB
plt = coloria.data.Xiao().plot(colorspace)
plt.show()
Lightness
Fairchild-Chen
Lightness experiment by Fairchild-Chen.
import coloria
cs = coloria.cs.CIELAB
plt = coloria.data.FairchildChen("SL2").plot(cs)
plt.show()
Articles