Rewrite python bindings with pybind11 and numpy

This introduces an entirely new python API for reading and writing
OpenEXR files that supports all file features (or will soon):
scanline, tiled, deep, multi-part, etc. It uses numpy arrays for pixel
data, and it supports both separate arrays for each channel and
interleaving of RGB data into a single composite channel.  It leaves
the existing binding API in place for backwards-compatibility; there's
no overlap between the two APIs.

See src/wrappers/python/README.md for examples of the new API.

The API is simple: the ``File`` object holds a py::list of ``Part``
objects, each of which has a py::dict for the header and a py::dict
for the channels, and each channels hold a numpy array for the pixel
data. There's intentionally no support for selective scanline/time
reading; reading a file reads the entire channel data for all parts.
There *is*, however, an option to read just the headers and skip the
pixel data entirely.

A few things don't work yet:

- Reading and writing of deep data isn't finished.
- ID manfest attributes aren't supported yet.
- For mipmaped images, it current only reads the top level.

This also does not (yet) properly integrate the real Imath types. It
leaves in place for now the internal "Imath.py" module, but defines
its own internal set of set of Imath classes. This needs to be resolve
once the Imath bindings are distributed via pypi.org

The test suite downloads images from openexr-images and runs them
through a battery of reading/writing tests. Currently, the download is
enabled via the ``OPENEXR_TEST_IMAGE_REPO`` environment variable that
is off by default but is on in the python wheel CI workflow.

Signed-off-by: Cary Phillips <[email protected]>

.github/workflows/python-wheels.yml

@@ -17,13 +17,15 @@ on:
     branches-ignore:
       - RB-*
     paths:
+      - 'src/lib/**'
       - 'src/wrappers/python/**'
       - 'pyproject.toml'
       - '.github/workflows/python-wheels.yml'
   pull_request:
     branches-ignore:
       - RB-*
     paths:
+      - 'src/lib/**'
       - 'src/wrappers/python/**'
       - 'pyproject.toml'
       - '.github/workflows/python-wheels.yml'
@@ -42,10 +44,10 @@ jobs:
     steps:
 
       - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        uses: actions/checkout@v4
 
       - name: Install Python 
-        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0
+        uses: actions/setup-python@v5
         with:
           python-version: '3.x'
 
@@ -55,17 +57,18 @@ jobs:
         run: pipx run build --sdist . --outdir wheelhouse
 
       - name: Build wheel
-        uses: pypa/cibuildwheel@8d945475ac4b1aac4ae08b2fd27db9917158b6ce # v2.17.0
+        uses: pypa/cibuildwheel@v2.16
         env:
           CIBW_ARCHS_MACOS: x86_64 arm64 universal2
           # Skip python 3.6 since scikit-build-core requires 3.7+
           # Skip 32-bit wheels builds on Windows
           # Also skip the PyPy builds, since they fail the unit tests
           CIBW_SKIP: cp36-* *-win32 *_i686 pp* 
           CIBW_TEST_SKIP: "*-macosx*arm64"
+          OPENEXR_TEST_IMAGE_REPO: "https://raw.githubusercontent.com/AcademySoftwareFoundation/openexr-images/main"
 
       - name: Upload artifact
-        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4.3.3
+        uses: actions/upload-artifact@v4
         with:
           name: wheels-${{ matrix.os }}
           path: |

pyproject.toml

@@ -2,7 +2,7 @@
 # Copyright (c) Contributors to the OpenEXR Project.
 
 [build-system]
-requires = ["scikit-build-core==0.8.1"]
+requires = ["scikit-build-core==0.8.1", "pybind11", "numpy"]
 build-backend = "scikit_build_core.build"
 
 [project]
@@ -67,6 +67,7 @@ CMAKE_POSITION_INDEPENDENT_CODE = 'ON'
 
 [tool.cibuildwheel]
 test-command = "pytest -s {project}/src/wrappers/python/tests"
+test-requires = ["numpy"]
 test-extras = ["test"]
 test-skip = ["*universal2:arm64"]
 build-verbosity = 1

share/ci/scripts/install_pybind11.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright Contributors to the OpenColorIO Project.
+
+set -ex
+
+PYBIND11_VERSION="$1"
+
+if [[ $OSTYPE == "msys" ]]; then
+    SUDO=""
+else
+    SUDO="sudo"
+fi
+
+git clone https://github.com/pybind/pybind11.git
+cd pybind11
+
+if [ "$PYBIND11_VERSION" == "latest" ]; then
+    LATEST_TAG=$(git describe --abbrev=0 --tags)
+    git checkout tags/${LATEST_TAG} -b ${LATEST_TAG}
+else
+    git checkout tags/v${PYBIND11_VERSION} -b v${PYBIND11_VERSION}
+fi
+
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release \
+      -DPYBIND11_INSTALL=ON \
+      -DPYBIND11_TEST=OFF \
+      ../.
+$SUDO cmake --build . \
+      --target install \
+      --config Release \
+      --parallel 2
+
+cd ../..
+rm -rf pybind11

src/lib/OpenEXR/ImfKeyCode.cpp

@@ -61,6 +61,18 @@ KeyCode::operator= (const KeyCode& other)
     return *this;
 }
 
+bool
+KeyCode::operator== (const KeyCode& other) const
+{
+    return (_filmMfcCode   == other._filmMfcCode &&
+            _filmType      == other._filmType &&
+            _prefix        == other._prefix &&
+            _count         == other._count &&
+            _perfOffset    == other._perfOffset &&
+            _perfsPerFrame == other._perfsPerFrame &&
+            _perfsPerCount == other._perfsPerCount);
+}
+
 int
 KeyCode::filmMfcCode () const
 {

src/lib/OpenEXR/ImfKeyCode.h

@@ -93,6 +93,8 @@ class IMF_EXPORT_TYPE KeyCode
     IMF_EXPORT
     KeyCode& operator= (const KeyCode& other);
 
+    bool operator== (const KeyCode& other) const;
+
     //----------------------------
     // Access to individual fields
     //----------------------------

src/lib/OpenEXR/ImfPreviewImage.h

@@ -36,6 +36,11 @@ struct IMF_EXPORT_TYPE PreviewRgba
         unsigned char a = 255)
         : r (r), g (g), b (b), a (a)
     {}
+
+        bool operator==(const PreviewRgba& other) const
+        {
+            return r == other.r && g == other.g && b == other.b && a == other.a;
+        }
 };
 
 class IMF_EXPORT_TYPE PreviewImage

src/wrappers/python/CMakeLists.txt

@@ -10,10 +10,11 @@ if(NOT "${CMAKE_PROJECT_NAME}" STREQUAL "OpenEXR")
 endif()
 
 find_package(Python COMPONENTS Interpreter Development.Module REQUIRED)
+find_package(pybind11 CONFIG REQUIRED)
 
-python_add_library (PyOpenEXR MODULE OpenEXR.cpp)
+python_add_library (PyOpenEXR MODULE PyOpenEXR.cpp PyOpenEXR_old.cpp)
 
-target_link_libraries (PyOpenEXR PRIVATE "${Python_LIBRARIES}" OpenEXR::OpenEXR)
+target_link_libraries (PyOpenEXR PRIVATE "${Python_LIBRARIES}" OpenEXR::OpenEXR pybind11::headers)
 
 # The python module should be called "OpenEXR.so", not "PyOpenEXR.so",
 # but "OpenEXR" is taken as a library name by the main lib, so specify