OpenColorIO (OCIO)

Common errors

• ModuleNotFoundError: No module named 'PyOpenColorIO'

  cause The `opencolorio` package is either not installed in the current Python environment, or the environment is not correctly configured (e.g., within certain DCC applications like Maya that ship their own Python).
  fix Ensure `opencolorio` is installed: `pip install opencolorio`. If in a DCC, verify if it ships its own bindings or if the external `PyOpenColorIO` package is compatible with the DCC's Python interpreter version and ABI.

• ImportError: No module named PyOpenColorIO

  cause Similar to `ModuleNotFoundError`, this typically means the `PyOpenColorIO` module cannot be found. For source builds, this can also indicate missing shared library paths.
  fix First, try `pip install opencolorio`. If building from source, ensure `DYLD_LIBRARY_PATH` (macOS) or `LD_LIBRARY_PATH` (Linux) is correctly set to include the directory containing the `PyOpenColorIO.so` (or equivalent) file.

• PyOpenColorIO.Exception: (ERROR) : ... config.ocio: 'color_space_name' not found

  cause The specified color space (e.g., source or destination) does not exist in the currently loaded OCIO configuration file. This often happens if an incorrect config is loaded or if a typo exists in the color space name.
  fix Verify the `OCIO` environment variable points to the correct `config.ocio` file. Use `config.getColorSpaces()` to list available color spaces and ensure your names match exactly (case-sensitive).

• PyOpenColorIO.ExceptionMissingFile: (ERROR) : ... LUT file not found: 'path/to/lut.cub'

  cause The OCIO configuration references a Look-Up Table (LUT) file that cannot be found at the specified path. This could be due to an incorrect path, missing file, or issues with environment variables resolving file paths.
  fix Check the `config.ocio` file and any referenced `.clf`, `.cub`, or other LUT files. Ensure all paths are correct and accessible by the application running OCIO, considering relative paths and environment variables like `OCIO_LUT_PATH` if used.

Warnings

• breaking OpenColorIO v2 (released Jan 2021) introduced significant breaking changes from v1. Key architectural shifts include a new GPU renderer, native ACES implementation, and updated API calls for config handling and color space parsing. Code written for OCIO v1 will likely not work without modification.
  Fix: Consult the 'Upgrading to v2' section in the official OpenColorIO documentation for detailed migration paths and API changes. Pay close attention to `Config::parseColorSpaceFromString()` (deprecated), `Config::getColorSpaceFromFilepath()` (new), and changes to strict parsing behavior and viewing rules.
• breaking OCIO 2.5.1 is not ABI compatible with 2.5.0 for applications utilizing the GPU renderer API. While the `SOVERSION` remains '2.5', any application compiled with OCIO 2.5.0 that uses the GPU API must be recompiled when upgrading to 2.5.1.
  Fix: Recompile your application against the OCIO 2.5.1 library if you use the GPU renderer API. Subsequent 2.5.x releases are expected to be ABI-compatible with 2.5.1.
• gotcha The `pip install opencolorio` package provides only the Python bindings. It does *not* include the command-line tools like `ocioconvert` or `ociochecklut`. These tools typically require building OpenColorIO from source or installing via a system package manager.
  Fix: If command-line tools are needed, refer to the official OpenColorIO installation documentation for building from source or using system-specific package managers (e.g., `brew` on macOS, `vcpkg` on Windows).
• gotcha The `OCIO` environment variable is critical for OpenColorIO to find and load a configuration file (`config.ocio`). If this variable is not set, or points to an invalid/missing file, many OCIO functions will fail at runtime with exceptions.
  Fix: Ensure the `OCIO` environment variable is set to the full path of your desired `config.ocio` file before initializing or using the OCIO library. For example: `export OCIO=/path/to/your/config.ocio`.
• deprecated The `Config::parseColorSpaceFromString()` method is officially deprecated in OCIO v2. It does not work correctly with FileRules, a feature introduced in v2 for dynamically determining color spaces from file paths.
  Fix: Use `Config::getColorSpaceFromFilepath()` instead. This method is the proper way to extract a color space from a file path and works with both v1 and v2 configs, including those with FileRules.

Install

• pip install opencolorio Install Python Bindings

Imports

• PyOpenColorIO
  wrong:

  import opencolorio

  correct:

  import PyOpenColorIO as OCIO

  The PyPI package is 'opencolorio', but the Python module for import is 'PyOpenColorIO' due to historical naming conventions.

Quickstart

This quickstart demonstrates how to perform a basic color space transformation on an RGB value. It requires an OpenColorIO configuration file (e.g., an ACES config) to be accessible, typically via the `OCIO` environment variable. The example shows how to load the current configuration, create a processor between two color spaces, and apply the transformation using the CPU processor.

import os
import PyOpenColorIO as OCIO

def apply_color_transform(rgb_value, source_space, destination_space, ocio_config_path):
    # Ensure the OCIO environment variable is set for config loading
    if 'OCIO' not in os.environ or os.environ['OCIO'] != ocio_config_path:
        os.environ['OCIO'] = ocio_config_path
    
    try:
        config = OCIO.GetCurrentConfig()
        processor = config.getProcessor(source_space, destination_space)
        cpu_processor = processor.getDefaultCPUProcessor()
        
        # Apply the transform to an RGB tuple/list
        transformed_rgb = cpu_processor.applyRGB(rgb_value)
        return transformed_rgb
    except OCIO.Exception as e:
        print(f"OpenColorIO Error: {e}")
        return None

# Example Usage (requires an OCIO config file to be set up)
# You can download reference configs from https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES
# For example, use 'aces_1.2/config.ocio'

# NOTE: Replace with the actual path to your OCIO config file
ocio_config_file = os.environ.get('OCIO_TEST_CONFIG', './config.ocio') # Placeholder for CI/testing

if not os.path.exists(ocio_config_file):
    print(f"Warning: OCIO config file not found at '{ocio_config_file}'. Skipping quickstart example. "
          "Please set the OCIO_TEST_CONFIG environment variable or provide a valid path.")
else:
    print(f"Using OCIO config: {ocio_config_file}")
    input_rgb = [0.5, 0.1, 0.9] # Example color in source_space
    src_cs = 'sRGB'
    dst_cs = 'ACES - ACEScg'
    
    # Note: The exact color space names depend on the loaded OCIO config.
    # Common ones are 'sRGB', 'ACES - ACEScg', 'Utility - Linear - sRGB', etc.
    
    transformed_color = apply_color_transform(
        input_rgb, src_cs, dst_cs, ocio_config_file
    )

    if transformed_color:
        print(f"Original RGB ({src_cs}): {input_rgb}")
        print(f"Transformed RGB ({dst_cs}): {transformed_color}")