Package: coloria
Tools for color research.InstallationInstall Coloriafrom PyPIwithpip install coloriaTo run Coloria, you need a license. Seeherefor more info.Illuminants, observers, white pointsIlluminantsCIE 1931 Observerimportcoloriaimportmatplotlib.pyplotaspltillu=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)orcoloria.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 modelsColor 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 colorspaces(see below).The color appearance models available in coloria areCIECAM02 / CAM02-UCSimportcoloriaciecam02=coloria.cam.CIECAM02("average",20,100)# parameters:# c:   surround parameter# Y_b: relative background luminance# L_A: luminance of the adapting fieldxyz=[19.31,23.93,10.14]corr=ciecam02.from_xyz100(xyz)# then work with those values:corr.lightnesscorr.brightnesscorr.chromacorr.hue_compositioncorr.hue_angle_degreescorr.colorfulnesscorr.saturationCAM16 / CAM16-UCSimportcoloriacam16=coloria.cam.CAM16("average",20,100)ZCAMimportcoloriacam16=coloria.cam.ZCAM("average",20,100,20)Color coordinates and spacesColor coordinates are handled as NumPy arrays or asColorCoordinates, 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 incoloria.cs, e.g.,importcoloriacoloria.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:fromcoloria.csimportColorCoordinates# you can also plug in large numpy arrays instead of two lists herec0=ColorCoordinates([1.0,1.0,0.0],"srgb1")# yellowc1=ColorCoordinates([0.0,0.0,1.0],"srgb1")# blue# naive interpolation gives [0.5, 0.5, 0.5], a mid gray# convert to OKLABc0.convert("oklab")c1.convert("oklab")# interpolatec2=(c0+c1)*0.5c2.convert("srgbhex",mode="clip")print(c2.color_space)print(c2.data)<coloria color space sRGB-hex>
#6cabc7All color spaces implement the two methodsvals=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 ofY)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 methodsfrom_srgb1()
to_srgb1()for direct conversion from and to standard RGB.OSA-UCS (coloria.cs.OsaUcs()), 1947CIELAB (coloria.cs.CIELAB()), 1976CIELUV (coloria.cs.CIELUV()), 1976RLAB (coloria.cs.RLAB()), 1993IPT
(coloria.cs.IPT()),
1998DIN99 and its variants DIN99{b,c,d} (coloria.cs.DIN99()), 1999CAM02-UCS, 2002importcoloriacam02=coloria.cs.CAM02("UCS","average",20,100)The implementation contains a few improvements over the CIECAM02
specification (seehere).CAM16-UCS, 2016importcoloriacam16ucs=coloria.cs.CAM16UCS("average",20,100)The implementation contains a few improvements over the CAM16
specification (seehere).SRLAB2 (coloria.cs.SRLAB2())Jzazbz(coloria.cs.JzAzBz()), 2017ICtCp (coloria.cs.ICtCp()), 2018IGPGTG(coloria.cs.IGPGTG()),
2020proLab (coloria.cs.PROLAB()), 2020Oklab (coloria.cs.OKLAB()), 2020OkLCh (coloria.cs.OKLCH()), 2020HCT (coloria.cs.HCT()/ HCTLAB
(coloria.cs.HCTLAB()),
2022All methods in coloria are fully vectorized, i.e., computation isreallyfast.Color difference formulascoloria implements the following color difference formulas:CIE76coloria.diff.cie76(lab1,lab2)CIE94coloria.diff.cie94(lab1,lab2)CIEDE2000coloria.diff.ciede2000(lab1,lab2)CMC l:ccoloria.diff.cmc(lab1,lab2)Chromatic adaptation transformscoloria implements the following CATs:von Kriescat,cat_inv=coloria.cat.von_kries(whitepoint_source,whitepoint_destination)xyz1=cat@xyz0Bradford (coloria.cat.bradford)sharp (coloria.cat.sharp)CMCCAT2000 (coloria.cat.cmccat2000)CAT02 (coloria.cat.cat02)CAT16 (coloria.cat.cat16)Bianco-Schettini (coloria.cat.bianco_schettini)Gamut visualizationcoloria provides a number of useful tools for analyzing and visualizing color spaces.sRGB gamutCIELABCAM16-UCSOklabThe 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.importcoloriap=coloria.plot_rgb_gamut("cielab",# or coloria.cs.CIELAB()n=51,show_grid=True,)p.show()For more visualization options, you can store the sRGB data in a fileimportcoloriacoloria.save_rgb_gamut("srgb.vtk","cielab",n=51)# all formats supported by https://github.com/coloria-dev/meshioand open it with a tool of your choice. Seeherefor how to open
the file inParaView.For lightness slices of the sRGB gamut, useimportcoloriap=coloria.plot_rgb_slice("cielab",lightness=50.0,n=51)p.show()# or# p.screenshot("screenshot.png")Surface color gamutXYZCIELABCAM16-UCSSame as above, but with the surface color gamut visible under a given illuminant.importcoloriailluminant=coloria.illuminants.d65()observer=coloria.observers.cie_1931_2()p=coloria.plot_surface_gamut("xyz100",# or coloria.cs.XYZ(100)observer,illuminant,)p.show()The gamut is shown in grey since sRGB screens are not able to display the colors anyway.The visible gamutxyYJzAzBzOklabSame as above, but with the gamut of visible colors up to a given lightnessY.importcoloriaobserver=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, useimportcoloriaplt=coloria.plot_visible_slice("cielab",lightness=0.5)plt.show()Color gradientsWith 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 withthe hue linearity data
below.)importcoloriaplt=coloria.plot_primary_srgb_gradients("cielab")plt.show()CIELABDIN99OKLABExperimental datacoloria 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 differencesxyYCIELABCAM16Color difference data fromMacAdam (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.importcoloriadata=coloria.data.MacAdam1974()cs=coloria.cs.CIELABplt=data.plot(cs)plt.show()print(coloria.data.MacAdam1974().stress(cs))24.54774029343344The same is available forcoloria.data.BfdP()
coloria.data.Leeds()
coloria.data.RitDupont()
coloria.data.Witt()

coloria.data.COMBVD()  # a weighted combination of the aboveMunsellxyYCIELABCAM16Munsell color datais
visualized withimportcoloriacs=coloria.cs.CIELUVplt=coloria.data.Munsell().plot(cs,V=5)plt.show()To retrieve the Munsell data in xyY format, useimportcoloriamunsell=coloria.data.Munsell()# munsell.h# munsell.V# munsell.C# munsell.xyyEllipsesMacAdam ellipses (1942)xyY (at Y=0.4)CIELAB (at L=50)CAM16 (at L=50)The famous MacAdam ellipses (fromthis
article) can be plotted withimportcoloriacs=coloria.cs.CIELUVplt=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 ellipsesxyYCIELABCAM16Likewise forLuo-Rigg.importcoloria# xyy = coloria.cs.XYY(100)# coloria.data.LuoRigg(8).show(xyy, 0.4)# coloria.data.LuoRigg(8).savefig("luo-rigg-xyy.png", xyy, 0.4)cieluv=coloria.cs.CIELUV()plt=coloria.data.LuoRigg(8).plot(cieluv,50)plt.show()Hue linearityEbner-FairchildxyYCIELABCAM16For exampleimportcoloriacolorspace=coloria.cs.JzAzBzplt=coloria.data.EbnerFairchild().plot(colorspace)plt.show()shows constant-hue data fromthe Ebner-Fairchild
experimentsin the hue-plane of some color spaces.
(Ideally, all colors in one set sit on a line.)Hung-BernsLikewise forHung-Berns:xyYCIELABCAM16Note the dark blue distortion in CIELAB and CAM16.importcoloriacolorspace=coloria.cs.JzAzBzplt=coloria.data.HungBerns().plot(colorspace)plt.show()Xiao et al.Likewise forXiao et al.:xyYCIELABCAM16importcoloriacolorspace=coloria.cs.CIELABplt=coloria.data.Xiao().plot(colorspace)plt.show()LightnessFairchild-ChenxyYCIELABCAM16Lightness experiment byFairchild-Chen.importcoloriacs=coloria.cs.CIELABplt=coloria.data.FairchildChen("SL2").plot(cs)plt.show()ArticlesAlgorithmic improvements for the CIECAM02 and CAM16 color appearance models,
Nico Schlömer, 2018On the conversion from OSA-UCS to CIEXYZ, Nico Schlömer,
2019