Python Stubs for PyOpenColorIO

Common errors

• PyOpenColorIO.Exception: Error building YAML: Colorspace associated to the role 'color_picking', does not exist.

  cause The OpenColorIO configuration file is trying to assign a color space role (e.g., 'color_picking') to a color space that is not defined within the configuration.
  fix Edit your `.ocio` configuration file to ensure that all referenced color spaces for roles actually exist, or update the role assignment to a valid color space.

• ImportError: DLL load failed while importing PyOpenColorIO: The specified module could not be found.

  cause On Windows, starting with Python 3.8, changes to DLL loading behavior can prevent `PyOpenColorIO` from finding its required native libraries.
  fix This issue is complex and often related to how `opencolorio` was built or installed. Possible solutions include ensuring all `opencolorio` dependencies are in the system PATH, or in some cases, reverting to Python versions prior to 3.8 if a pre-built wheel for your specific Python 3.8+ environment isn't correctly configured. For development builds, consult OpenColorIO's build documentation for Windows-specific considerations.

• AttributeError: module 'PyOpenColorIO' has no attribute 'ColorSpace'

  cause This usually indicates that the `opencolorio` runtime library is not installed or incorrectly installed, leading to the type stubs for `PyOpenColorIO` being found, but the actual C++-backed Python module is not loaded correctly, or the version mismatch.
  fix Verify that `pip install opencolorio` completed successfully and that the installed `opencolorio` version matches the expected API for the `types-opencolorio` version you are using. If running in a virtual environment, ensure it's activated.

Warnings

• breaking OpenColorIO v2 introduced significant API changes compared to v1, including a re-engineered GPU renderer, modified clamping behavior for transforms, and new requirements for interchange roles (`aces_interchange`, `cie_xyz_d65_interchange`) for inter-config conversions.
  Fix: Review the OpenColorIO v2 migration guides. Update configuration files to include new roles and verify clamping behavior. Adapt Python code to the new GPU rendering API if used.
• gotcha The `types-opencolorio` package provides only type stubs. The actual runtime library, `PyOpenColorIO` (installed via `pip install opencolorio`), must be installed separately for your Python code to execute successfully. Without it, you will encounter `ModuleNotFoundError` at runtime.
  Fix: Ensure both `pip install types-opencolorio` and `pip install opencolorio` are executed in your environment.
• gotcha The `OCIO` environment variable is crucial for OpenColorIO applications as it typically points to the active configuration file. If this variable is not set or points to an invalid/incomplete configuration, `OCIO.GetCurrentConfig()` will fail, or applications may behave unexpectedly.
  Fix: Set the `OCIO` environment variable to the path of your `.ocio` configuration file. For example, `export OCIO=/path/to/my_config.ocio`.

Install

• pip install types-opencolorio Install stubs
• pip install opencolorio Install runtime (required)

Imports

• OCIO

  import PyOpenColorIO as OCIO

  PyOpenColorIO is typically imported with the alias OCIO for brevity and convention.
• Config
  wrong:

  import PyOpenColorIO as OCIO
  config = OCIO.Config()

  correct:

  import PyOpenColorIO as OCIO
  config = OCIO.GetCurrentConfig()

  While `OCIO.Config()` can create an empty config, `OCIO.GetCurrentConfig()` is the most common pattern, automatically loading from the OCIO environment variable or a default.
• ColorSpace

  import PyOpenColorIO as OCIO
  cs = OCIO.ColorSpace()

  Used for defining or referencing color spaces within a configuration.

Quickstart

This quickstart demonstrates how to load an OpenColorIO configuration and perform a basic color space transformation using the Python bindings. It first attempts to load an existing configuration (e.g., via the `OCIO` environment variable) and falls back to creating a minimal in-memory configuration if none is found. It then converts a sample sRGB pixel value to a linear color space using a `Processor`.

import PyOpenColorIO as OCIO
import os

# For a runnable example, we'll try to get the current config.
# In a real setup, you'd likely set the OCIO environment variable
# to point to an OCIO config file, e.g., os.environ['OCIO'] = '/path/to/my_config.ocio'
# For this example, we'll assume a default or simple config if OCIO is not set.

try:
    config = OCIO.GetCurrentConfig()
    print("Successfully loaded OCIO config.")
except OCIO.Exception as e:
    print(f"Could not load OCIO config: {e}. Attempting to create a minimal default config.")
    # Create a minimal config for demonstration if none is found
    config = OCIO.Config.Create()
    config.setFileFormatVersion(OCIO.Constants.OCIO_FILE_FORMAT_VERSION_2_0)
    linear_cs = OCIO.ColorSpace.Create()
    linear_cs.setName("linear")
    linear_cs.setFamily("linear")
    linear_cs.setIsData(False)
    config.addColorSpace(linear_cs)
    
    srgb_cs = OCIO.ColorSpace.Create()
    srgb_cs.setName("sRGB")
    srgb_cs.setFamily("display")
    srgb_cs.setIsData(False)
    srgb_to_linear = OCIO.BuiltinTransform.Create(OCIO.BuiltinTransformRegistry.ACES_CG_TO_ACES2065_1)
    srgb_to_linear.setDirection(OCIO.TransformDirection.INVERSE_TRANSFORM)
    srgb_cs.setTransform(srgb_to_linear, OCIO.TransformDirection.FROM_REFERENCE)
    config.addColorSpace(srgb_cs)
    
    config.setDefaultWorkingSpaceName("linear")
    config.setRole(OCIO.ROLE_SCENE_LINEAR, "linear")
    config.setRole(OCIO.ROLE_COLOR_PICKING, "sRGB")
    config.setRole(OCIO.ROLE_DISPLAY, "sRGB")


# Define source and destination color spaces
source_colorspace = "sRGB"
destination_colorspace = "linear"

# Ensure the color spaces exist in the config
if config.getColorSpace(source_colorspace) is None:
    print(f"Error: Source colorspace '{source_colorspace}' not found in config.")
    exit(1)
if config.getColorSpace(destination_colorspace) is None:
    print(f"Error: Destination colorspace '{destination_colorspace}' not found in config.")
    exit(1)

# Get a Processor to perform the color transformation
processor = config.getProcessor(OCIO.ColorSpaceTransform(src=source_colorspace, dst=destination_colorspace))

# Create an image buffer (e.g., a single pixel, RGB float values 0-1)
# Example sRGB value (mid-gray)
input_pixel = [0.218, 0.218, 0.218, 1.0] # R, G, B, A

# Create a working buffer (CPU processor operates on this)
# OCIO expects a contiguous flat array of pixel data.
# For a single pixel, it's [R, G, B, A]
output_pixel_data = list(input_pixel)

# Apply the transformation
# CPUProcessor handles float arrays directly
cpu_processor = processor.getCPUProcessor()
cpu_processor.applyRGB(output_pixel_data)

print(f"Input (sRGB): {input_pixel}")
print(f"Output (linear): {output_pixel_data[:3]} (alpha: {output_pixel_data[3]})")