or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

chromatic-adaptation.mdcolor-appearance-models.mdcolor-conversions.mdcolor-diff.mdcolor-objects.mdconstants-standards.mdindex.mdspectral-density.md
tile.json

tessl/pypi-colormath

Color math and conversion library for comprehensive color space transformations and color difference calculations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/colormath@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-colormath@2.1.0

index.mddocs/

Colormath

A comprehensive Python library for color mathematics and conversions between different color spaces. It implements extensive color operations including color space conversions (RGB, Lab, XYZ, etc.), Delta E calculations for measuring color differences, density to spectral conversions, and chromatic adaptation algorithms. The library is designed for scientific and technical applications requiring precise color calculations.

Package Information

  • Package Name: colormath
  • Language: Python
  • Installation: pip install colormath
  • Dependencies: numpy, networkx

Core Imports

import colormath

Common for working with color objects:

from colormath.color_objects import LabColor, XYZColor, sRGBColor, SpectralColor
from colormath.color_conversions import convert_color
from colormath.color_diff import delta_e_cie2000

Basic Usage

from colormath.color_objects import LabColor, XYZColor, sRGBColor
from colormath.color_conversions import convert_color
from colormath.color_diff import delta_e_cie2000

# Create a Lab color
lab = LabColor(lab_l=0.9, lab_a=16.3, lab_b=-2.22)

# Convert to XYZ color space
xyz = convert_color(lab, XYZColor)

# Convert to RGB for display
rgb = convert_color(lab, sRGBColor)
print(f"RGB: {rgb.rgb_r:.3f}, {rgb.rgb_g:.3f}, {rgb.rgb_b:.3f}")

# Get RGB as hex string
hex_color = rgb.get_rgb_hex()
print(f"Hex: {hex_color}")

# Calculate color difference
lab2 = LabColor(lab_l=0.7, lab_a=14.2, lab_b=-1.80)
diff = delta_e_cie2000(lab, lab2)
print(f"Delta E: {diff:.2f}")

# Work with RGB colors
rgb_color = sRGBColor(255, 128, 0, is_upscaled=True)  # 0-255 values
hex_from_rgb = rgb_color.get_rgb_hex()  # "#ff8000"
rgb_from_hex = sRGBColor.new_from_rgb_hex("#ff8000")

Architecture

Colormath follows a structured hierarchy for color science operations:

  • Color Objects: Individual color space representations (Lab, XYZ, RGB, etc.) with illuminant and observer support
  • Color Conversions: Graph-based conversion engine supporting direct and multi-step transformations between 14+ color spaces
  • Color Differences: Perceptual difference calculations using multiple Delta E algorithms
  • Constants & Standards: Comprehensive collections of illuminants, observers, and industry standards
  • Spectral Processing: Full spectral power distribution support with density calculations
  • Color Appearance Models: Advanced models for sophisticated color science applications

This design enables precise color calculations for professional applications in computer graphics, printing, textiles, and scientific research.

Capabilities

Color Objects and Spaces

Create and manipulate colors in 14+ different color spaces including CIE Lab, XYZ, RGB variants, spectral data, and more. Each color space supports appropriate illuminants and observers.

class LabColor:
    def __init__(self, lab_l, lab_a, lab_b, observer='2', illuminant='d50'): ...

class XYZColor:
    def __init__(self, xyz_x, xyz_y, xyz_z, observer='2', illuminant='d50'): ...

class sRGBColor:
    def __init__(self, rgb_r, rgb_g, rgb_b, is_upscaled=False): ...

class SpectralColor:
    def __init__(self, spec_340nm=0.0, spec_350nm=0.0, ..., spec_830nm=0.0, observer='2', illuminant='d50'): ...

Color Objects and Spaces

Color Space Conversions

Convert between any supported color spaces using a comprehensive conversion engine that handles illuminant adaptation and multi-step transformations.

def convert_color(color, target_cs, through_rgb_type=sRGBColor, target_illuminant=None):
    """
    Convert color from one space to another.
    
    Parameters:
    - color: Source color object
    - target_cs: Target color space class
    - through_rgb_type: RGB color space for intermediate conversions
    - target_illuminant: Target illuminant for conversion
    
    Returns:
    Color object in target color space
    """

Color Space Conversions

Color Difference Calculations

Calculate perceptual color differences using industry-standard Delta E algorithms including CIE 1976, CIE 1994, CIE 2000, and CMC.

def delta_e_cie2000(color1, color2, Kl=1, Kc=1, Kh=1):
    """
    Calculate CIE 2000 Delta E difference.
    
    Parameters:
    - color1, color2: Color objects to compare
    - Kl, Kc, Kh: Weighting factors for lightness, chroma, hue
    
    Returns:
    float: Delta E difference value
    """

def delta_e_cie1976(color1, color2): ...
def delta_e_cie1994(color1, color2, K_L=1, K_C=1, K_H=1, K_1=0.045, K_2=0.015): ...
def delta_e_cmc(color1, color2, pl=2, pc=1): ...

Color Difference Calculations

Spectral Color and Density

Work with spectral power distributions and calculate color densities using industry standards for applications in printing and color reproduction.

def auto_density(color):
    """
    Automatically calculate density for spectral color.
    
    Parameters:
    - color: SpectralColor object
    
    Returns:
    float: Calculated density value
    """

def ansi_density(color, density_standard): ...

Spectral Color and Density

Constants and Standards

Access comprehensive collections of illuminants, observers, density standards, and other color science constants used throughout the library.

# Illuminant constants
ILLUMINANTS: dict  # Illuminant XYZ values by observer angle
OBSERVERS: list    # Available observer angles ('2', '10')

# Color constants  
CIE_E: float      # CIE epsilon constant
CIE_K: float      # CIE kappa constant

# Density standards
ANSI_STATUS_T_RED: dict
ISO_VISUAL: dict
VISUAL_DENSITY_THRESH: float

Constants and Standards

Color Appearance Models

Advanced color appearance models for sophisticated color science applications including CIE CAM02, RLAB, LLAB, and others.

class CIECAM02:
    def __init__(self, xyz, **viewing_conditions): ...

class RLAB:
    def __init__(self, xyz, **parameters): ...

Color Appearance Models

Chromatic Adaptation

Low-level chromatic adaptation functions for precise color transformations between different illuminants using Bradford, Von Kries, and other adaptation methods.

def apply_chromatic_adaptation(val_x, val_y, val_z, orig_illum, targ_illum, adaptation='bradford'):
    """
    Apply chromatic adaptation to XYZ values.
    
    Parameters:
    - val_x, val_y, val_z: XYZ color values
    - orig_illum: Original illuminant name
    - targ_illum: Target illuminant name  
    - adaptation: Adaptation method ('bradford', 'von_kries', etc.)
    
    Returns:
    tuple: Adapted XYZ values
    """

Chromatic Adaptation

Error Handling

Colormath defines custom exceptions for color-specific error handling:

class ColorMathException(Exception):
    """Base exception class for colormath errors."""

class UndefinedConversionError(ColorMathException):
    """Raised when conversion doesn't exist."""

class InvalidIlluminantError(ColorMathException):
    """Raised for invalid illuminants."""

class InvalidObserverError(ColorMathException):
    """Raised for invalid observer angles."""