AcademySoftwareFoundation · zachlewis · Jul 12, 2026 · Jul 12, 2026 · Jul 12, 2026 · Jul 12, 2026
diff --git a/CHANGES.md b/CHANGES.md
@@ -18,6 +18,9 @@ Release 3.2 (target: Sept 2026?) -- compared to 3.1
   - *oiiotool*: New `--nchannels` flag to specify the number of output channels, for parity with maketx. [#5198](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5198) (by Danny Greenstein) (3.2.0.3, 3.1.14.0)
   - *oiiotool*: Commands taking offsets or geometry arguments now accept commas as alternative separators (e.g., `X,Y` or `WxH,X,Y` in addition to the X11-style `+X+Y` form). This affects `--create`, `--crop`, `--cut`, `--fit`, `--fullsize`, `--origin`, `--originoffset`, `--paste`, `--pattern`, `--printstats`, `--resize`. [#5209](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5209) (3.2.0.3, 3.1.14.0)
   - *oiiotool*: Be more cautious about implicit promotion to float when `--autocc` is used alongside explicit color space names. [#5192](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5192) (3.2.0.3, 3.1.14.0)
+  - *oiiotool*: New `--colorspacesearch` flag prints the color spaces in the active config whose derivable characteristics match a partial description, without needing to know the config's naming conventions. Each hint axis is a comma-separated list of terms via the modifiers `chromaticities=` (shorthand `chrm=`), `transfer_function=`, `encoding=`, `image_state=`, with inclusion toggles `include_inactive=`, `include_context_sensitive=`, `include_complex=`, `authored_encoding_only=`; colon-bearing terms may be passed as quoted modifier values. [#XXXX](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/XXXX) (3.2.0.4)
+  - *oiiotool*: New `--colorwriteplan FORMAT` flag prints, without writing any file, the color metadata OIIO would write for the current top image to the named format -- per signal: the verdict (write/derive/suppress/omit), the value, and which policy layer decided it (builtin default, global attribute, per-spec attribute, explicit metadata, or format incapability). [#XXXX](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/XXXX) (3.2.0.4)
+  - *oiiotool*: New `--colorinfo COLORSPACES` flag prints, for each color space in a comma-separated list (or for the current top image's color space if the list is empty), the characterization info available from the active config -- image state, color interop ID, encoding, range, and cached derived facts -- one row per field with an available/derived/unavailable/uncomputed marker. It is a tool-facing diagnostic and does no new probing or derivation. [#XXXX](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/XXXX) (3.2.0.4)
 * *Command line utilities*:
   - *iv*: Flip, rotate and save image [#5003](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5003) (by Valery Angelique) (3.2.0.0, 3.1.11.0)
   - *iconvert*: Allow `-o outfile` for output file designation, for parity with oiiotool syntax. [#5173](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5173) (3.2.0.3, 3.1.14.0)
@@ -54,6 +57,10 @@ Release 3.2 (target: Sept 2026?) -- compared to 3.1
   - *jpeg-xl*: CICP read and write support for JPEG-XL [#4968](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/4968) (by Brecht Van Lommel) (3.2.0.0, 3.1.9.0)
   - *jpeg-xl*: ICC read and write for JPEG-XL files (issue 4649) [#4905](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/4905) (by shanesmith-dwa) (3.0.14.0, 3.2.0.0)
   - *color mgmt*: For OCIO built-in configs, replace the default file rules with more sensible ones that avoid spurious matches (e.g., no longer assumes all `.exr` files use ACES2065-1 primaries). [#5194](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5194) (3.2.0.3, 3.1.14.0)
+  - *color mgmt*: Map the CICP Rec.709 primaries + sRGB-transfer tuple to display-referred sRGB (`srgb_rec709_display`) rather than the scene-referred entry, so CICP-tagged reads resolve to the intended display encoding. [#XXXX](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/XXXX) (3.2.0.4)
+  - *color mgmt*: `ColorConfig` color and display conversions now bridge across differing OCIO configs through the `aces_interchange` role, so a source space known only to a foreign config can be reconciled into the active config. When the two configs are not color-interoperable and OCIO strict parsing is off, the conversion falls back to a pass-through that leaves pixels untouched and keeps the honest source color-space tag instead of mistagging the result with the requested destination; a once-per-config interoperability warning is emitted (debug-gated). [#XXXX](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/XXXX) (3.2.0.4)
+  - *ImageBufAlgo* **behavior change**: the color-aware operations (`colorconvert`, `ociolook`, `ociodisplay`, `ociofiletransform`) now automatically maintain the output's color metadata as a best-effort convenience. When the resulting space is known, the operation updates `oiio:ColorSpace`, maintains the new cheap current-state descriptor attributes `oiio:ColorSpace:state` / `:encoding` / `:range` / `:equality_id` (each present only when its value is actually known -- updated or erased, never guessed or derived), and removes stale file-provenance attributes (`colorInteropID`, `CICP`, `ICCProfile`, `chromaticities`, `oiio:Gamma`, `acesImageContainerFlag`) that described the pre-operation source. This scrub now applies uniformly whether the source space was named explicitly or inferred from metadata (previously only the inferred-source path scrubbed), so callers should set metadata overrides after the last color operation. `ociofiletransform` with an arbitrary LUT now erases the color-space verdict and related metadata entirely (the resulting space cannot be known and absence is the honest answer), unless the file's name identifies the result space via the config's file rules, which keeps its longstanding tagging behavior. `ociolook` and `ociodisplay` gain the same untagged-source inference `colorconvert` already had, and space-preserving no-ops (data spaces, cross-config pass-throughs) now leave still-true metadata untouched. The deliberate unknown-marker family (`ocio:unknown` / `oiio:unknown` / `error:unknown`) is always honored and never scrubbed. Automatic tracking is documented as a convenience, not a contract: tracking gaps are not errors, but under a strict resolution scope an operation whose source cannot be resolved now errors (via the usual `has_error()` convention) instead of silently guessing, honoring a config-declared `error:unknown` catch space when the config also enables strict parsing. [#XXXX](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/XXXX) (3.2.0.4)
+  - *color mgmt* **behavior enrichment**: `ColorConfig::set_colorspace()` (and the `ImageSpec::set_colorspace()` / free-function conveniences that route through it) now applies the same two-bucket color-metadata hygiene as the color-aware `ImageBufAlgo` operations. Asserting a different color space than the spec already claims scrubs every now-contradicting file-provenance attribute (`colorInteropID`, `CICP`, `chromaticities`, `ICCProfile`, `oiio:Gamma`, `acesImageContainerFlag`, plus the longstanding `Exif:ColorSpace` / `tiff:*` invalidations), and maintains -- update-or-erase from the cheap characterization, never guessed or derived -- any `oiio:ColorSpace:state` / `:encoding` / `:range` / `:equality_id` current-state descriptors the spec carries. An empty name now erases all of it (verdict, facts, and descriptors: assume nothing). First tagging of an untagged spec and re-assertion of the current space keep their previous behavior exactly, so read paths that derive the tag from just-read metadata are unchanged. [#XXXX](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/XXXX) (3.2.0.4)
 * Other notable new feature:
   - *tiff*: Support for GPS metadata fields (latitude, longitude, altitude, timestamp, and related EXIF GPS fields) when using libTIFF 4.2+. [#5050](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5050) (3.2.0.1, 3.1.12.0)
   - *heif*: Add IOProxy support for both input and output [#5017](https://github.com/AcademySoftwareFoundation/OpenImageIO/pull/5017) (by Brecht Van Lommel) (3.2.0.0, 3.1.10.0)

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -223,7 +223,17 @@ if (IGNORE_HOMEBREWED_DEPS)
              )
     endforeach ()
 
+    # CMAKE_IGNORE_PATH only blocks exact directories; config packages
+    # (e.g. <prefix>/lib/cmake/Imath) are found by prefix search and slip
+    # through. CMAKE_IGNORE_PREFIX_PATH (CMake 3.23+) blocks the whole
+    # prefix, and dependency_utils forwards it to local dependency child
+    # builds so they cannot resolve a different Homebrew copy than the
+    # parent (e.g. Homebrew Imath 3.2 inside a local OpenEXR build while
+    # OIIO links the local-dist Imath -- a mangled-symbol link failure).
+    list (APPEND CMAKE_IGNORE_PREFIX_PATH ${HOMEBREW_PREFIXES})
+
     message (STATUS "CMAKE_IGNORE_PATH: ${CMAKE_IGNORE_PATH}")
+    message (STATUS "CMAKE_IGNORE_PREFIX_PATH: ${CMAKE_IGNORE_PREFIX_PATH}")
 endif ()
 
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -332,6 +332,20 @@ clang-format is installed on your local machine, and just run
 
     make clang-format
 
+**clang-format must be older than version 18.** It is an optional dev
+dependency, but a version-sensitive one: clang-format's output is not stable
+across major releases, so a newer binary will reformat the entire tree in a
+way the CI check then rejects. CI pins clang-format 17, and the build
+configuration enforces the same bound — if the clang-format it finds is 18 or
+newer, it prints a warning and disables the `clang-format` target rather than
+let you reformat the tree incorrectly.
+
+If your system clang-format is too new, either install a 17.x build and point
+the configuration at it with `CLANG_FORMAT_EXE_HINT=/path/to/its/bin`, or run
+the pinned version directly without installing anything:
+
+    uvx clang-format@17.0.6 --style=file -i <files>
+
 and it will automatically reformat your code according to the configuration
 file found in the `.clang-format` file at the root directory of the OIIO
 source code checkout.

diff --git a/pyproject.toml b/pyproject.toml
@@ -130,6 +130,10 @@ CXXFLAGS = "-Wno-error=stringop-overflow -Wno-pragmas"
 SKBUILD_CMAKE_BUILD_TYPE = "MinSizeRel"
 # FIXME: Getting build problems when using WebP 1.6.0, so hold it back
 WebP_BUILD_VERSION = "1.5.0"
+# The commit hash pin in src/cmake/build_WebP.cmake is for v1.6.0; override
+# it to the v1.5.0 commit to match the held-back version above, else the
+# tag-verification check fails the wheel build.
+WebP_GIT_COMMIT = "a4d7a715337ded4451fec90ff8ce79728e04126c"
 
 [tool.cibuildwheel.windows.environment]
 SKBUILD_CMAKE_BUILD_TYPE = "MinSizeRel"

diff --git a/src/cmake/compiler.cmake b/src/cmake/compiler.cmake
@@ -630,8 +630,46 @@ if (PROJECT_IS_TOP_LEVEL)
                   NO_DEFAULT_PATH
                   DOC "Path to clang-format executable")
     find_program (CLANG_FORMAT_EXE NAMES clang-format bin/clang-format)
+    # clang-format is an OPTIONAL dev dependency, but a version-sensitive one:
+    # its output is not stable across major releases, so a newer binary will
+    # happily reformat the whole tree in a way the CI check then rejects. The
+    # CI matrix pins clang-format-17 (see CLANG_FORMAT_EXE dance in ci.yml), so
+    # accept only < 18 and otherwise decline to wire the target -- reformatting
+    # with the wrong version is strictly worse than not reformatting at all.
+    set (CLANG_FORMAT_USABLE OFF)
     if (CLANG_FORMAT_EXE)
-        message (STATUS "clang-format found: ${CLANG_FORMAT_EXE}")
+        set (CLANG_FORMAT_USABLE ON)
+        execute_process (COMMAND "${CLANG_FORMAT_EXE}" --version
+                         OUTPUT_VARIABLE CLANG_FORMAT_VERSION_OUTPUT
+                         ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE
+                         RESULT_VARIABLE _cf_result)
+        if (_cf_result EQUAL 0 AND
+            CLANG_FORMAT_VERSION_OUTPUT MATCHES "([0-9]+)\\.[0-9]+\\.[0-9]+")
+            set (CLANG_FORMAT_VERSION_MAJOR ${CMAKE_MATCH_1})
+        else ()
+            set (CLANG_FORMAT_VERSION_MAJOR "")
+        endif ()
+        if (NOT CLANG_FORMAT_VERSION_MAJOR)
+            message (STATUS "clang-format found (${CLANG_FORMAT_EXE}) but its "
+                            "version could not be determined -- skipping the "
+                            "clang-format target.")
+            set (CLANG_FORMAT_USABLE OFF)
+        elseif (CLANG_FORMAT_VERSION_MAJOR GREATER_EQUAL 18)
+            message (WARNING
+                     "clang-format ${CLANG_FORMAT_VERSION_MAJOR} found at "
+                     "${CLANG_FORMAT_EXE}, but this project requires "
+                     "clang-format < 18 (CI pins 17). Its output differs from "
+                     "17's, so 'make clang-format' would reformat the tree in "
+                     "a way CI rejects. The 'clang-format' target is disabled. "
+                     "Install a 17.x binary and point CLANG_FORMAT_EXE_HINT at "
+                     "it, or run the pinned version directly with no install: "
+                     "uvx clang-format@17.0.6 --style=file -i <files>")
+            set (CLANG_FORMAT_USABLE OFF)
+        endif ()
+    endif ()
+    if (CLANG_FORMAT_USABLE)
+        message (STATUS "clang-format found: ${CLANG_FORMAT_EXE} "
+                        "(version ${CLANG_FORMAT_VERSION_MAJOR})")
         # Start with the list of files to include when formatting...
         file (GLOB_RECURSE FILES_TO_FORMAT ${CLANG_FORMAT_INCLUDES})
         # ... then process any list of excludes we are given
@@ -644,7 +682,7 @@ if (PROJECT_IS_TOP_LEVEL)
               DESTINATION ${CMAKE_CURRENT_BINARY_DIR})
         add_custom_target (clang-format
             COMMAND "${CLANG_FORMAT_EXE}" -i -style=file ${FILES_TO_FORMAT} )
-    else ()
+    elseif (NOT CLANG_FORMAT_EXE)
         message (STATUS "clang-format not found.")
     endif ()
 endif ()

diff --git a/src/cmake/dependency_utils.cmake b/src/cmake/dependency_utils.cmake
@@ -727,10 +727,15 @@ macro (build_dependency_with_cmake pkgname)
 
     # Make sure to inherit CMAKE_IGNORE_PATH
     set(_pkg_CMAKE_ARGS ${_pkg_CMAKE_ARGS} ${_pkg_CMAKE_ARGS})
-    if (CMAKE_IGNORE_PATH)
-        string(REPLACE ";" "\\;" CMAKE_IGNORE_PATH_ESCAPED "${CMAKE_IGNORE_PATH}")
-        list(APPEND _pkg_CMAKE_ARGS "-DCMAKE_IGNORE_PATH=${CMAKE_IGNORE_PATH_ESCAPED}")
-    endif()
+    # CMAKE_IGNORE_PREFIX_PATH too: unlike CMAKE_IGNORE_PATH it also blocks
+    # config-package prefix search, so child builds cannot resolve a system
+    # (e.g. Homebrew) copy of a dependency the parent build is ignoring.
+    foreach (_ignore_var IN ITEMS CMAKE_IGNORE_PATH CMAKE_IGNORE_PREFIX_PATH)
+        if (${_ignore_var})
+            string(REPLACE ";" "\\;" _ignore_escaped "${${_ignore_var}}")
+            list(APPEND _pkg_CMAKE_ARGS "-D${_ignore_var}=${_ignore_escaped}")
+        endif()
+    endforeach()
 
     # Pass along any CMAKE_MSVC_RUNTIME_LIBRARY
     if (WIN32 AND CMAKE_MSVC_RUNTIME_LIBRARY)

diff --git a/src/cmake/testing.cmake b/src/cmake/testing.cmake
@@ -267,6 +267,8 @@ macro (oiio_add_all_tests)
         set (nanobind_python_test_suffix ".nanobind")
         if (OIIO_BUILD_PYTHON_PYBIND11)
             oiio_add_tests (
+                colorinfo
+                colorspacesearch
                 docs-examples-python
                 python-colorconfig
                 python-deep
@@ -279,6 +281,8 @@ macro (oiio_add_all_tests)
                 python-roi
                 python-texturesys
                 python-typedesc
+                sourceprovenance
+                cicp-write-strip
                 filters
                 ENVIRONMENT "${_pybind_tests_pythonpath}"
                 )
@@ -302,8 +306,22 @@ macro (oiio_add_all_tests)
     endif ()
 
     oiio_add_tests (oiiotool-color
+                    color-interop-convert
                     FOUNDVAR OpenColorIO_FOUND)
 
+    # These color tests drive oiiotool through POSIX-shell constructs
+    # (per-command `env VAR=` prefixes, single-quoted echo, grep pipelines)
+    # that cmd.exe cannot run; skip them on Windows until they are
+    # rewritten portably. The behavior they exercise is platform-neutral.
+    if (NOT WIN32)
+        oiio_add_tests (oiiotool-colorwriteplan)
+        oiio_add_tests (oiiotool-colorpolicy-config
+                        oiiotool-colorroundtrip
+                        oiiotool-colorverbose
+                        oiiotool-colorprofile
+                        FOUNDVAR OpenColorIO_FOUND)
+    endif ()
+
     # Tests to run with HWY enabled.
     # Remember to add tests here as hwy enabled IBA functions are added
     oiio_add_tests ( oiiotool