python-colormath

To use colormath, ensure your environment meets the following requirements:

• numpy
• NetworkX 2.0 or higher
• Python 2.7 or Python 3.5 or higher

Note: This module is no longer actively maintained.

If you are contributing to the project or need development tools, install the package with the development extra.

$ pip install 'colormath[development]'

Delta E equations quantify the visual difference between two LabColor instances. The library provides several implementations depending on the required precision and application context.

To calculate a difference, import the desired Delta E function from colormath.color_diff and pass two LabColor objects as arguments. The function returns the Delta E value as a float.

from colormath.color_objects import LabColor
from colormath.color_diff import delta_e_cie1976

# Reference color
color1 = LabColor(lab_l=0.9, lab_a=16.3, lab_b=-2.22)
# Color to be compared to the reference
color2 = LabColor(lab_l=0.7, lab_a=14.2, lab_b=-1.80)

# Calculate Delta E value as a float
delta_e = delta_e_cie1976(color1, color2)

When converting from an RGB space to a CIE space (like XYZ, Lab, LCH, or Luv), the conversion passes through the XYZ color space. RGB spaces have native illuminants (e.g., sRGB uses D65).

To override the default native illuminant and explicitly request a specific one, provide the target_illuminant keyword argument to convert_color.

from colormath.color_objects import XYZColor, sRGBColor
from colormath.color_conversions import convert_color

# Note: Ensure RGBColor is imported or use sRGBColor
rgb = sRGBColor(0.1, 0.2, 0.3)
xyz = convert_color(rgb, XYZColor, target_illuminant='d50')

Install the colormath package using pip. This is the easiest way to get started with color space conversions, Delta E calculations, and density to spectral operations.

$ pip install colormath

On Linux or macOS, you can install colormath using pip or easy_install.

pip install colormath

Some color conversions (e.g., XYZ to HSL or XYZ to CMYK) require an intermediate step through an RGB color space. By default, sRGB is used. If you need to use a different RGB space to maintain color accuracy or gamut characteristics, use the through_rgb_type keyword argument in convert_color.

Note: If you convert from Space A $\rightarrow$ Space B $\rightarrow$ Space A, ensure you use the same through_rgb_type for both directions to avoid color shifts.

from colormath.color_objects import XYZColor, HSLColor, AdobeRGBColor
from colormath.color_conversions import convert_color

xyz = XYZColor(0.1, 0.2, 0.3)
# Convert using AdobeRGB as the intermediate step
hsl = convert_color(xyz, HSLColor, through_rgb_type=AdobeRGBColor)

# Convert back using the same intermediate space to preserve accuracy
xyz2 = convert_color(hsl, XYZColor, through_rgb_type=AdobeRGBColor)

When working with color spaces that use reflective light, you can specify the illuminant and the observer angle during initialization. This is done using the observer and illuminant keyword arguments in the LabColor class.

lab = LabColor(0.1, 0.2, 0.3, observer='10', illuminant='d65')

Density can be calculated from SpectralColor instances using two primary functions in colormath.density:

1. auto_density(color): Calculates the density automatically based on the provided color object.
2. ansi_density(color, filter): Calculates the density using a specific filter constant provided by colormath.density_standards.

Both functions accept SpectralColor objects as input.

from colormath.color_objects import SpectralColor
from colormath.density import auto_density, ansi_density
from colormath.density_standards import ANSI_STATUS_T_RED

# Create a SpectralColor instance
color = SpectralColor(spec_340nm=0.08)

# Calculate automatic density
density = auto_density(color)

# Calculate density using a specific ANSI filter
red_density = ansi_density(color, ANSI_STATUS_T_RED)

The CIECAM02 class computes perceptual correlates based on the CIECAM02 color appearance model. It requires the XYZ components of the color stimulus, the XYZ components of the illuminant, and several viewing condition parameters.

Parameters:

• color_x, color_y, color_z: XYZ components of the color stimulus.
• illuminant_x, illuminant_y, illuminant_z: XYZ components of the illuminant.
• y_b: Background relative luminance.
• l_a: Adapting luminance.
• c: Surround condition (e.g., 0.69 for average).
• n_c: Surround condition.
• f: Surround condition.

model = CIECAM02(color_x, color_y, color_z, illuminant_x, illuminant_y, illuminant_z, y_b, l_a, c, n_c, f)