Skip to content
Tools for color models.
Branch: master
Clone or download
nschloe Merge pull request #38 from jamadagni/patch-1
Follow up to VTU > VTK format change in README
Latest commit 357d600 Apr 16, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.


Tools for color models.

CircleCI codecov Code style: black colorful PyPi Version DOI GitHub stars

All methods in colorio are fully vectorized.

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.

The following color spaces are implemented:

  • XYZ (colorio.XYZ())
  • xyY (colorio.XYY())
  • Linear SRGB (colorio.SrgbLinear()) This class has the two additional methods
    for conversion from and to standard RGB.
  • CIELAB (colorio.CIELAB())
  • CIELUV (colorio.CIELUV())
  • ICtCp (colorio.ICtCp())
  • IPT (colorio.IPT())
  • CIECAM02 / CAM02-UCS
    import colorio
    L_A = 64 / numpy.pi / 5
    ciecam02 = colorio.CIECAM02(0.69, 20, L_A)
    cam02 = colorio.CAM02('UCS', 0.69, 20, L_A)
    The implementation contains a few improvements over the CIECAM02 specification (see here).
  • CAM16 / CAM16-UCS
    L_A = 64 / numpy.pi / 5
    cam16 = colorio.CAM16(0.69, 20, L_A)
    cam16ucs = colorio.CAM16UCS(0.69, 20, L_A)
    The implementation contains a few improvements over the CAM16 specification (see here).
  • Jzazbz (colorio.JzAzBz())


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

Visualizing the SRGB gamut

The SRGB gamut is a perfect cube in SRGB space, and takes curious shapes when translated into other color spaces. The above image shows the SRGB gamut in XYZ space. The image data was created with

colorspace = colorio.CIELAB()
colorio.show_srgb_gamut(colorspace, "out.vtk", n=50, cut_000=False)

The VTK file can then be opened in, e.g., ParaView, where the following instructions apply:

  1. Open the file in ParaView and execute the following steps in the Properties tab to the left.
  2. Press the Apply button.
  3. Under the Coloring section, change Solid Color to srgb.
  4. If necessary, press the gear button to the right of the search field to activate advanced options.
  5. Under the Scalar Coloring section, uncheck Map Scalars.

More images are in the gh-pages branch.

The data can be written in most formats supported by meshio. (You might have to install additional packages for some formats.)

Visualizing the visible gamut

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

colorspace = colorio.XYZ()
illuminant = colorio.illuminants.d65()
observer = colorio.observers.cie_1931_2()
colorio.show_visible_gamut(colorspace, observer, illuminant, "visible.vtk")

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

The xy-gamut

Show the classical visible gamut in xy with Planckian locus and the SRGB colors (at maximum luminosity).


Show experimental data

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


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


For example

colorspace = colorio.JzAzBz()

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


Likewise for Hung-Berns:

colorspace = colorio.JzAzBz()
Xiao et al.

Likewise for Xiao et al.:

colorspace = colorio.CIELAB()

Munsell color data is visualized with

colorspace = colorio.CIELUV()
colorio.show_munsell(colorspace, V=5)

Color differences

Color differences in any space can be computed with, b).


colorio is available from the Python Package Index, so with

pip install -U colorio

you can install/upgrade.


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



To create a new release

  1. bump the __version__ number,

  2. publish to PyPi and GitHub:

    $ make publish


colorio is published under the MIT license.

You can’t perform that action at this time.