{"id":9377,"library":"types-opencolorio","title":"Python Stubs for PyOpenColorIO","description":"types-opencolorio provides static type checking stubs for PyOpenColorIO, the Python bindings for OpenColorIO (OCIO). OCIO is a complete color management solution for motion picture production, emphasizing visual effects and computer animation. This stub package enhances IDE support and enables tools like MyPy for type validation of PyOpenColorIO code. It closely follows the versioning of the main OpenColorIO library, which typically has annual releases around September.","status":"active","version":"2.4.2.0","language":"en","source_language":"en","source_url":"https://github.com/AcademySoftwareFoundation/OpenColorIO","tags":["type-stubs","color-management","vfx","animation","post-production","ocio","opencolorio","mypy"],"install":[{"cmd":"pip install types-opencolorio","lang":"bash","label":"Install stubs"},{"cmd":"pip install opencolorio","lang":"bash","label":"Install runtime (required)"}],"dependencies":[{"reason":"Provides the actual runtime functionality; types-opencolorio only contains type hints.","package":"opencolorio","optional":false}],"imports":[{"note":"PyOpenColorIO is typically imported with the alias OCIO for brevity and convention.","symbol":"OCIO","correct":"import PyOpenColorIO as OCIO"},{"note":"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.","wrong":"import PyOpenColorIO as OCIO\nconfig = OCIO.Config()","symbol":"Config","correct":"import PyOpenColorIO as OCIO\nconfig = OCIO.GetCurrentConfig()"},{"note":"Used for defining or referencing color spaces within a configuration.","symbol":"ColorSpace","correct":"import PyOpenColorIO as OCIO\ncs = OCIO.ColorSpace()"}],"quickstart":{"code":"import PyOpenColorIO as OCIO\nimport os\n\n# For a runnable example, we'll try to get the current config.\n# In a real setup, you'd likely set the OCIO environment variable\n# to point to an OCIO config file, e.g., os.environ['OCIO'] = '/path/to/my_config.ocio'\n# For this example, we'll assume a default or simple config if OCIO is not set.\n\ntry:\n    config = OCIO.GetCurrentConfig()\n    print(\"Successfully loaded OCIO config.\")\nexcept OCIO.Exception as e:\n    print(f\"Could not load OCIO config: {e}. Attempting to create a minimal default config.\")\n    # Create a minimal config for demonstration if none is found\n    config = OCIO.Config.Create()\n    config.setFileFormatVersion(OCIO.Constants.OCIO_FILE_FORMAT_VERSION_2_0)\n    linear_cs = OCIO.ColorSpace.Create()\n    linear_cs.setName(\"linear\")\n    linear_cs.setFamily(\"linear\")\n    linear_cs.setIsData(False)\n    config.addColorSpace(linear_cs)\n    \n    srgb_cs = OCIO.ColorSpace.Create()\n    srgb_cs.setName(\"sRGB\")\n    srgb_cs.setFamily(\"display\")\n    srgb_cs.setIsData(False)\n    srgb_to_linear = OCIO.BuiltinTransform.Create(OCIO.BuiltinTransformRegistry.ACES_CG_TO_ACES2065_1)\n    srgb_to_linear.setDirection(OCIO.TransformDirection.INVERSE_TRANSFORM)\n    srgb_cs.setTransform(srgb_to_linear, OCIO.TransformDirection.FROM_REFERENCE)\n    config.addColorSpace(srgb_cs)\n    \n    config.setDefaultWorkingSpaceName(\"linear\")\n    config.setRole(OCIO.ROLE_SCENE_LINEAR, \"linear\")\n    config.setRole(OCIO.ROLE_COLOR_PICKING, \"sRGB\")\n    config.setRole(OCIO.ROLE_DISPLAY, \"sRGB\")\n\n\n# Define source and destination color spaces\nsource_colorspace = \"sRGB\"\ndestination_colorspace = \"linear\"\n\n# Ensure the color spaces exist in the config\nif config.getColorSpace(source_colorspace) is None:\n    print(f\"Error: Source colorspace '{source_colorspace}' not found in config.\")\n    exit(1)\nif config.getColorSpace(destination_colorspace) is None:\n    print(f\"Error: Destination colorspace '{destination_colorspace}' not found in config.\")\n    exit(1)\n\n# Get a Processor to perform the color transformation\nprocessor = config.getProcessor(OCIO.ColorSpaceTransform(src=source_colorspace, dst=destination_colorspace))\n\n# Create an image buffer (e.g., a single pixel, RGB float values 0-1)\n# Example sRGB value (mid-gray)\ninput_pixel = [0.218, 0.218, 0.218, 1.0] # R, G, B, A\n\n# Create a working buffer (CPU processor operates on this)\n# OCIO expects a contiguous flat array of pixel data.\n# For a single pixel, it's [R, G, B, A]\noutput_pixel_data = list(input_pixel)\n\n# Apply the transformation\n# CPUProcessor handles float arrays directly\ncpu_processor = processor.getCPUProcessor()\ncpu_processor.applyRGB(output_pixel_data)\n\nprint(f\"Input (sRGB): {input_pixel}\")\nprint(f\"Output (linear): {output_pixel_data[:3]} (alpha: {output_pixel_data[3]})\")","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"OpenColorIO 2.x.x (and corresponding types-opencolorio 2.x.x.x)"},{"fix":"Ensure both `pip install types-opencolorio` and `pip install opencolorio` are executed in your environment.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the `OCIO` environment variable to the path of your `.ocio` configuration file. For example, `export OCIO=/path/to/my_config.ocio`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"PyOpenColorIO.Exception: Error building YAML: Colorspace associated to the role 'color_picking', does not exist."},{"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.","cause":"On Windows, starting with Python 3.8, changes to DLL loading behavior can prevent `PyOpenColorIO` from finding its required native libraries.","error":"ImportError: DLL load failed while importing PyOpenColorIO: The specified module could not be found."},{"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.","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.","error":"AttributeError: module 'PyOpenColorIO' has no attribute 'ColorSpace'"}]}