{"id":8027,"library":"colormath","title":"Color Math and Conversion Library","description":"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.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/gtaylor/python-colormath","tags":["color","math","conversion","color space","cie","rgb","lab","delta e"],"install":[{"cmd":"pip install colormath","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for core mathematical operations.","package":"numpy","optional":false},{"reason":"Introduced in 2.1.0/2.1.1 for graph-based color conversion resolution.","package":"networkx","optional":false}],"imports":[{"symbol":"LabColor","correct":"from colormath.color_objects import LabColor"},{"symbol":"XYZColor","correct":"from colormath.color_objects import XYZColor"},{"note":"As of v2.0.0, the generic `RGBColor` class was replaced by specific RGB color space classes like `sRGBColor`, `AdobeRGBColor`, etc.","wrong":"from colormath.color_objects import RGBColor","symbol":"sRGBColor","correct":"from colormath.color_objects import sRGBColor"},{"note":"As of v2.0.0, the `ColorBase.convert_to()` method was removed in favor of the `colormath.color_conversions.convert_color()` function.","wrong":"color_object.convert_to('target_space')","symbol":"convert_color","correct":"from colormath.color_conversions import convert_color"}],"quickstart":{"code":"from colormath.color_objects import LabColor, XYZColor\nfrom colormath.color_conversions import convert_color\n\n# Instantiate a CIE Lab color object\nlab = LabColor(lab_l=50.0, lab_a=20.0, lab_b=-15.0)\nprint(f\"Original LabColor: {lab}\")\n\n# Convert the Lab color to XYZ color space\nxyz = convert_color(lab, XYZColor)\nprint(f\"Converted XYZColor: {xyz}\")\n\n# You can access individual components\nprint(f\"X coordinate: {xyz.xyz_x}\")\nprint(f\"Y coordinate: {xyz.xyz_y}\")\nprint(f\"Z coordinate: {xyz.xyz_z}\")","lang":"python","description":"This quickstart demonstrates how to instantiate a LabColor object and convert it to the XYZColor space using the `convert_color` function."},"warnings":[{"fix":"Replace `color_object.convert_to()` with `colormath.color_conversions.convert_color(color_object, TargetColorClass)`. Replace `RGBColor` with `sRGBColor` or another appropriate `BaseRGBColor` subclass.","message":"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`).","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"In version 2.0.0, RGB color channels were changed from `[1-255]` to `[0-1]` for consistency with scientific notation.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Explicitly specify the desired `target_illuminant` keyword argument in the `convert_color()` function (e.g., `convert_color(rgb_color, XYZColor, target_illuminant='d50')`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Converting between certain color spaces might require an intermediate trip through an RGB color space. The default intermediate RGB type is `sRGBColor`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Use the module-level `convert_color()` function: `from colormath.color_conversions import convert_color; new_color = convert_color(old_color, TargetColorClass)`.","cause":"Attempting to use the deprecated `convert_to()` method on a color object after upgrading to v2.0.0 or later.","error":"AttributeError: 'LabColor' object has no attribute 'convert_to'"},{"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)`.","cause":"Attempting to import or instantiate the generic `RGBColor` class which was removed in v2.0.0.","error":"NameError: name 'RGBColor' is not defined"},{"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)`.","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.","error":"ValueError: R, G, B values must be between 0.0 and 1.0. Got X"}]}