openexr icon indicating copy to clipboard operation
openexr copied to clipboard

Rewrite OpenEXR python bindings using pybind11 and numpy

Open cary-ilm opened this issue 1 year ago • 5 comments

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 channel holds a numpy array for the pixel data. There's intentionally no support for selective scanline/time reading; to keep the API simple, 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 but should be fixed before release:

  • Reading and writing of deep data samples isn't finished.
  • ID manifest attributes aren't supported yet.
  • For mip-mapped images, it current only reads the top level.
  • Channel subsampling is not working.
  • I'm not 100% sure the memory ownership is handled properly.

This also does not (yet) properly integrate the real Imath types from the proper Imath bindings. 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 resolved 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.

This also adds operator== methods to KeyCode and PreviewImage, required in order to implement operator== for the Part and File objects.

cary-ilm avatar May 16 '24 04:05 cary-ilm