{"id":7469,"library":"openimageio","title":"OpenImageIO","description":"OpenImageIO (OIIO) is a high-performance, open-source library and toolset for reading, writing, and processing images in a wide variety of file formats, using a format-agnostic API. Primarily aimed at visual effects (VFX) and animation applications, it provides robust support for formats like OpenEXR, TIFF, JPEG, PNG, and many more. The library is actively maintained by the Academy Software Foundation, with frequent minor releases within its major versions.","status":"active","version":"3.1.12.0","language":"en","source_language":"en","source_url":"https://github.com/AcademySoftwareFoundation/OpenImageIO","tags":["image processing","vfx","animation","image i/o","image manipulation","openexr","tiff","jpeg","png"],"install":[{"cmd":"pip install openimageio","lang":"bash","label":"Stable release"},{"cmd":"pip install --force-reinstall \"openimageio[all]\" # For comprehensive format support and to rebuild if issues arise","lang":"bash","label":"Full installation (recommended for broad format support)"}],"dependencies":[{"reason":"Required for handling pixel data as NumPy arrays in Python bindings.","package":"numpy","optional":false},{"reason":"Core C++ dependency, often linked during compilation. Included in wheels.","package":"zlib","optional":true},{"reason":"Core C++ dependency for TIFF format support. Included in wheels.","package":"libTIFF","optional":true},{"reason":"Core C++ dependency for OpenEXR format support. Included in wheels.","package":"OpenEXR","optional":true},{"reason":"Core C++ dependency for color management features. Included in wheels.","package":"OpenColorIO","optional":true},{"reason":"Core C++ dependency for JPEG format support. Included in wheels.","package":"libjpeg / libjpeg-turbo","optional":true}],"imports":[{"symbol":"OpenImageIO","correct":"import OpenImageIO as oiio"},{"note":"ImageInput is a class within the OpenImageIO module, not a top-level module itself.","wrong":"import ImageInput","symbol":"ImageInput","correct":"from OpenImageIO import ImageInput"},{"note":"ImageBuf is a class within the OpenImageIO module, not a top-level module itself.","wrong":"import ImageBuf","symbol":"ImageBuf","correct":"from OpenImageIO import ImageBuf"}],"quickstart":{"code":"import OpenImageIO as oiio\nimport numpy as np\nimport os\n\n# Create a dummy image (e.g., a red square)\nwidth, height, channels = 256, 256, 3\nspec = oiio.ImageSpec(width, height, channels, oiio.TypeDesc('float'))\n# Create a NumPy array with red pixels\npixels = np.zeros((height, width, channels), dtype=np.float32)\npixels[:, :, 0] = 1.0 # Red channel to full intensity\n\n# Create an ImageBuf from the spec and pixels\nimg_buf = oiio.ImageBuf(spec, pixels)\n\n# Define output file path\noutput_filename = 'red_square.exr'\n\n# Write the image\ntry:\n    img_buf.write(output_filename)\n    print(f\"Successfully wrote {output_filename}\")\n\n    # Read the image back\n    read_img_buf = oiio.ImageBuf(output_filename)\n    if read_img_buf.has_error:\n        raise RuntimeError(f\"Error reading {output_filename}: {read_img_buf.geterror()}\")\n    \n    # Get pixel data as a NumPy array\n    read_pixels = read_img_buf.get_pixels(oiio.TypeDesc('float'))\n    print(f\"Read image with shape: {read_pixels.shape}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    if os.path.exists(output_filename):\n        os.remove(output_filename) # Clean up the dummy file","lang":"python","description":"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."},"warnings":[{"fix":"Migrate pixel buffer handling to use NumPy arrays. Functions like `read_image()` and `get_pixels()` now return NumPy arrays, and `write()` expects them.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All (especially custom builds)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The Python interpreter cannot find the installed OpenImageIO module. This often happens after building from source or due to incorrect `PYTHONPATH` settings.","error":"ModuleNotFoundError: No module named 'OpenImageIO'"},{"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.","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.","error":"Python interpreter crashes when reading certain image files."},{"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)`.","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+.","error":"TypeError: argument 'pixels': 'list' object cannot be converted to 'PyArrayObject'"}]}