Registry / data / opencolorio

opencolorio

JSON →
library2.5.2pypypi✓ verified 84d ago

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.

pip install opencolorio
INSTALL
IMPORT
SIG · OPENCOLORIO
O
opencolorio
datapythonv2.5.2
Install
2.2s avg
Import
31ms
Disk
37MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.5.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.2s · import 0.031s · 39MB
37MB installed
● package 37MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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}")
ocioconvert --version
Debug
Known issues
breakingOpenColorIO 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.
affects: 1.x to 2.x
breakingOCIO 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.
affects: 2.5.0 to 2.5.1
gotchaThe `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).
affects: All versions
gotchaThe `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`.
affects: All versions
deprecatedThe `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.
affects: 2.x and higher
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'PyOpenColorIO'
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
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
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'
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.
Upgrade
Version history
2.5.2latest on PyPI · released May 13, 2026
Audit
Dependencies
numpyoptionalRecommended for efficient batch processing of color values in Python.
Agent activity
2 hits · last 30 days
node
2
Resources
opencolorio — pip install opencolorio · libregistry