COMP: Make ITKVtkGlue wrapping abi3-compatible

[hjmjohnson]

Makes ITKVtkGlue's Python wrapping stable-ABI clean, so it can be built with ITK_USE_PYTHON_LIMITED_API=ON — the configuration its FATAL_ERROR previously rejected. Closes #6711.

Scope is deliberately limited to Modules/Bridge/VtkGlue/. No CMake option, Python discovery, or wrapping-macro behaviour changes here; whether ITK should default to abi3 is separate work, tracked in #6757 along with free-threading and abi3t.

Because Limited API calls are also valid in a full-API build, one implementation serves both modes — the module does not become abi3-only, and the FATAL_ERROR is removed rather than inverted.

Verified on macOS 26 / arm64 only. No Linux or Windows verification, and no Slicer test result.

The fix, and a defect in the approach #6711 proposed

VtkGlue.i exchanged pointers with VTK through vtkPythonUtil, whose header chain reaches PyVTKObject.h and touches PyTypeObject members that Py_LIMITED_API hides. The typemaps now use Limited API calls only, parsing VTK's __this__ encoding and reconstructing through Addr=0x....

VTK::WrappingPythonCore is dropped from the wrapping link interface. This is a correctness requirement rather than tidying: that library is built against one libpython, so an extension linking it cannot be version-agnostic.

Defect in the sketch from #6711. The issue proposed PyObject_CallFunction(cls, "s", addr), i.e. vtkImageData("Addr=0x…"). On VTK 9.6.2 this fails, but only for vtkImageData and vtkPolyData, and only in the pointer-to-object direction. The cause is not ABI-related: vtkmodules/util/data_model.py registers @vtkImageData.override with a Python subclass whose __init__(self, **kwargs) is keyword-only, so the positional address string never reaches VTK's C-level reconstruction. vtkImageExport, vtkImageImport, vtkObject and vtkPoints have no override and were unaffected.

The fix is to call __new__ explicitly: it bypasses the override's __init__ while still returning the enhanced ImageData type, with pointer identity preserved.

Neither __this__ nor Addr=0x... is documented VTK API, so PythonVtkGlueABI3EncodingTest exists to fail loudly and specifically if VTK changes either one. PythonVtkGlueRoundTripTest exercises the typemaps end to end.

Environments verified (and what was not)

Platform: macOS 26 / arm64, Apple clang via conda-forge toolchain.
VTK: github.com/slicer/VTK at 6181bb1223bbc499a340a1644f5356e7e152c318 — the SHA Slicer's SuperBuild/External_VTK.cmake pins for its 9.6 series — built with Qt6 6.9.1, full rendering, and Python wrapping.

Both wrapping modes, built and tested separately

Check	ITK_USE_PYTHON_LIMITED_API=ON	=OFF
Build	8565/8565, 0 FAILED:	8565/8565, 0 FAILED:
ctest -R Python	177/177	177/177
PythonVtkGlueABI3EncodingTest	passed	passed
PythonVtkGlueRoundTripTest	passed	passed
Module suffix	_ITKVtkGluePython.abi3.so	_ITKVtkGluePython.so

pre-commit run --all-files: exit 0.

Artifact audit (limited-API mode)

Property	Value
_ITKVtkGluePython.abi3.so undefined Py* symbols	71, all Limited API
PyVTK* / vtkPythonUtil symbols	0
libvtkWrappingPythonCore linked	0
libpython linked	none

Multi-interpreter. Extensions were built against pixi Python 3.13.9; the others are Homebrew builds, a different distribution. VTK's Python wrappers were built separately for cp311/cp312/cp313/cp314 against the same VTK C++ libraries, so each row pairs the same ITK .abi3.so with a different version-specific VTK.

Interpreter	abi3 module loads	Filter result	VtkGlue round-trip
3.11.15	yes	7.0	OK
3.12.13	yes	7.0	OK
3.13.9 (build interpreter)	yes	7.0	OK
3.14.6	yes	7.0	OK

