Merge branch 'main' of github.com:AcademySoftwareFoundation/OpenImageIO

Author: scott-wilson

.github/workflows/build-steps.yml

@@ -104,8 +104,6 @@ jobs:
     steps:
       - name: Checkout repo
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          fetch-depth: '0'
       - name: Prepare ccache timestamp
         id: ccache_cache_keys
         shell: bash

.github/workflows/ci.yml

@@ -176,8 +176,6 @@ jobs:
       #     egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
       - name: Checkout repo
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
-        with:
-          fetch-depth: '0'
       - name: Prepare ccache timestamp
         id: ccache_cache_keys
         run: echo "date=`date -u +'%Y-%m-%dT%H:%M:%SZ'`" >> $GITHUB_OUTPUT
@@ -340,7 +338,16 @@ jobs:
             fmt_ver: 10.1.1
             pybind11_ver: v2.12.0
             setenvs: PUGIXML_VERSION=v1.14
-          - desc: VFX2024 sanitizers
+          - desc: VFX2025 gcc11/C++17 py3.11 exr3.3 ocio2.4
+            nametag: linux-vfx2025
+            runner: ubuntu-latest
+            container: aswftesting/ci-oiio:2025
+            python_ver: "3.11"
+            simd: "avx2,f16c"
+            fmt_ver: 11.1.4
+            pybind11_ver: v2.13.6
+            setenvs: PUGIXML_VERSION=v1.15
+          - desc: Sanitizers
             nametag: sanitizer
             runner: ubuntu-latest
             container: aswf/ci-osl:2024-clang17
@@ -367,7 +374,7 @@ jobs:
             simd: "avx2,f16c"
             skip_tests: 1
             # abi_check: v2.6.2.0
-            abi_check: 730687ae79bb6c3290afff535aa0e98b0531d165
+            abi_check: b35615200396c4767966446e446b4fe5ad960d2a
             setenvs: export OIIO_CMAKE_FLAGS="-DOIIO_BUILD_TOOLS=0 -DOIIO_BUILD_TESTS=0 -DUSE_PYTHON=0"
                             USE_OPENCV=0 USE_FFMPEG=0 USE_PYTHON=0 USE_FREETYPE=0
 
@@ -397,7 +404,7 @@ jobs:
             cc_compiler: gcc-13
             cxx_compiler: g++-13
             cxx_std: 20
-            fmt_ver: 11.1.4
+            fmt_ver: 11.2.0
             opencolorio_ver: v2.4.2
             openexr_ver: v3.3.3
             pybind11_ver: v2.13.6
@@ -598,12 +605,21 @@ jobs:
         include:
           - desc: Windows-2019 VS2019
             runner: windows-2019
+            nametag: windows-2019
             vsver: 2019
             generator: "Visual Studio 16 2019"
             python_ver: "3.9"
             setenvs: export OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1
           - desc: Windows-2022 VS2022
             runner: windows-2022
+            nametag: windows-2022
+            vsver: 2022
+            generator: "Visual Studio 17 2022"
+            python_ver: "3.9"
+            setenvs: export OPENIMAGEIO_PYTHON_LOAD_DLLS_FROM_PATH=1
+          - desc: Windows-2025 VS2022
+            runner: windows-2025
+            nametag: windows-2025
             vsver: 2022
             generator: "Visual Studio 17 2022"
             python_ver: "3.9"

.github/workflows/release-sign.yml

