python: add experimental nanobind bindings (ImageSpec, ParamValue, ROI, TypeDesc)

Build as optional oiio_python_nanobind target; share tests with the pybind11
module. Documents migration status in src/python-nanobind/MIGRATION_STATUS.md.

Assisted-by: Cursor/Composer-2

Signed-off-by: Aleksandr Motsjonov <soswow@gmail.com>

Author: soswow

CMakeLists.txt

@@ -142,12 +142,6 @@ if (TEX_BATCH_SIZE)
     add_compile_definitions (OIIO_TEXTURE_SIMD_BATCH_WIDTH=${TEX_BATCH_SIZE})
 endif ()
 
-# If we're building this just for CI, define a symbol so the code can
-# tell (and reduce complexity of some tests)
-set_option (OIIO_CI "Set if this build is for our GHA CI" OFF)
-if (OIIO_CI)
-    add_compile_definitions (OIIO_CI=1)
-endif ()
 
 # Namespace settings
 #
@@ -314,7 +308,12 @@ else ()
     set (_py_dev_found Python3_Development.Module_FOUND)
 endif ()
 if (USE_PYTHON AND ${_py_dev_found} AND NOT BUILD_OIIOUTIL_ONLY)
-    add_subdirectory (src/python)
+    if (OIIO_BUILD_PYTHON_PYBIND11)
+        add_subdirectory (src/python)
+    endif ()
+    if (OIIO_BUILD_PYTHON_NANOBIND)
+        add_subdirectory (src/python-nanobind)
+    endif ()
 else ()
     message (STATUS "Not building Python bindings: USE_PYTHON=${USE_PYTHON}, Python3_Development.Module_FOUND=${Python3_Development.Module_FOUND}")
 endif ()

INSTALL.md

@@ -42,6 +42,10 @@ NEW or CHANGED MINIMUM dependencies since the last major release are **bold**.
      * Python >= 3.9 (tested through 3.13).
      * pybind11 >= 2.7 (tested through 3.0)
      * NumPy (tested through 2.4.4)
+     * If you enable the optional nanobind (WIP) backend for source/CMake
+       builds (`OIIO_PYTHON_BINDINGS_BACKEND` is `nanobind` or `both`):
+         * nanobind discoverable by CMake, or installed in the active Python
+           environment so `python -m nanobind --cmake_dir` works
  * If you want support for PNG files:
      * libPNG >= 1.6.0 (tested though 1.6.56)
  * If you want support for camera "RAW" formats:
@@ -157,6 +161,12 @@ Make wrapper (`make PkgName_ROOT=...`).
 
 `USE_PYTHON=0` : Omits building the Python bindings.
 
+`OIIO_PYTHON_BINDINGS_BACKEND=pybind11|nanobind|both` : Select which Python
+binding backend(s) to configure for source/CMake builds. `both` keeps the
+existing pybind11 module and also builds the nanobind (WIP) module. The
+Python packaging path driven by `pyproject.toml` still targets the production
+pybind11 bindings today.
+
 `OIIO_BUILD_TESTS=0` : Omits building tests (you probably don't need them
 unless you are a developer of OIIO or want to verify that your build
 passes all tests).
@@ -247,6 +257,7 @@ Additionally, a few helpful modifiers alter some build-time options:
 | make USE_QT=0 ...             |  Skip anything that needs Qt                                              |
 | make MYCC=xx MYCXX=yy ...     |  Use custom compilers                                                     |
 | make USE_PYTHON=0 ...         |  Don't build the Python binding                                           |
+| make OIIO_PYTHON_BINDINGS_BACKEND=both ... | For source/CMake builds, build the existing pybind11 bindings and the nanobind (WIP) module |
 | make BUILD_SHARED_LIBS=0      |  Build static library instead of shared                                   |
 | make IGNORE_HOMEBREWED_DEPS=1 |  Ignore homebrew-managed dependencies                                     |
 | make LINKSTATIC=1 ...         |  Link with static external libraries when possible                        |

src/build-scripts/ci-startup.bash

