ENH: Implement PEP 688 buffer protocol for ITK Python

[Copilot]

Description

Implements PEP 688 buffer protocol support for ITK Images and ImportImageContainers, enabling zero-copy NumPy interoperability in Python 3.12+. Based on #5665 by @blowekamp with fixes for test failures and implementation refinements.

Key changes:

• C++ infrastructure: Added PyBuffer::_GetMemoryViewFromImportImageContainer() with overflow checking
• Python __buffer__() methods: Implemented for Image and ImportImageContainer classes
  • Reuses existing PyBuffer._GetArrayViewFromImage()
  • Extracts component types for composite pixels (RGB, Vector, etc.)
  • Handles shape conversion to NumPy C-order (channels-last)
  • Fallback _get_formatstring() for robustness
• Build system: Wrapping for ImportImageContainer, CMake macro application
• Backward compatibility: __array__() uses buffer protocol for Python 3.12+, falls back to array_from_image() otherwise

Usage:

import itk
import numpy as np

image = itk.Image[itk.UC, 2].New()
image.SetRegions([100, 100])
image.Allocate()

# Python 3.12+: zero-copy conversion via buffer protocol
array = np.asarray(image)  # Direct memory access

# Multi-component images follow channels-last convention
rgb_image = itk.Image[itk.RGBPixel[itk.UC], 2].New()
rgb_array = np.asarray(rgb_image)  # Shape: [height, width, 3]

PR Checklist

• No API changes were made (or the changes have been approved)
• No major design changes were made (or the changes have been approved)
• Added test (or behavior not changed)
• Updated API documentation (or API not changed)
• Added license to new files (if any)
• Added Python wrapping to new files (if any) as described in ITK Software Guide Section 9.5
• Added ITK examples for all new major features (if any)

Related:

• Original PR: WIP: PEP 688 demonstration #5665
• PEP 688: https://peps.python.org/pep-0688/
• SimpleITK implementation: Add PyBuffer interface to Image (PEP 688) and numpy array conversion SimpleITK/SimpleITK#2447

Co-authored-by: Bradley Lowekamp blowekamp@users.noreply.github.com

Original prompt

Take ITK PR #5665 and push it forward in a new PR that you cerate, addressing failing tests and refine the implementation and tests as appropriate.

We are currently getting test failures:

mac

itkImagePythonTest

Traceback (most recent call last):
File "/Users/runner/work/1/s/Modules/Core/Common/wrapping/test/itkImageTest.py", line 37, in
array = np.array(image.buffer())
File "/Users/runner/work/1/s-build/Wrapping/Generators/Python/itk/itkImagePython.py", line 27853, in buffer
memview = memoryview(self.GetPixelContainer())
TypeError: memoryview: a bytes-like object is required, not 'SwigPyObject'
itkTestDriver: Process exited with return value: 1

itkTransformSerializationTest

Traceback (most recent call last):
File "/Users/runner/work/1/s/Modules/Core/Transform/wrapping/test/itkTransformSerializationTest.py", line 167, in
assert np.array_equal(np.array(resampled_image1), np.array(resampled_image2))
AssertionError

PyImageFilterTest

Traceback (most recent call last):
File "/Users/runner/work/1/s/Wrapping/Generators/Python/Tests/PyImageFilterTest.py", line 47, in
assert np.all(np.asarray(output_image) == 42)
AssertionError
itkTestDriver: Process exited with return value: 1

PythonExtrasTest

Traceback (most recent call last):
File "/Users/runner/work/1/s/Wrapping/Generators/Python/Tests/extras.py", line 176, in
assert np.sum(comparison) == 0.0
AssertionError

And similar test failures on Linux.

See also:

• https://peps.python.org/pep-0688/
• @SimpleITK/SimpleITKDOC: improve description of LBFGSERR_ROUNDING_ERROR stopping condition #2447

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[blowekamp]

The original PR, got a buffer from the import image container. This added a daisy chained reference to the object which actually holds the C buffer. This may help keep the Python buffer valid in some cases.

If this is not used, then perhaps the ImportImageContainer buffer interface should be removed. As I recall it was not properly wrapped for complex/composite pixel types.

[hjmjohnson]

Status Update and Analysis (2026-04-07)

Current State

