{"id":8374,"library":"opencolorio","title":"OpenColorIO (OCIO)","description":"OpenColorIO (OCIO) is an Academy Software Foundation (ASWF) project providing a comprehensive color management solution for motion picture production, visual effects, and computer animation. It offers a consistent user experience, is compatible with the Academy Color Encoding Specification (ACES), and is LUT-format agnostic. The current version is 2.5.1, and the project targets annual releases around September, aligning with the VFX Reference Platform schedule.","status":"active","version":"2.5.1","language":"en","source_language":"en","source_url":"https://github.com/AcademySoftwareFoundation/OpenColorIO","tags":["color management","VFX","animation","ACES","film","post-production"],"install":[{"cmd":"pip install opencolorio","lang":"bash","label":"Install Python Bindings"}],"dependencies":[{"reason":"Recommended for efficient batch processing of color values in Python.","package":"numpy","optional":true}],"imports":[{"note":"The PyPI package is 'opencolorio', but the Python module for import is 'PyOpenColorIO' due to historical naming conventions.","wrong":"import opencolorio","symbol":"PyOpenColorIO","correct":"import PyOpenColorIO as OCIO"}],"quickstart":{"code":"import os\nimport PyOpenColorIO as OCIO\n\ndef apply_color_transform(rgb_value, source_space, destination_space, ocio_config_path):\n    # Ensure the OCIO environment variable is set for config loading\n    if 'OCIO' not in os.environ or os.environ['OCIO'] != ocio_config_path:\n        os.environ['OCIO'] = ocio_config_path\n    \n    try:\n        config = OCIO.GetCurrentConfig()\n        processor = config.getProcessor(source_space, destination_space)\n        cpu_processor = processor.getDefaultCPUProcessor()\n        \n        # Apply the transform to an RGB tuple/list\n        transformed_rgb = cpu_processor.applyRGB(rgb_value)\n        return transformed_rgb\n    except OCIO.Exception as e:\n        print(f\"OpenColorIO Error: {e}\")\n        return None\n\n# Example Usage (requires an OCIO config file to be set up)\n# You can download reference configs from https://github.com/AcademySoftwareFoundation/OpenColorIO-Config-ACES\n# For example, use 'aces_1.2/config.ocio'\n\n# NOTE: Replace with the actual path to your OCIO config file\nocio_config_file = os.environ.get('OCIO_TEST_CONFIG', './config.ocio') # Placeholder for CI/testing\n\nif not os.path.exists(ocio_config_file):\n    print(f\"Warning: OCIO config file not found at '{ocio_config_file}'. Skipping quickstart example. \"\n          \"Please set the OCIO_TEST_CONFIG environment variable or provide a valid path.\")\nelse:\n    print(f\"Using OCIO config: {ocio_config_file}\")\n    input_rgb = [0.5, 0.1, 0.9] # Example color in source_space\n    src_cs = 'sRGB'\n    dst_cs = 'ACES - ACEScg'\n    \n    # Note: The exact color space names depend on the loaded OCIO config.\n    # Common ones are 'sRGB', 'ACES - ACEScg', 'Utility - Linear - sRGB', etc.\n    \n    transformed_color = apply_color_transform(\n        input_rgb, src_cs, dst_cs, ocio_config_file\n    )\n\n    if transformed_color:\n        print(f\"Original RGB ({src_cs}): {input_rgb}\")\n        print(f\"Transformed RGB ({dst_cs}): {transformed_color}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"1.x to 2.x"},{"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.","message":"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.","severity":"breaking","affected_versions":"2.5.0 to 2.5.1"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"2.x and higher"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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).","error":"ModuleNotFoundError: No module named 'PyOpenColorIO'"},{"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.","cause":"Similar to `ModuleNotFoundError`, this typically means the `PyOpenColorIO` module cannot be found. For source builds, this can also indicate missing shared library paths.","error":"ImportError: No module named PyOpenColorIO"},{"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).","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.","error":"PyOpenColorIO.Exception: (ERROR) : ... config.ocio: 'color_space_name' not found"},{"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.","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.","error":"PyOpenColorIO.ExceptionMissingFile: (ERROR) : ... LUT file not found: 'path/to/lut.cub'"}]}