ColorAide

Common errors

• AttributeError: module 'coloraide' has no attribute 'Color'

  cause Attempting to access the `Color` class via `coloraide.Color` after `import coloraide`, when `Color` is intended for direct import.
  fix Change your import statement from `import coloraide` to `from coloraide import Color`.

• AttributeError: 'Color' object has no attribute 'in_pointer_gamut'

  cause Using the deprecated `in_pointer_gamut()` method, which was removed in ColorAide v8.1 and later.
  fix Replace `color_object.in_pointer_gamut()` with `color_object.in_gamut('pointer-gamut')`.

• ERROR: Package 'coloraide' requires a different Python version: >=3.10 but your Python is 3.9.x

  cause Attempting to install or run ColorAide v8.7 or newer with an unsupported Python version (e.g., Python 3.9).
  fix Upgrade your Python environment to version 3.10 or newer.

Warnings

• breaking ColorAide v8.7 dropped support for Python 3.9. Projects using older Python versions will encounter installation errors or runtime issues.
  Fix: Upgrade your Python environment to 3.10 or newer before installing ColorAide v8.7+.
• deprecated The methods `in_pointer_gamut()` and `fit_pointer_gamut()` were deprecated in v8.1 and are now removed. Attempting to use them will raise an `AttributeError`.
  Fix: Use `color.in_gamut('pointer-gamut')` and `color.fit('pointer-gamut')` respectively for checking and fitting to the Pointer Gamut.
• gotcha As of v8.8, `luminance()` returns luminance relative to D65 by default (WCAG recommended), while the new `Y()` method returns luminance relative to the current color space's white point.
  Fix: Be mindful of which luminance function you use. If you need luminance relative to the current color space's white point, use `color.Y()`. For D65-relative luminance, `color.luminance()` remains the correct choice.
• gotcha In v8.7, spline interpolation `monotone` end point conditions were changed to `not-a-knot` by default to prevent overshoot. This might subtly alter interpolation results if you relied on the previous behavior.
  Fix: If specific end point conditions are critical for your interpolation, explicitly configure them using the `end_conditions` parameter in interpolation methods.
• gotcha The new `scale` gamut mapping method introduced in v8.4 is now used by default for conversions from `from_wavelengths()`, `blackbody()`, and `chromaticity()`. This changes how out-of-gamut colors are handled in these specific conversions.
  Fix: Review results from these conversion functions. If previous gamut mapping behavior is desired, or custom `scale` options are needed, explicitly pass the relevant parameters to these functions.

Install

• pip install coloraide Install stable version

Imports

• Color
  wrong:

  import coloraide; c = coloraide.Color('red')

  correct:

  from coloraide import Color

  The primary Color class is typically imported directly from the top-level package.

Quickstart

Demonstrates creating colors, converting between color spaces, mixing colors, checking gamut, and fitting colors to a target gamut using the `Color` class.

from coloraide import Color

# Create a color from a name or hex string
c = Color('red')
print(f"Initial color: {c.to_string()}")

# Convert to another color space and print
srgb_color = c.convert('srgb')
print(f"sRGB: {srgb_color.to_string(hex=True)}")

# Mix two colors
c1 = Color('blue')
c2 = Color('green')
mixed_color = c1.mix(c2, space='srgb', amount=0.5)
print(f"Mixed color: {mixed_color.to_string(hex=True)}")

# Check if a color is in gamut
p3_color = Color('color(--display-p3 0.9 0.1 0.5)')
print(f"Is P3 color in sRGB gamut? {p3_color.in_gamut('srgb')}")

# Fit a color to a gamut
out_of_gamut = Color('color(--rec2020 0.9 0.1 0.5)')
fit_srgb = out_of_gamut.fit('srgb')
print(f"Out of gamut: {out_of_gamut.to_string()}, Fit to sRGB: {fit_srgb.to_string()}")