@@ -36,7 +36,7 @@ export PYTHONPATH=$OpenImageIO_ROOT/lib/python${PYTHON_VERSION}/site-packages:$P
 export COMPILER=${COMPILER:=gcc}
 export CC=${CC:=gcc}
 export CXX=${CXX:=g++}
-export OpenImageIO_CI=1
+export OpenImageIO_CI=true
 export USE_NINJA=${USE_NINJA:=1}
 export CMAKE_GENERATOR=${CMAKE_GENERATOR:=Ninja}
 export CMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE:=Release}

src/cmake/externalpackages.cmake

@@ -118,9 +118,13 @@ endif()
 if (USE_PYTHON)
     find_python()
 endif ()
-if (USE_PYTHON)
+if (USE_PYTHON AND OIIO_BUILD_PYTHON_PYBIND11)
     checked_find_package (pybind11 REQUIRED VERSION_MIN 2.7)
 endif ()
+if (USE_PYTHON AND OIIO_BUILD_PYTHON_NANOBIND)
+    discover_nanobind_cmake_dir()
+    checked_find_package (nanobind CONFIG REQUIRED)
+endif ()
 
 
 ###########################################################################

src/cmake/pythonutils.cmake

@@ -8,6 +8,31 @@ set (PYTHON_VERSION "" CACHE STRING "Target version of python to find")
 option (PYLIB_INCLUDE_SONAME "If ON, soname/soversion will be set for Python module library" OFF)
 option (PYLIB_LIB_PREFIX "If ON, prefix the Python module with 'lib'" OFF)
 set (PYMODULE_SUFFIX "" CACHE STRING "Suffix to add to Python module init namespace")
+set (OIIO_PYTHON_BINDINGS_BACKEND "pybind11" CACHE STRING
+     "Which Python binding backend(s) to build: pybind11, nanobind, or both")
+set_property (CACHE OIIO_PYTHON_BINDINGS_BACKEND PROPERTY STRINGS
+              pybind11 nanobind both)
+
+# Normalize and validate the user-facing backend selector early so the rest
+# of the file can make simple boolean decisions.
+string (TOLOWER "${OIIO_PYTHON_BINDINGS_BACKEND}" OIIO_PYTHON_BINDINGS_BACKEND)
+if (NOT OIIO_PYTHON_BINDINGS_BACKEND MATCHES "^(pybind11|nanobind|both)$")
+    message (FATAL_ERROR
+             "OIIO_PYTHON_BINDINGS_BACKEND must be one of: pybind11, nanobind, both")
+endif ()
+
+# Derive internal switches used by the top-level CMakeLists and the Python
+# helper macros below.
+set (OIIO_BUILD_PYTHON_PYBIND11 OFF)
+set (OIIO_BUILD_PYTHON_NANOBIND OFF)
+if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "pybind11"
+        OR OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "both")
+    set (OIIO_BUILD_PYTHON_PYBIND11 ON)
+endif ()
+if (OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "nanobind"
+        OR OIIO_PYTHON_BINDINGS_BACKEND STREQUAL "both")
+    set (OIIO_BUILD_PYTHON_NANOBIND ON)
+endif ()
 if (WIN32)
     set (PYLIB_LIB_TYPE SHARED CACHE STRING "Type of library to build for python module (MODULE or SHARED)")
 else ()
@@ -54,6 +79,15 @@ macro (find_python)
                                 Python3_Development.Module_FOUND
                                 Python3_Interpreter_FOUND )
 
+    if (OIIO_BUILD_PYTHON_NANOBIND)
+        # nanobind's CMake package expects the generic FindPython targets and
+        # variables (Python::Module, Python_EXECUTABLE, etc.), not the
+        # versioned Python3::* targets that the rest of OIIO uses today.
+        find_package (Python ${Python3_VERSION_MAJOR}.${Python3_VERSION_MINOR}
+                      EXACT REQUIRED
+                      COMPONENTS ${_py_components})
+    endif ()
+
     # The version that was found may not be the default or user
     # defined one.
     set (PYTHON_VERSION_FOUND ${Python3_VERSION_MAJOR}.${Python3_VERSION_MINOR})