@@ -48,8 +48,8 @@ jobs:
           echo OPENIMAGEIO_TARBALL=OpenImageIO-${TAG//v}.tar.gz >> $GITHUB_ENV
         shell: bash
 
-      - name: Checkout
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - name: Checkout repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
       - name: Create archive
         run: git archive --format=tar.gz -o ${OPENIMAGEIO_TARBALL} --prefix ${OPENIMAGEIO_PREFIX} ${TAG}

.github/workflows/scorecard.yml

@@ -40,11 +40,10 @@ jobs:
       actions: read
 
     steps:
-      - name: "Checkout code"
+      - name: Checkout repo
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
         with:
           persist-credentials: false
-          fetch-depth: '0'
 
       - name: "Run analysis"
         uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1
@@ -66,7 +65,7 @@ jobs:
       # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
       # format to the repository Actions tab.
       - name: "Upload artifact"
-        uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 # v4.3.0
+        uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
         with:
           name: SARIF file
           path: results.sarif

.github/workflows/wheel.yml

@@ -58,15 +58,16 @@ jobs:
 
     steps:
 
-    - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+    - name: Checkout repo
+      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
     - name: Build SDist
       run: pipx run build --sdist
 
     - name: Check metadata
       run: pipx run twine check dist/*
 
-    - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+    - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
       with:
         name: cibw-sdist
         path: dist/*.tar.gz
@@ -140,24 +141,33 @@ jobs:
             arch: x86_64
 
     steps:
-      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Checkout repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
-        name: Install Python
+      - name: Install Python
+        uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
         with:
           python-version: '3.9'
 
       - name: Build wheels
+        # Note: the version of cibuildwheel should be kept in sync with src/python/stubs/CMakeLists.txt
         uses: pypa/cibuildwheel@d4a2945fcc8d13f20a1b99d461b8e844d5fc6e23 # v2.21.1
         env:
+          # pass GITHUB_ACTIONS through to the build container so that custom
+          # processes can tell they are running in CI.
+          CIBW_ENVIRONMENT_PASS_LINUX: GITHUB_ACTIONS
           CIBW_BUILD: ${{ matrix.python }}
           CIBW_ARCHS: ${{ matrix.arch }}
           CIBW_MANYLINUX_X86_64_IMAGE: ${{ matrix.manylinux }}
 
-      - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+      - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
         with:
           name: cibw-wheels-${{ matrix.python }}-${{ matrix.manylinux }}
-          path: ./wheelhouse/*.whl
+          path: |
+            ./wheelhouse/*.whl
+            ./wheelhouse/OpenImageIO/__init__.pyi
+        # if stub validation fails we want to upload the stubs for users to review
+        if: success() || failure()
 
   # ---------------------------------------------------------------------------
   # Linux ARM Wheels
@@ -201,10 +211,11 @@ jobs:
               arch: aarch64
 
       steps:
-        - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+        - name: Checkout repo
+          uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-        - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
-          name: Install Python
+        - name: Install Python
+          uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
           with:
             python-version: '3.9'
 
@@ -215,10 +226,14 @@ jobs:
             CIBW_ARCHS: ${{ matrix.arch }}
             CIBW_MANYLINUX_AARCH64_IMAGE: ${{ matrix.manylinux }}
 
-        - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+        - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
           with:
             name: cibw-wheels-${{ matrix.python }}-${{ matrix.manylinux }}
-            path: ./wheelhouse/*.whl
+            path: |
+              ./wheelhouse/*.whl
+              ./wheelhouse/OpenImageIO/__init__.pyi
+          # if stub validation fails we want to upload the stubs for users to review
+          if: success() || failure()
 
   # ---------------------------------------------------------------------------
   # macOS Wheels
@@ -256,10 +271,11 @@ jobs:
             arch: x86_64
 
     steps:
-      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Checkout repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
-        name: Install Python
+      - name: Install Python
+        uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
         with:
           python-version: '3.9'
 
@@ -273,7 +289,7 @@ jobs:
           # not include GPL-licensed dynamic libraries.
           USE_Libheif: 'OFF'
 
-      - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+      - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
         with:
           name: cibw-wheels-${{ matrix.python }}
           path: ./wheelhouse/*.whl
@@ -314,10 +330,11 @@ jobs:
             arch: arm64
 
     steps:
-      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Checkout repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
-        name: Install Python
+      - name: Install Python
+        uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
         # https://cibuildwheel.pypa.io/en/stable/faq/#macos-building-cpython-38-wheels-on-arm64
         with:
           python-version: '3.8'
@@ -330,7 +347,7 @@ jobs:
           CIBW_ARCHS: ${{ matrix.arch }}
           CMAKE_GENERATOR: "Unix Makefiles"
 
-      - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+      - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
         with:
           name: cibw-wheels-${{ matrix.python }}
           path: ./wheelhouse/*.whl
@@ -371,10 +388,11 @@ jobs:
             arch: AMD64
 
     steps:
-      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
+      - name: Checkout repo
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
-        name: Install Python
+      - name: Install Python
+        uses: actions/setup-python@f677139bbe7f9c59b41e40162b753c062f5d49a3 # v5.2.0
         with:
           python-version: '3.9'
 
@@ -385,7 +403,7 @@ jobs:
           CIBW_ARCHS: ${{ matrix.arch }}
           CMAKE_POLICY_VERSION_MINIMUM: 3.5
 
-      - uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+      - uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4.5.0
         with:
           name: cibw-wheels-${{ matrix.python }}
           path: ./wheelhouse/*.whl

.gitignore

@@ -23,6 +23,7 @@ gastest.o
 /*.exr
 /*.tif
 /*.jpg
+/*.png
 /*.jxl
 /*.tx
 /*.log

CMakeLists.txt

@@ -4,7 +4,7 @@
 
 cmake_minimum_required (VERSION 3.18.2...4.0)
 
-set (OpenImageIO_VERSION "3.1.1.0")
+set (OpenImageIO_VERSION "3.1.2.0")
 set (OpenImageIO_VERSION_OVERRIDE "" CACHE STRING
      "Version override (use with caution)!")
 mark_as_advanced (OpenImageIO_VERSION_OVERRIDE)

INSTALL.md

@@ -74,6 +74,8 @@ NEW or CHANGED MINIMUM dependencies since the last major release are **bold**.
      * Ptex >= 2.3.1 (probably works for older; tested through 2.4.3)
  * If you want to be able to do font rendering into images:
      * Freetype >= 2.10.0 (tested through 2.13)
+ * If you want to be able to read "ultra-HDR" embedded in JPEG files:
+     * libultrahdr >= 1.3 (tested through 1.4)
  * We use PugiXML for XML parsing. There is a version embedded in the OIIO
    tree, but if you want to use an external, system-installed version (as
    may be required by some software distributions with policies against
@@ -393,6 +395,25 @@ the headers, and the CLI tools to a platform-specific, Python-specific location.
 See the [scikit-build-core docs](https://scikit-build-core.readthedocs.io/en/latest/configuration.html#configuring-cmake-arguments-and-defines)
 for more information on customizing and overriding build-tool options and CMake arguments.
 
+This repo contains python type stubs which are generated from `pybind11` signatures.
+The workflow for releasing new stubs is as follows:
+
+- Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) and `docker`
+- Run `make pystubs` locally to generate updated stubs in `src/python/stubs/__init__.pyi`
+- Run `make test-pystubs` locally to use mypy to test the stubs against the code in 
+  the python testsuite.
+- Commit the new stubs and push to Github
+- In CI, the stubs will be included in the wheels built by `cibuildwheel`, as defined in `.github/wheel.yml`
+- In CI, one of the `cibuildwheel` Github actions will rebuild the stubs to a 
+  temp location and verify that they match what has been committed to the repo.  
+  This step ensures that if changes to the C++ source code and bindings results 
+  in a change to the stubs, developers are notified of the need to regenerate 
+  the stubs, so that changes can be reviewed and the rules in `generate_stubs.py` 
+  can be updated, if necessary.
+
+Note that if you can't (or don't want to) build the stubs locally, you can 
+download an artifact containing the wheel and `__init__.pyi` file from any job 
+that fails the stub validation.
 
 Test Images
 -----------

Makefile

@@ -243,6 +243,18 @@ build: config
 	    ${CMAKE} --build . --config ${CMAKE_BUILD_TYPE} \
 	  )
 
+# generate python stubs and add them to the repo
+pystubs: config
+	@ ( cd ${build_dir} ; \
+	    ${CMAKE} --build . --config ${CMAKE_BUILD_TYPE} --target pystubs \
+	  )
+
+# run mypy on python tests to confirm the stubs are working
+test-pystubs: pystubs
+	@ ( uv export --quiet --no-dev --no-build --no-emit-project --no-hashes -o ${build_dir}/requirements.txt ; \
+	    uvx --with-requirements ${build_dir}/requirements.txt mypy==1.15.0 \
+	  )
+
 # 'make install' builds everthing and installs it in 'dist'.
 # Suppress pointless output from docs installation.
 install: build

pyproject.toml

@@ -122,4 +122,31 @@ CXXFLAGS = "-Wno-error=stringop-overflow -Wno-pragmas"
 SKBUILD_CMAKE_BUILD_TYPE = "MinSizeRel"
 
 [tool.cibuildwheel.windows.environment]
-SKBUILD_CMAKE_BUILD_TYPE = "MinSizeRel"
+SKBUILD_CMAKE_BUILD_TYPE = "MinSizeRel"
+
+[[tool.cibuildwheel.overrides]]
+# Trigger the build & validation of the python stubs for certain platforms.
+# The test command acts as a kind of "post-build" callback where it's possible
+# for the stub-generator to import the freshly-built wheel.
+# There are two entry-points which are designed to call generate_stubs.py through
+# this test command:
+# - `make pystubs` is called during local development to generate the
+#   stubs and copy them into the git repo to be committed and reviewed.
+# - in CI, the cibuildwheel action is used to validate that the stubs match what
+#   has been committed to the repo.
+test-requires = "mypy~=1.15.0 stubgenlib~=0.1.0"
+# Note: the python version here must be kept in sync with src/python/stubs/CMakeLists.txt
+select = "cp311-manylinux_*64"
+inherit.test-command = "append"
+test-command = [
+    "python {project}/src/python/stubs/generate_stubs.py --out-path '/output' --validate-path '{project}/src/python/stubs/OpenImageIO/__init__.pyi'",
+]
+
+[tool.mypy]
+files = [
+    "testsuite/python-*/src/",
+]
+mypy_path = [
+    "src/python/stubs",
+]
+check_untyped_defs = true