The 3.11 and 3.14 rows are the substantive ones: that .abi3.so was compiled against cp313 VTK headers yet drove full round-trips against cp311 and cp314 VTK modules. While VTK::WrappingPythonCore was linked, those pairings were structurally impossible.

Downstream

• Standalone ITK with ITK_WRAP_PYTHON=OFF, Module_ITKVtkGlue=ON: 2730/2730 targets, 0 errors.
• Slicer: its ITK external project built successfully against this branch, together with ~20 other external projects. No Slicer tests ran — the Slicer build is blocked in GDCM by a conda/system library shadowing problem in the local test environment, independent of this branch (the diff is wrapping-only and Slicer's ITK is ITK_WRAP_PYTHON=OFF).

Not verified: Linux, Windows, any non-arm64 target, and any completed Slicer test suite.

[dzenanz]

Looks good on a glance. Matt and Brad should review this.

[hjmjohnson]

Force-push a8b614a044 → 30bd48d4d0b: content-only fix for the ITK.macOS.Python failure (no rebase mixed in — the branch was already current with main).

libITKCommon failed to link with undefined _Py_BuildValue / _Py_Dealloc. Fixed by folding into the commit that introduced it.

Root cause

Modules/Core/Common/src/CMakeLists.txt has two uses of _itk_python_target: the INCLUDE_DIRECTORIES source property, and target_link_libraries(ITKCommon PRIVATE ${_itk_python_target}) about 100 lines further down. The commit that replaced the variable with Python3::SABIModule updated only the first, leaving the second to expand to an empty string. ITKCommon then stopped linking Python3::SABIModule and lost its INTERFACE_LINK_OPTIONS, i.e. -undefined dynamic_lookup.

It failed on exactly one configuration because three things have to line up: an undefined CMake variable expands to empty without error, ELF shared objects tolerate undefined symbols, and static archives never resolve them at all. Only a shared macOS build links libITKCommon.dylib strictly enough to notice — hence green Linux Python (177 tests) and green CDash while macOS Python failed at 764/5404 with 0 tests run.

Verified by configuring main and this branch side by side with BUILD_SHARED_LIBS=ON: main emits 98 dynamic_lookup link options, the broken branch 97, and the fixed branch 98 again, with the missing one being libITKCommon. libITKCommon-6.0.1.dylib now links, and nm -u shows _Py_BuildValue and _Py_Dealloc present as permitted undefined symbols.

[hjmjohnson]

Two force-pushes just landed, split by concern: 33b3a662354 → c046803a5c7 is a plain rebase on main (nothing else), and c046803a5c7 → d542b02554f is content only — the fix for Greptile's P1 unvalidated-pointer finding. The second compare link shows just the two VtkGlue files.

[blowekamp]

What are the implications of this for building against the Python Free Thread ABI. Currently Free Threads are not stable and there is expected to be a separate stable ABI for 3.15:
https://peps.python.org/pep-0803/

[dzenanz]

I read this, and the requirements for abi3t are abi3 + no GIL locking. So this PR is a step in the right direction, as best as I can tell.

[hjmjohnson]

I do think this is a mandatory step toward abi3t, but I am not an expert on those details. The primary motivator was to remove complexity in the cmake options, and remove unnecessary dependance on non-abi3 code.

[thewtex]

I don't think we necessarily want to remove support for building without abi3. Linux distributions, etc. may want/need to not use abi3.

[thewtex]

Yes, abi3t will need to be a separate build.

[blowekamp]

I don't think we necessarily want to remove support for building without abi3. Linux distributions, etc. may want/need to not use abi3.

I agree with this. For example for the condo-forge distribution they are still build per python distribution. It is unclear if the SWIG generated code utilizes the extra available interfaces or not in these configurations.

[hjmjohnson]

@thewtex @blowekamp — thanks both; your comments changed the shape of this PR.

It is now only the ITKVtkGlue fix: one commit, seven files, all under Modules/Bridge/VtkGlue/. ITK_USE_PYTHON_LIMITED_API is untouched, keeps its current default, and no Python-discovery or wrapping-macro behaviour changes here. The earlier revision removed that option; that is withdrawn.

The ABI questions you raised are tracked separately in #6757 — free-threaded CPython, abi3t, whether ITK should default to abi3, and alternative binding generators. Python 3.15 makes the actions much more clear about what to do, so it is a roadmap, not a work item.

Because Limited API calls are also valid in a full-API build, one implementation serves both modes — the module does not become abi3-only, and the FATAL_ERROR is removed rather than inverted. Verified on macOS arm64 with VTK 9.6: both ITK_USE_PYTHON_LIMITED_API=ON and =OFF build 8565/8565 targets and pass 177/177 ctest -R Python.

conda-forge: abi3 is compatible with per-version builds, and does not require them to collapse

Checked against conda-forge's own recipe machinery rather than assumed.

conda-forge supports abi3 explicitly, gated per recipe on an is_abi3 selector. When a feedstock opts in, recipe/example-meta.yaml in python-abi3-feedstock sets:

python_version_independent: true   # [is_abi3]
skip: True                         # [is_abi3 and not is_python_min]

plus a python-abi3 host dependency and an abi3audit test. That produces one version-independent artifact built at python_min, instead of one per Python version.

The relevant point for ITK: this is opt-in. A feedstock that keeps its per-version matrix and simply compiles abi3 binaries is perfectly valid — an abi3 extension loads on any interpreter at or above its floor, so a per-cp3XX package containing one is a strict superset of what that package needs. abi3 makes the per-version matrix unnecessary; it does not make it unusable.

For reference, conda-forge/itk-feedstock (ITK 5.4.7) currently builds per version — 18 .ci_support variants, python 3.10/3.11/3.12 × hdf5 1.14.6/2 × linux_64/linux_aarch64/osx_arm64 — and every one is ____cpython, i.e. no free-threaded variants today.

One correction to how this is sometimes stated. Version-specific builds are not needed "for abi3t under 3.13/3.14" — abi3t does not exist there. Per PEP 803 the Stable ABI is simply unavailable on free-threaded builds:

"Extensions will fail to build for the Stable ABI on free-threaded Python (that is, when both Py_LIMITED_API and Py_GIL_DISABLED preprocessor macros are defined)."

So free-threaded 3.13t/3.14t require a build that is neither abi3 nor abi3t, which is exactly why a version-specific path has to stay reachable.

That changes at 3.15, but not to a single build: PEP 803 recommends shipping both, tagged abi3.abi3t, compiled with Py_LIMITED_API and Py_TARGET_ABI3T respectively. So the end state is two ABI variants per platform rather than one per interpreter version. CMake already models the switch — no new find_package component is needed, since USE_SABI picks Py_TARGET_ABI3T over Py_LIMITED_API when Python3_FREE_THREADED is true and the version is 3.15+ (CMake 4.4). Note CMake does not cover the 3.13t/3.14t gap: it still defines Py_LIMITED_API there, so the guard has to be ours. All captured in #6757.

[dzenanz]

I still like this. I don't have time to carefully review.

[hjmjohnson]

@thewtex would you be able to review this PR?

[thewtex]

I defer to VTK developers.

[hjmjohnson]

@dzenanz @thewtex Do you know who uses this mechanism and could review?

The purpose for addressing this conversion was to simplify the interplay between sabi vs non-sabi across Python builds. These changes represent using the stable-abi in such a way that it works both with and without the requirement being set.

[dzenanz]

I think that Slicer is a prominent user of this. Another is probably ITK-SNAP. Maybe MITK too?

I am formally approving this, despite not being entirely certain that this works. It is not very likely we will get another review. I am relying on your testing.

[hjmjohnson]

@dzenanz — you said you liked this but didn't have time to review carefully, and @thewtex deferred to VTK developers. Rather than ask for more review time, I expanded the test coverage and validated the branch on two platforms so the evidence stands on its own.

Every configuration passes, including a pre-PR baseline. Two OSes, two VTK minor versions, both wrapping modes.

Environment	LIMITED_API	C++	Python	Total
Linux x86_64, VTK 9.1, py3.12	OFF	3/3	3/3	8/8
Linux x86_64, VTK 9.1, py3.12	ON	3/3	3/3	8/8
macOS arm64, VTK 9.6.2, py3.13	OFF	3/3	3/3	8/8
macOS arm64, VTK 9.6.2, py3.13	ON	3/3	3/3	8/8
macOS arm64 — main without this PR	baseline	3/3	n/a	3/3

The Linux rows are new — the original description was macOS-only. The branch was also rebased onto current main; git range-diff reports the patch byte-identical across 154 commits of upstream churn, and it now compiles alongside the VTK_FUTURE_CONST change from a53fc61.

New test: PythonVtkGlueTypemapCoverageTest

VtkGlue.i declares six Python typemaps. VtkGlueRoundTripTest exercised two of them, so the new test covers the rest and the cases where a typemap can look correct on the happy path:

Area	Rationale
GetImporter() / GetExporter()	The out vtkImageImport* and out vtkImageExport* typemaps had no Python coverage at all
itk.UC, itk.SS, 3-D itk.F	Existing coverage is float/2-D only; a cast correct there can be wrong elsewhere
Object identity	Two GetOutput() calls must return the same underlying VTK address — the out typemap rebuilds a wrapper from a raw address, so this is the natural failure mode
Lifetime	The wrapper must outlive the producing filter; plus ten repeated round trips
Rejection	vtkPoints, a literal "Addr=0x0" string, and an integer must each be refused rather than reinterpreted as a pointer
Scalar-type mismatch	A VTK_DOUBLE image must be rejected for an itk.F filter, not silently reinterpreted

It deliberately avoids numpy, so it runs wherever ITKVtkGlue is wrapped without requiring ITKBridgeNumPy.

Worth noting for context: Modules/Bridge/VtkGlue/wrapping/test/ did not exist before this PR. There were no Python tests for VtkGlue at all, so the typemaps have never been exercised in ITK's test suite until now.

Artifact audit, re-verified on the rebased branch

_ITKVtkGluePython.abi3.so, limited-API build:

Property	Value
PyVTK* / vtkPythonUtil symbols	0
libvtkWrappingPythonCore linked	0
libpython linked	0
Undefined Py* symbols	72, all Limited API

The OFF build produces _ITKVtkGluePython.so with WrappingPythonCore still linked, as before.

A macOS detour worth recording, since it is not a defect in this PR

The three C++ tests initially segfaulted on macOS. They segfault identically on unpatched main, so I chased it to the end rather than assume.

The cause is Slicer's VTK being a kit build (VTK_ENABLE_KITS=ON, no libvtkCommonCore). A ten-line VTK-only program with no ITK crashes the same way — printing its output, returning from main, then dying in static teardown. Rebuilding VTK non-kit makes both the reproducer and all three ITK tests pass.

So the macOS rows above use a purpose-built VTK 9.6.2: non-kit, rendering enabled, Python-wrapped for the same 3.13.9 interpreter ITK uses, same compiler and deployment target as ITK. Nothing to fix here; recording it so the next person testing VtkGlue against a Slicer VTK does not lose an evening to it.

Separately, this surfaced #6846: ITKVtkGlue cannot configure against a rendering-free VTK because the VTK_RENDERING_BACKEND guard in itk-module-init.cmake tests a VTK 8 variable that VTK 9 never defines, making the non-rendering branch dead code. Unrelated to this PR and out of scope; I will propose the four-line fix after this merges, since both touch the same file.

[dzenanz]

CI doesn't do a Windows Python build. Let me do that locally.

[hjmjohnson]

CI doesn't do a Windows Python build. Let me do that locally.

You need to explicitly request this; it is not enabled by default. And it requires a VTK build with rendering to be available.