OpenImageIO

Common errors

• ModuleNotFoundError: No module named 'OpenImageIO'

  cause The Python interpreter cannot find the installed OpenImageIO module. This often happens after building from source or due to incorrect `PYTHONPATH` settings.
  fix Ensure `pip install openimageio` completed successfully. If building from source, set the `PYTHONPATH` environment variable to include the directory where `OpenImageIO.so` (Linux/macOS) or `OpenImageIO.pyd` (Windows) is located. For macOS, sometimes renaming `OpenImageIO.dylib` to `OpenImageIO.so` is required.

• Python interpreter crashes when reading certain image files.

  cause OpenImageIO is a C++ library, and reading malformed or corrupted image files, or files with exotic parameters that expose bugs in the underlying C++ plugins, can lead to a hard crash of the Python interpreter instead of raising a Python exception.
  fix Wrap image reading operations in `try-except` blocks, specifically checking `ImageBuf.has_error` and `ImageBuf.geterror()` after initialization or I/O operations. While this doesn't prevent all C++-level crashes, it helps catch many issues gracefully. Ensure you are using the latest stable version of OpenImageIO and its dependencies, as many such bugs are fixed over time.

• TypeError: argument 'pixels': 'list' object cannot be converted to 'PyArrayObject'

  cause Attempting to pass raw Python lists or `array.array` objects as pixel data to OIIO functions (e.g., `ImageBuf.set_pixels()`, `ImageOutput.write_image()`) in OpenImageIO 2.0+.
  fix Convert pixel data to `numpy.ndarray` objects before passing them to OpenImageIO functions. For example, `pixels_ndarray = np.array(my_list_of_pixels, dtype=np.float32)`.

Warnings

• breaking OpenImageIO 2.0 introduced significant breaking changes in Python bindings, most notably the switch from Python's `array.array` to `numpy.ndarray` for pixel data. Code written for OIIO 1.x that handles pixel buffers will need updates.
  Fix: Migrate pixel buffer handling to use NumPy arrays. Functions like `read_image()` and `get_pixels()` now return NumPy arrays, and `write()` expects them.
• gotcha Installing OpenImageIO via `pip` on certain platforms or for full functionality (especially with specific C++ compiler versions or less common image formats) can sometimes be challenging due to its underlying C++ dependencies. Pre-built wheels aim to simplify this but edge cases exist.
  Fix: Ensure your environment meets the `requires_python` version. If `pip install` fails or format support is missing, consider building from source using `vcpkg` or by following the detailed build instructions in the OIIO documentation, which might require installing system-level C++ development packages (e.g., `libtiff-dev`, `libopenexr-dev`).
• gotcha When `pip` installing OpenImageIO from source, or if using a custom build, a `ModuleNotFoundError` can occur if the Python interpreter cannot locate the `OpenImageIO` module. This is particularly common on macOS where shared libraries (`.dylib`) might not be found by Python which often expects `.so` extensions.
  Fix: Verify that the `PYTHONPATH` environment variable correctly points to the directory containing the `OpenImageIO.so` (or `OpenImageIO.pyd` on Windows) file. For macOS, ensure the `.dylib` file is either renamed to `.so` or linked appropriately, or that the build system is configured to produce `.so`.
• gotcha Incorrectly converting a color image (like sRGB JPEG) to grayscale by simply averaging the R, G, B channels will yield visually inaccurate results because human perception of brightness is not uniform across color channels, and sRGB is a non-linear color space.
  Fix: Use `oiio.ImageBufAlgo.colorconvert()` to linearize the image (e.g., 'sRGB' to 'linear') and then `oiio.ImageBufAlgo.channel_sum()` with appropriate luminance weights (e.g., `(0.2126, 0.7152, 0.0722)` for Rec. 709/sRGB luminance) to derive the grayscale. Convert back to sRGB if outputting to an 8-bit image format.

Install

• pip install openimageio Stable release
• pip install --force-reinstall "openimageio[all]" # For comprehensive format support and to rebuild if issues arise Full installation (recommended for broad format support)

Imports

• OpenImageIO

  import OpenImageIO as oiio

• ImageInput
  wrong:

  import ImageInput

  correct:

  from OpenImageIO import ImageInput

  ImageInput is a class within the OpenImageIO module, not a top-level module itself.
• ImageBuf
  wrong:

  import ImageBuf

  correct:

  from OpenImageIO import ImageBuf

  ImageBuf is a class within the OpenImageIO module, not a top-level module itself.

Quickstart

This quickstart demonstrates how to create an in-memory image (a red square) using OpenImageIO and NumPy, write it to an OpenEXR file, and then read it back. It utilizes `ImageSpec` to define image properties and `ImageBuf` for convenient image manipulation and I/O. The `get_pixels` method retrieves pixel data as a NumPy array.

import OpenImageIO as oiio
import numpy as np
import os

# Create a dummy image (e.g., a red square)
width, height, channels = 256, 256, 3
spec = oiio.ImageSpec(width, height, channels, oiio.TypeDesc('float'))
# Create a NumPy array with red pixels
pixels = np.zeros((height, width, channels), dtype=np.float32)
pixels[:, :, 0] = 1.0 # Red channel to full intensity

# Create an ImageBuf from the spec and pixels
img_buf = oiio.ImageBuf(spec, pixels)

# Define output file path
output_filename = 'red_square.exr'

# Write the image
try:
    img_buf.write(output_filename)
    print(f"Successfully wrote {output_filename}")

    # Read the image back
    read_img_buf = oiio.ImageBuf(output_filename)
    if read_img_buf.has_error:
        raise RuntimeError(f"Error reading {output_filename}: {read_img_buf.geterror()}")
    
    # Get pixel data as a NumPy array
    read_pixels = read_img_buf.get_pixels(oiio.TypeDesc('float'))
    print(f"Read image with shape: {read_pixels.shape}")

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    if os.path.exists(output_filename):
        os.remove(output_filename) # Clean up the dummy file