Skip to main content

Tools for color models

Project description

colorio

Tools for color models.

PyPi Version PyPI pyversions DOI GitHub stars PyPi downloads

gh-actions codecov LGTM Code style: black

Color spaces

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.

colorspace.to_rgb_linear(vals)
colorspace.to_rgb1(vals)
colorspace.to_rgb255(vals)

# same for from_rgb*

The following color spaces are 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 two additional methods
    from_rgb1()
    to_rgb1()
    
    for conversion from and to standard RGB.
  • 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
    
    L_A = 64 / math.pi / 5
    ciecam02 = colorio.cs.CIECAM02(0.69, 20, L_A)
    cam02 = colorio.cs.CAM02("UCS", 0.69, 20, L_A)
    
    The implementation contains a few improvements over the CIECAM02 specification (see here).
  • CAM16 / CAM16-UCS
    import math
    import colorio
    
    L_A = 64 / math.pi / 5
    cam16 = colorio.cs.CAM16(0.69, 20, L_A)
    cam16ucs = colorio.cs.CAM16UCS(0.69, 20, L_A)
    
    The implementation contains a few improvements over the CAM16 specification (see here).
  • Jzazbz (colorio.cs.JzAzBz())
  • Oklab(colorio.cs.OKLAB())
  • proLab(colorio.cs.PROLAB())

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)
    

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()
colorio.show_rgb_gamut(colorspace, n=51, show_grid=True, camera_position=None)

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()
colorio.show_rgb_slice(colorspace, lightness=0.5, n=51)
# or
# save_rgb_slice()
# plot_rgb_slice()

The plot_rgb_slice() method is especially useful for combining with other plots.

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)
colorio.show_surface_gamut(colorspace, observer, illuminant)

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)

colorio.save_visible_gamut("visible.vtk", colorspace, observer, max_Y1=1)
colorio.show_visible_gamut(colorspace, observer, max_Y1=1)

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()
colorio.show_visible_slice(colorspace, lightness=0.5)
# or
# save_visible_slice()
# plot_visible_slice()

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 arrow tips meet in one point.

import colorio

cs = colorio.cs.CIELAB()
colorio.data.MacAdam1974().show(cs)
print(colorio.data.MacAdam1974().stress(cs))
24.531919167387624

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

which, combined and weighted, form the COMBVD color difference data set.

Munsell

xyY CIELAB CAM16

Munsell color data is visualized with

import colorio

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

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

# xyy = colorio.cs.XYY(100)
# colorio.data.MacAdam1942(50.0).show(xyy)
# colorio.data.MacAdam1942(50.0).savefig("macadam-xyy.png", xyy)

cieluv = colorio.cs.CIELUV()
colorio.data.MacAdam1942(50.0).show(cieluv)

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()
colorio.data.LuoRigg(8).show(cieluv, 50)

Hue linearity

Ebner-Fairchild
xyY CIELAB CAM16

For example

import colorio

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

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()
colorio.data.HungBerns().show(colorspace)
Xiao et al.

Likewise for Xiao et al.:

xyY CIELAB CAM16
import colorio

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

Lightness

Fairchild-Chen
xyY CIELAB CAM16

Lightness experiment by Fairchild-Chen.

import colorio

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

Articles

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for colorio, version 0.7.3
Filename, size File type Python version Upload date Hashes
Filename, size colorio-0.7.3-py3-none-any.whl (289.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size colorio-0.7.3.tar.gz (280.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page