tessl/pypi-colormath

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Color Space Conversions

Name: tessl/pypi-colormath
Author: tessl

The color conversions module provides comprehensive functionality for converting colors between any supported color spaces. It uses a graph-based conversion engine that handles direct conversions where possible and multi-step transformations when needed.

Capabilities

Primary Conversion Function

The main conversion function that handles transformations between any color spaces.

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 (any ColorBase subclass)
    - target_cs: Target color space class (e.g., XYZColor, LabColor)
    - through_rgb_type: RGB color space for intermediate conversions (default: sRGBColor)
    - target_illuminant: Target illuminant for conversion (default: None, uses source illuminant)
    
    Returns:
    Color object in target color space
    
    Raises:
    - UndefinedConversionError: If conversion path doesn't exist
    - InvalidIlluminantError: If illuminant is invalid
    """

Matrix Operations

Low-level matrix operations for RGB color space transformations.

def apply_RGB_matrix(var1, var2, var3, rgb_type, convtype="xyz_to_rgb"):
    """
    Apply RGB conversion matrix to convert between XYZ and RGB.
    
    Parameters:
    - var1: X coordinate (XYZ) or R coordinate (RGB)
    - var2: Y coordinate (XYZ) or G coordinate (RGB)  
    - var3: Z coordinate (XYZ) or B coordinate (RGB)
    - rgb_type: RGB color space class (sRGBColor, AdobeRGBColor, etc.)
    - convtype: Conversion type ("xyz_to_rgb" or "rgb_to_xyz")
    
    Returns:
    tuple: Transformed color coordinates
    """

Supported Color Space Conversions

The conversion engine supports the following color spaces:

CIE Color Spaces

XYZ ↔ Lab ↔ Luv ↔ xyY
Lab ↔ LCHab
Luv ↔ LCHuv

RGB Color Spaces

sRGB ↔ Adobe RGB
RGB ↔ XYZ (with appropriate matrices)

Device Color Spaces

HSL ↔ HSV ↔ RGB
CMY ↔ CMYK ↔ RGB

Spectral and Advanced

Spectral → XYZ (via integration)
IPT ↔ XYZ

Conversion Paths

The conversion engine automatically determines the optimal path between color spaces:

Direct conversions when mathematical relationships exist
Multi-step conversions through intermediate color spaces
Illuminant adaptation when source and target illuminants differ
RGB intermediate conversions for device color spaces

Usage Examples

Basic Conversions

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

# Lab to XYZ
lab = LabColor(lab_l=50.0, lab_a=20.0, lab_b=-30.0)
xyz = convert_color(lab, XYZColor)

# XYZ to RGB
rgb = convert_color(xyz, sRGBColor)

# Direct Lab to RGB (automatic multi-step conversion)
rgb_direct = convert_color(lab, sRGBColor)

Illuminant Conversion

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

# Lab color with D65 illuminant
lab_d65 = LabColor(lab_l=50, lab_a=0, lab_b=0, illuminant='d65')

# Convert to XYZ with different illuminant
xyz_a = convert_color(lab_d65, XYZColor, target_illuminant='a')

# The conversion automatically applies chromatic adaptation

RGB Color Space Conversions

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

# sRGB to Adobe RGB
srgb = sRGBColor(rgb_r=0.8, rgb_g=0.4, rgb_b=0.2)
adobe_rgb = convert_color(srgb, AdobeRGBColor)

Complex Multi-Step Conversions

from colormath.color_objects import HSLColor, LabColor
from colormath.color_conversions import convert_color

# HSL to Lab (automatic path: HSL → RGB → XYZ → Lab)
hsl = HSLColor(hsl_h=120, hsl_s=0.8, hsl_l=0.6)
lab = convert_color(hsl, LabColor)

Spectral to XYZ Conversion

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

# Create spectral color
spectral = SpectralColor(
    spec_400nm=0.064,
    spec_410nm=0.065,
    # ... wavelength data
    spec_700nm=0.108,
    observer='2',
    illuminant='d65'
)

# Convert to XYZ via integration
xyz = convert_color(spectral, XYZColor)

Batch Conversions

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

# Convert multiple colors
lab_colors = [
    LabColor(50, 20, -30),
    LabColor(60, -10, 40),
    LabColor(40, 0, 0)
]

rgb_colors = [convert_color(lab, sRGBColor) for lab in lab_colors]

Conversion Performance

The conversion engine optimizes performance through:

Caching: Frequently used conversion matrices and constants
Direct paths: Shortest mathematical paths between color spaces
Batch operations: Efficient handling of multiple conversions
Lazy loading: Constants loaded only when needed

Error Handling

The conversion system provides specific error handling:

from colormath.color_exceptions import UndefinedConversionError, InvalidIlluminantError
from colormath.color_conversions import convert_color

try:
    result = convert_color(color, target_space)
except UndefinedConversionError:
    # Handle missing conversion path
    pass
except InvalidIlluminantError:
    # Handle invalid illuminant specification
    pass

Illuminant Handling

The conversion engine automatically handles illuminant differences:

Same illuminant: Direct conversion without adaptation
Different illuminants: Automatic chromatic adaptation applied
Target illuminant: Explicitly specify target illuminant
Default behavior: Preserve source illuminant when possible

Color Space Support Matrix

From/To	XYZ	Lab	Luv	RGB	HSL	HSV	CMY	CMYK	Spectral	IPT
XYZ	✓	✓	✓	✓	✓*	✓*	✓*	✓*	✗	✓
Lab	✓	✓	✓*	✓*	✓*	✓*	✓*	✓*	✗	✓*
Luv	✓	✓*	✓	✓*	✓*	✓*	✓*	✓*	✗	✓*
RGB	✓	✓*	✓*	✓	✓	✓	✓	✓	✗	✓*
HSL	✓*	✓*	✓*	✓	✓	✓	✓*	✓*	✗	✓*
HSV	✓*	✓*	✓*	✓	✓	✓	✓*	✓*	✗	✓*
CMY	✓*	✓*	✓*	✓	✓*	✓*	✓	✓	✗	✓*
CMYK	✓*	✓*	✓*	✓	✓*	✓*	✓	✓	✗	✓*
Spectral	✓	✓*	✓*	✓*	✓*	✓*	✓*	✓*	✓	✓*
IPT	✓	✓*	✓*	✓*	✓*	✓*	✓*	✓*	✗	✓