@@ -63,15 +97,44 @@ macro (find_python)
     set (PythonInterp3_FIND_VERSION PYTHON_VERSION_FOUND)
     set (PythonInterp3_FIND_VERSION_MAJOR ${Python3_VERSION_MAJOR})
 
+    if (NOT DEFINED PYTHON_SITE_ROOT_DIR)
+        set (PYTHON_SITE_ROOT_DIR
+             "${CMAKE_INSTALL_LIBDIR}/python${PYTHON_VERSION_FOUND}/site-packages")
+    endif ()
     if (NOT DEFINED PYTHON_SITE_DIR)
-        set (PYTHON_SITE_DIR "${CMAKE_INSTALL_LIBDIR}/python${PYTHON_VERSION_FOUND}/site-packages/OpenImageIO")
+        set (PYTHON_SITE_DIR "${PYTHON_SITE_ROOT_DIR}/OpenImageIO")
     endif ()
     message (VERBOSE "    Python site packages dir ${PYTHON_SITE_DIR}")
+    message (VERBOSE "    Python site packages root ${PYTHON_SITE_ROOT_DIR}")
     message (VERBOSE "    Python to include 'lib' prefix: ${PYLIB_LIB_PREFIX}")
     message (VERBOSE "    Python to include SO version: ${PYLIB_INCLUDE_SONAME}")
 endmacro()
 
 
+# Help CMake locate nanobind when it was installed as a Python package.
+macro (discover_nanobind_cmake_dir)
+    if (nanobind_DIR OR nanobind_ROOT OR "$ENV{nanobind_DIR}" OR "$ENV{nanobind_ROOT}")
+        return()
+    endif ()
+
+    if (NOT Python3_Interpreter_FOUND)
+        return()
+    endif ()
+
+    execute_process (
+        COMMAND ${Python3_EXECUTABLE} -m nanobind --cmake_dir
+        RESULT_VARIABLE _oiio_nanobind_result
+        OUTPUT_VARIABLE _oiio_nanobind_cmake_dir
+        OUTPUT_STRIP_TRAILING_WHITESPACE
+        ERROR_QUIET)
+    if (_oiio_nanobind_result EQUAL 0
+            AND EXISTS "${_oiio_nanobind_cmake_dir}/nanobind-config.cmake")
+        set (nanobind_DIR "${_oiio_nanobind_cmake_dir}" CACHE PATH
+             "Path to the nanobind CMake package" FORCE)
+    endif ()
+endmacro()
+
+
 ###########################################################################
 # pybind11
 
@@ -163,3 +226,62 @@ macro (setup_python_module)
 
 endmacro ()
 
+
+###########################################################################
+# nanobind
+
+macro (setup_python_module_nanobind)
+    cmake_parse_arguments (lib "" "TARGET;MODULE"
+                           "SOURCES;LIBS;INCLUDES;SYSTEM_INCLUDE_DIRS;PACKAGE_FILES"
+                           ${ARGN})
+
+    set (target_name ${lib_TARGET})
+
+    if (NOT COMMAND nanobind_add_module)
+        discover_nanobind_cmake_dir()
+        find_package (nanobind CONFIG REQUIRED)
+    endif ()
+
+    nanobind_add_module(${target_name} ${lib_SOURCES})
+    if (CMAKE_CXX_COMPILER_ID MATCHES "Clang" AND TARGET nanobind-static)
+        target_compile_options (nanobind-static PRIVATE -Wno-error=format-nonliteral)
+    endif ()
+
+    target_include_directories (${target_name}
+                                PRIVATE ${lib_INCLUDES})
+    target_include_directories (${target_name}
+                                SYSTEM PRIVATE ${lib_SYSTEM_INCLUDE_DIRS})
+    target_link_libraries (${target_name}
+                           PRIVATE ${lib_LIBS})
+
+    set (_module_LINK_FLAGS "${VISIBILITY_MAP_COMMAND} ${EXTRA_DSO_LINK_ARGS}")
+    if (UNIX AND NOT APPLE)
+        set (_module_LINK_FLAGS "${_module_LINK_FLAGS} -Wl,--exclude-libs,ALL")
+    endif ()
+    set_target_properties (${target_name} PROPERTIES
+                           LINK_FLAGS ${_module_LINK_FLAGS}
+                           OUTPUT_NAME ${lib_MODULE}
+                           DEBUG_POSTFIX "")
+
+    if (SKBUILD)
+        set (_nanobind_install_dir .)
+    else ()
+        set (_nanobind_install_dir ${PYTHON_SITE_DIR})
+    endif ()
+
+    # Keep nanobind modules isolated in the build tree so they don't alter
+    # how the existing top-level OpenImageIO module is imported during tests.
+    set_target_properties (${target_name} PROPERTIES
+            LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/nanobind/OpenImageIO
+            ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib/python/nanobind/OpenImageIO
+            )
+
+    install (TARGETS ${target_name}
+             RUNTIME DESTINATION ${_nanobind_install_dir} COMPONENT user
+             LIBRARY DESTINATION ${_nanobind_install_dir} COMPONENT user)
+
+    if (lib_PACKAGE_FILES)
+        install (FILES ${lib_PACKAGE_FILES}
+                 DESTINATION ${_nanobind_install_dir} COMPONENT user)
+    endif ()
+endmacro ()

