Colorspacious

Common errors

• TypeError: cspace_convert() got multiple values for argument 'target_cspace'

  cause Using the pre-v1.0.0 argument order for `cspace_convert` where `target_cspace` was the third positional argument. The post-v1.0.0 API uses `out_cspace`.
  fix Update your code to use `cspace_convert(data, in_cspace='...', out_cspace='...')` or `cspace_convert(data, '...', '...')` where the second and third arguments are now `in_cspace` and `out_cspace` respectively.

• AttributeError: module 'colorspacious' has no attribute 'CIELCh_from_CIELab'

  cause Attempting to use a direct conversion function that was removed in `colorspacious` v1.0.0 and later.
  fix Replace the direct function call with `colorspacious.cspace_convert`. For example, use `colorspacious.cspace_convert(data, 'CIELab', 'CIELCh')` instead.

• ValueError: Unknown colorspace specifier 'sRGB_linear'

  cause Using an old colorspace string identifier that was renamed in `colorspacious` v1.0.0.
  fix Consult the `colorspacious` documentation for the correct colorspace string. For `sRGB_linear`, use `sRGB1`. For `sRGB_255`, use `sRGB255`.

Warnings

• breaking The argument signature for `colorspacious.cspace_convert` changed significantly in version 1.0.0. Previously, it might have been `cspace_convert(data, start_cspace, target_cspace)`. In v1.0.0 and later, it uses explicit keyword arguments `in_cspace` and `out_cspace`.
  Fix: Update calls to `cspace_convert` from `cs.cspace_convert(data, 'old_in', 'old_out')` to `cs.cspace_convert(data, in_cspace='new_in', out_cspace='new_out')` or `cs.cspace_convert(data, 'new_in', 'new_out')`.
• breaking Direct utility functions for specific conversions (e.g., `CIELCh_from_CIELab`, `XYZ_from_sRGB1`) were removed in version 1.0.0. All conversions are now consolidated under the general `colorspacious.cspace_convert` function.
  Fix: Replace calls like `colorspacious.CIELCh_from_CIELab(data)` with `colorspacious.cspace_convert(data, 'CIELab', 'CIELCh')`.
• breaking Many colorspace specifier strings changed naming conventions in version 1.0.0 (e.g., `sRGB_linear` became `sRGB1`, `sRGB_255` became `sRGB255`). Using old names will result in `ValueError`.
  Fix: Refer to the `colorspacious` documentation for the updated list of colorspace names. For common cases, update `sRGB_linear` to `sRGB1` and `sRGB_255` to `sRGB255`.
• gotcha While `colorspacious` can process lists or tuples as input, it is heavily optimized for NumPy arrays. Using non-NumPy inputs, especially for large datasets, can lead to significant performance degradation.
  Fix: Ensure that your color data is converted to a NumPy array before passing it to `colorspacious` functions, e.g., `np.array(my_list_of_colors)`.

Install

• pip install colorspacious Install stable release

Imports

• cspace_convert

  import colorspacious as cs
  cs.cspace_convert(...)

• CIELCh_from_CIELab
  wrong:

  from colorspacious import CIELCh_from_CIELab

  correct:

  import colorspacious as cs
  cs.cspace_convert(data, 'CIELab', 'CIELCh')

  Direct conversion functions like CIELCh_from_CIELab were removed in v1.0.0. Use cspace_convert instead.

Quickstart

This example demonstrates basic color space conversion using the `cspace_convert` function. It takes a NumPy array representing color data and converts it between specified input and output color spaces.

import colorspacious as cs
import numpy as np

# A color in sRGB255 (standard 0-255 sRGB) space
sRGB_color = np.array([255, 128, 0]) # Orange

# Convert to CIELab (D65 illuminant) space
LAB_color = cs.cspace_convert(sRGB_color, "sRGB255", "CIELab")
print(f"sRGB color (255, 128, 0) in CIELab: {LAB_color}")

# Convert to CIELCh space
LCH_color = cs.cspace_convert(LAB_color, "CIELab", "CIELCh")
print(f"sRGB color (255, 128, 0) in CIELCh: {LCH_color}")