This PR (copilot-generated, based on @blowekamp's #5665) implements PEP 688 buffer protocol support for ITK Python. It has been open since 2025-12-05 with no human review activity. The upstream `main` branch has no PEP 688 support — `buffer` does not exist anywhere in the codebase today.

Relationship to Other PRs

PR	Author	Status	Relationship
#5665	@blowekamp	WIP/Draft	Original exploration — blowekamp stated "I don't have any intention of taking this change further... This PR can be closed without merging"
#5673	copilot	Draft	This PR — built on #5665, added overflow checks, fallback `_get_formatstring`, composite pixel handling
#5653	copilot	Draft	Unrelated — wraps `ObjectToObjectMultiMetricv4` with explicit TVirtualImage (not PEP 688)

Review of @blowekamp's Feedback

blowekamp commented on this PR:

"The original PR got a buffer from the import image container. This added a daisy chained reference to the object which actually holds the C buffer. This may help keep the Python buffer valid in some cases. If this is not used, then perhaps the ImportImageContainer buffer interface should be removed. As I recall it was not properly wrapped for complex/composite pixel types."

This is a valid concern about memory lifetime safety. The key difference:

• WIP: PEP 688 demonstration #5665 (blowekamp): `Image.buffer` calls `memoryview(self.GetPixelContainer())` → gets buffer from `ImportImageContainer`, which maintains a reference chain to the actual C buffer owner
• ENH: Implement PEP 688 buffer protocol for ITK Python #5673 (this PR): `Image.buffer` calls `PyBufferType._GetArrayViewFromImage(self)` → gets buffer directly from the image, bypassing the container reference chain

SimpleITK's implementation (SimpleITK#2447) solved this properly by creating a CPython ImageBuffer class that maintains a reference to the Python Image instance, preventing garbage collection of the underlying image while buffers are active.

Key Issues in This PR

1. Memory safety: The `buffer` implementation uses `_GetArrayViewFromImage` which returns a raw memoryview without holding a Python reference to the image. If the image is garbage collected while the memoryview is alive, it becomes a dangling pointer. blowekamp's approach of going through `ImportImageContainer` was safer.

2. `release_buffer` not implemented: PEP 688 specifies that if `buffer` exists, `release_buffer` should handle cleanup. Neither WIP: PEP 688 demonstration #5665 nor this PR implements it.

3. Composite pixel types: The `_get_formatstring` mapping only handles scalar types and `PF2`/`PF3`. Missing: `RGBPixel`, `RGBAPixel`, `Vector`, `CovariantVector`, `SymmetricSecondRankTensor`, etc.

4. Test quality: Tests use `try/except: pass` patterns that silently swallow failures — not appropriate for regression testing.

5. `ImportImageContainer` wrapping: The new `.wrap` file only wraps scalar types but the `buffer` on `ImportImageContainer` could be called with composite container types.

6. Debug code in WIP: PEP 688 demonstration #5665: The transform serialization test changes in WIP: PEP 688 demonstration #5665 add debug `print` statements and a redundant `field.Update()` call — these are development artifacts.

PEP 688 Requirements (Python 3.12+)

Per PEP 688:

• `buffer(self, flags: int, /) -> memoryview` — creates buffer, must return memoryview
• `release_buffer(self, buffer: memoryview, /)` — optional cleanup
• `memoryview()` constructor invokes `buffer`
• The returned memoryview must match the requested `flags` (from `inspect.BufferFlags`)
• The object must keep its buffer valid as long as any memoryview referencing it exists

Recommendations

1. Do not merge this PR as-is — the memory safety issue needs to be resolved first, following SimpleITK's approach of maintaining proper reference chains.

2. The preferred path forward is a new human-authored PR that:

   • Follows blowekamp's approach (WIP: PEP 688 demonstration #5665) of going through `ImportImageContainer` for reference safety
   • Incorporates SimpleITK's pattern of an intermediary class maintaining image references
   • Properly handles composite pixel types
   • Implements `release_buffer` or documents why it's not needed
   • Has real assertions in tests (no `try/except: pass`)
   • Requires Python 3.12+ (which ITK already effectively requires via ENH: Update to minimum Python support to py310 #6012)

3. Close WIP: PEP 688 demonstration #5665 — author has stated it should be closed

4. This PR (ENH: Implement PEP 688 buffer protocol for ITK Python #5673) can serve as reference material but should not be merged without significant rework addressing the memory safety concern

[dzenanz]

Summary of recommendation: some human should implement this 😄

[hjmjohnson]

Superseded by #6020 which addresses the memory safety concerns raised here. The new implementation uses existing PyBuffer._GetArrayViewFromImage() and pure Python reshaping, with __array_interface__ gated behind an opt-in itk.SIMULATE_PEP688 flag to preserve backward compatibility.