Color Math and Conversion Library

3.0.0 · active · verified Thu Apr 16

colormath is a Python library that simplifies complex color mathematics and conversions. The current stable version is 3.0.0. It provides support for a wide range of color spaces (e.g., CIE Lab, XYZ, sRGB, HSL, HSV, CMY/CMYK), enabling conversions between them, calculation of color differences (Delta E), and chromatic adaptations. The project maintains an active status with ongoing documentation updates, though code releases are less frequent.

Common errors

```
AttributeError: 'LabColor' object has no attribute 'convert_to'
```
cause Attempting to use the deprecated `convert_to()` method on a color object after upgrading to v2.0.0 or later.

fix Use the module-level `convert_color()` function: `from colormath.color_conversions import convert_color; new_color = convert_color(old_color, TargetColorClass)`.
```
NameError: name 'RGBColor' is not defined
```
cause Attempting to import or instantiate the generic `RGBColor` class which was removed in v2.0.0.

fix Replace `RGBColor` with a specific RGB color space class, most commonly `sRGBColor`: `from colormath.color_objects import sRGBColor; my_srgb = sRGBColor(r, g, b)`.
```
ValueError: R, G, B values must be between 0.0 and 1.0. Got X
```
cause Providing RGB values in the `[0-255]` range to an RGB color class constructor when the library expects `[0.0-1.0]`. This change occurred in v2.0.0.

fix Normalize your RGB values to `[0.0, 1.0]`. Alternatively, use `is_upscaled=True` in the constructor if you intend to pass `[0-255]` values, although `[0.0-1.0]` is the recommended standard. For example: `sRGBColor(r/255.0, g/255.0, b/255.0)` or `sRGBColor(r, g, b, is_upscaled=True)`.

Warnings

breaking Version 2.0.0 introduced significant breaking changes, notably removing `ColorBase.convert_to()` and replacing `RGBColor` with specific RGB color space classes (e.g., `sRGBColor`).
Fix: Replace `color_object.convert_to()` with `colormath.color_conversions.convert_color(color_object, TargetColorClass)`. Replace `RGBColor` with `sRGBColor` or another appropriate `BaseRGBColor` subclass.
breaking In version 2.0.0, RGB color channels were changed from `[1-255]` to `[0-1]` for consistency with scientific notation.
Fix: Ensure RGB input values are normalized to `[0.0, 1.0]`. If you need the `[1-255]` range, use the `is_upscaled=True` parameter in constructors or `get_upscaled_value_tuple()` where available.
gotcha When converting from RGB to a reflective color space (like XYZ) that relies on an illuminant, the RGB space's native illuminant is used by default. This can lead to unexpected results if not accounted for.
Fix: Explicitly specify the desired `target_illuminant` keyword argument in the `convert_color()` function (e.g., `convert_color(rgb_color, XYZColor, target_illuminant='d50')`).
gotcha Converting between certain color spaces might require an intermediate trip through an RGB color space. The default intermediate RGB type is `sRGBColor`.
Fix: If your conversion chain is producing unexpected results or clipping colors, consider explicitly setting the `through_rgb_type` parameter in `convert_color()` to a different RGB space (e.g., `AdobeRGBColor`) if a wider gamut is needed.

Install

pip install colormath Install stable version

Imports

LabColor

from colormath.color_objects import LabColor

XYZColor

from colormath.color_objects import XYZColor

sRGBColor
wrong:
```
from colormath.color_objects import RGBColor
```
correct:
```
from colormath.color_objects import sRGBColor
```
As of v2.0.0, the generic `RGBColor` class was replaced by specific RGB color space classes like `sRGBColor`, `AdobeRGBColor`, etc.
convert_color
wrong:
```
color_object.convert_to('target_space')
```
correct:
```
from colormath.color_conversions import convert_color
```
As of v2.0.0, the `ColorBase.convert_to()` method was removed in favor of the `colormath.color_conversions.convert_color()` function.

Quickstart

This quickstart demonstrates how to instantiate a LabColor object and convert it to the XYZColor space using the `convert_color` function.

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

# Instantiate a CIE Lab color object
lab = LabColor(lab_l=50.0, lab_a=20.0, lab_b=-15.0)
print(f"Original LabColor: {lab}")

# Convert the Lab color to XYZ color space
xyz = convert_color(lab, XYZColor)
print(f"Converted XYZColor: {xyz}")

# You can access individual components
print(f"X coordinate: {xyz.xyz_x}")
print(f"Y coordinate: {xyz.xyz_y}")
print(f"Z coordinate: {xyz.xyz_z}")

view raw JSON →