src/cmake/testing.cmake

@@ -33,6 +33,7 @@ set(OIIO_TESTSUITE_IMAGEDIR "${PROJECT_BINARY_DIR}/testsuite" CACHE PATH
 #                    [ DISABLEVAR variable_name ... ]
 #                    [ SUFFIX suffix ]
 #                    [ ENVIRONMENT "VAR=value" ... ]
+#                    [ ENVIRONMENT_MODIFICATION "VAR=op:value" ... ]
 #                  )
 #
 # The optional argument IMAGEDIR is used to check whether external test images
@@ -55,8 +56,12 @@ set(OIIO_TESTSUITE_IMAGEDIR "${PROJECT_BINARY_DIR}/testsuite" CACHE PATH
 # The optional ENVIRONMENT is a list of environment variables to set for the
 # test.
 #
+# The optional ENVIRONMENT_MODIFICATION is a list of environment variable
+# modifications in the format accepted by the CTest ENVIRONMENT_MODIFICATION
+# property.
+#
 macro (oiio_add_tests)
-    cmake_parse_arguments (_ats "" "SUFFIX;TESTNAME" "URL;IMAGEDIR;LABEL;FOUNDVAR;ENABLEVAR;DISABLEVAR;ENVIRONMENT" ${ARGN})
+    cmake_parse_arguments (_ats "" "SUFFIX;TESTNAME" "URL;IMAGEDIR;LABEL;FOUNDVAR;ENABLEVAR;DISABLEVAR;ENVIRONMENT;ENVIRONMENT_MODIFICATION" ${ARGN})
        # Arguments: <prefix> <options> <one_value_keywords> <multi_value_keywords> args...
     set (_ats_testdir "${OIIO_TESTSUITE_IMAGEDIR}/${_ats_IMAGEDIR}")
     # If there was a FOUNDVAR param specified and that variable name is
@@ -131,6 +136,11 @@ macro (oiio_add_tests)
                              "OIIO_TESTSUITE_CUR=${_testdir}"
                              "Python_EXECUTABLE=${Python3_EXECUTABLE}"
                              ${_ats_ENVIRONMENT})
+            if (_ats_ENVIRONMENT_MODIFICATION)
+                set_property(TEST ${_testname} APPEND PROPERTY
+                             ENVIRONMENT_MODIFICATION
+                             ${_ats_ENVIRONMENT_MODIFICATION})
+            endif ()
             if (NOT ${_ats_testdir} STREQUAL "")
                 set_property(TEST ${_testname} APPEND PROPERTY ENVIRONMENT
                              "OIIO_TESTSUITE_IMAGEDIR=${_ats_testdir}")
@@ -228,25 +238,48 @@ macro (oiio_add_all_tests)
     # Python interpreter itself won't be linked with the right asan
     # libraries to run correctly.
     if (USE_PYTHON AND NOT BUILD_OIIOUTIL_ONLY AND NOT SANITIZE)
-        oiio_add_tests (
-            docs-examples-python
-            python-colorconfig
-            python-deep 
-            python-imagebuf
-            python-imagecache
-            python-imageoutput
-            python-imagespec
-            python-paramlist
-            python-roi
-            python-texturesys
-            python-typedesc
-            filters
-            )
-        # These Python tests also need access to oiio-images
-        oiio_add_tests (
-            python-imageinput python-imagebufalgo
-            IMAGEDIR oiio-images
-            )
+        set (pybind11_python_path_mod
+             "PYTHONPATH=path_list_prepend:${CMAKE_BINARY_DIR}/lib/python/site-packages")
+        set (nanobind_python_tests
+             python-imagespec
+             python-paramlist
+             python-roi
+             python-typedesc)
+        set (nanobind_python_test_suffix ".nanobind")
+        if (OIIO_BUILD_PYTHON_PYBIND11)
+            oiio_add_tests (
+                docs-examples-python
+                python-colorconfig
+                python-deep
+                python-imagebuf
+                python-imagecache
+                python-imageoutput
+                python-imagespec
+                python-paramlist
+                python-roi
+                python-texturesys
+                python-typedesc
+                filters
+                ENVIRONMENT_MODIFICATION ${pybind11_python_path_mod}
+                )
+            # These Python tests also need access to oiio-images
+            oiio_add_tests (
+                python-imageinput python-imagebufalgo
+                IMAGEDIR oiio-images
+                ENVIRONMENT_MODIFICATION ${pybind11_python_path_mod}
+                )
+        else ()
+            set (nanobind_python_test_suffix "")
+        endif ()
+
+        if (OIIO_BUILD_PYTHON_NANOBIND)
+            oiio_add_tests (
+                ${nanobind_python_tests}
+                SUFFIX ${nanobind_python_test_suffix}
+                ENVIRONMENT_MODIFICATION
+                    "PYTHONPATH=path_list_prepend:${CMAKE_BINARY_DIR}/lib/python/nanobind"
+                )
+        endif ()
     endif ()
 
     oiio_add_tests (oiiotool-color

src/libOpenImageIO/CMakeLists.txt

@@ -263,13 +263,11 @@ if (OIIO_BUILD_TESTS AND BUILD_TESTING)
                           LINK_LIBRARIES OpenImageIO Imath::Imath
                           FOLDER "Unit Tests" NO_INSTALL)
     add_test (unit_image_span ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/image_span_test)
-    set_tests_properties (unit_image_span PROPERTIES COST 10)
 
     fancy_add_executable (NAME imagebuf_test SRC imagebuf_test.cpp
                           LINK_LIBRARIES OpenImageIO
                           FOLDER "Unit Tests" NO_INSTALL)
     add_test (unit_imagebuf ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/imagebuf_test)
-    set_tests_properties (unit_imagebuf PROPERTIES COST 30)
 
     fancy_add_executable (NAME imagecache_test SRC imagecache_test.cpp
                           LINK_LIBRARIES OpenImageIO
@@ -286,7 +284,6 @@ if (OIIO_BUILD_TESTS AND BUILD_TESTING)
                           FOLDER "Unit Tests" NO_INSTALL)
     target_compile_definitions (imagebufalgo_test PRIVATE OIIO_USE_HWY=${_oiio_use_hwy})
     add_test (unit_imagebufalgo ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/imagebufalgo_test)
-    set_tests_properties (unit_imagebufalgo PROPERTIES PROCESSORS 2 COST 60)
 
     fancy_add_executable (NAME imagespec_test SRC imagespec_test.cpp
                           LINK_LIBRARIES OpenImageIO
@@ -297,7 +294,6 @@ if (OIIO_BUILD_TESTS AND BUILD_TESTING)
                           LINK_LIBRARIES OpenImageIO
                           FOLDER "Unit Tests" NO_INSTALL)
     add_test (unit_imageinout ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/imageinout_test)
-    set_tests_properties (unit_imageinout PROPERTIES PROCESSORS 2 COST 30)
 
     if (NOT DEFINED ENV{OpenImageIO_CI})
         fancy_add_executable (NAME imagespeed_test SRC imagespeed_test.cpp