Building OpenImageIO

How to Install OpenImageIO on Windows and Linux#

OpenImageIO (OIIO) is an open-source library for reading, writing, and manipulating image files. It is widely used in the visual effects and animation industries. Here's a step-by-step guide to installing OIIO on both Windows and Linux systems using vcpkg, a popular C++ library manager.

Prerequisites#

Python 3.11.8
Git
VCPKG
VSCode or Cursor

Step 1: Install vcpkg#

vcpkg is a free, open-source package manager for C and C++ libraries. It was developed by Microsoft to simplify the process of managing and building third-party libraries in C++ projects. vcpkg helps developers easily find, install, and manage libraries across multiple platforms, including Windows, Linux, and macOS.

Prerequisites for Linux#

If you're on Linux, make sure to install the following dependencies:

sudo apt-get install git cmake build-essential curl tar gzip unzip zip pkg-config autoconf automake libtool autoconf-archive

Prerequisites for Windows:#

Install Visual Studio https://visualstudio.microsoft.com/vs/community/ and the C++ components

Git Clone VCPKG#

Run git clone on the vcpkg repository from Microsoft:

"git clone https://github.com/microsoft/vcpkg.git"

Step 2: Setup VCPKG#

Navigate to the directory where you cloned vcpkg and run the following commands:

For Windows:#

.\bootstrap-vcpkg.bat

.\vcpkg.exe integrate install

For Linux:#

./bootstrap-vcpkg.sh

./vcpkg integrate install

Step 3: Install OpenImageIO with Python Bindings#

To install OpenImageIO, run the following command from within the vcpkg directory:

vcpkg install openimageio[tools,opencolorio,pybind11]

When building with vcpkg, the python bindings are an optional but in most cases necessary extension.
Other options can be seen by looking at the openmageio port file for vcpkg:

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
    FEATURES
        libraw      USE_LIBRAW
        opencolorio USE_OPENCOLORIO
        ffmpeg      USE_FFMPEG
        freetype    USE_FREETYPE
        gif         USE_GIF
        opencv      USE_OPENCV
        openjpeg    USE_OPENJPEG
        webp        USE_WEBP
        libheif     USE_LIBHEIF
        pybind11    USE_PYTHON
        tools       OIIO_BUILD_TOOLS
        viewer      ENABLE_IV
)

Step 4: Configure OpenImageIO for Python#

Windows#

After installation, copy the file vcpkg\installed\x64-windows\lib\python3.10\site-packages\OpenImageIO.cp310-win_amd64.pyd to the desired oiio folder.
Copy the necessary DLLs from vcpkg\installed\x64-windows\bin to the same oiio folder.
Rename the .pyd file to OpenImageIO.pyd.

Linux#

Create an environment with the required Python version (3.11.8) and set up dependencies using the following script:

To complete the installation, create a symbolic link:

1ln -s /vcpkg/installed/x64-linux/lib/python3.11/site-packages/OpenImageIO/OpenImageIO.cpython-311-x86_64-linux-gnu.so
2/usr/local/lib/python3.11/site-packages/OpenImageIO.so

Step 5: Generate Python Bindings#

Generate Python stubs for code completion and add them to the VSCode python search path.
python3 -m pip install mypy

stubgen -m OpenImageIO -o ./

.vscode/settings.json
{
    "python.pythonPath": "${workspaceFolder}/.venv/bin/python",
    "python.analysis.extraPaths": [
        "${workspaceFolder}/oiio"
    ]
}

Conclusion#

By following these steps, you can successfully install OpenImageIO on both Windows and Linux, allowing you to leverage its powerful image processing capabilities in your projects.

Here is an example of OIIO in action that converts exr to png

import os,sys
sys.path.insert(1, os.path.join(os.getcwd()  , '..', 'oiio'))

import OpenImageIO as oiio
from OpenImageIO import ImageInput, ImageOutput
from OpenImageIO import ImageBuf, ImageSpec, ImageBufAlgo

folder = "/show/seq/elements/plate"

# Function to convert EXR to PNG
def convert_exr_to_png(input_path, output_path):
    
    source_image = ImageBuf(input_path)
    # Apply color transformation
    destination_image = ImageBufAlgo.colorconvert(source_image, "acescg","sRGB", True)
    destination_image.set_write_format(oiio.UINT8)
    destination_image.write(output_path)
    
    
    print(f"Converted {input_path} to {output_path}")

# Iterate through all files in the folder
for filename in os.listdir(folder):
    if filename.lower().endswith('.exr'):
        input_path = os.path.join(folder, filename)
        output_path = os.path.join(folder, os.path.splitext(filename)[0] + '.png')
        convert_exr_to_png(input_path, output_path)

print("Conversion complete.")

Dockerfile#

# Use the official Debian slim image with Python 3.11.8
FROM python:3.11.8-slim

# Install required packages
RUN apt-get update && \
    apt-get install -y \
        git \
        cmake \
        build-essential \
        curl \
        tar \
        gzip \
        unzip \
        zip \
        pkg-config \
        autoconf \
        automake \
        libtool \
        pkg-config \
        autoconf-archive && \
    rm -rf /var/lib/apt/lists/*

# Clone vcpkg repository
RUN git clone https://github.com/microsoft/vcpkg.git /vcpkg

# Set working directory
WORKDIR /vcpkg

# Bootstrap vcpkg
RUN ./bootstrap-vcpkg.sh

# Install OpenImageIO and dependencies via vcpkg
RUN ./vcpkg install openimageio[tools,opencolorio,pybind11]

# Create symlink to make OpenImageIO available in Python's site-packages
RUN ln -s /vcpkg/installed/x64-linux/lib/python3.11/site-packages/OpenImageIO/OpenImageIO.cpython-311-x86_64-linux-gnu.so /usr/local/lib/python3.11/site-packages/OpenImageIO.so

# Default command
CMD [ "python3" ]

Resources#

https://www.studyplan.dev/pro-cpp/vcpkg-windows

https://tomasroggero.com/notes/how-to-install-openimageio-in-mac-os-x-el-capitan

https://www.studyplan.dev/pro-cpp/vcpkg-windows

https://github.com/Correct-Syntax/py-oiio