ENH: Add PEP 688 buffer protocol and fix np.asarray() lifetime safety

Add zero-copy data export to all wrapped itk.Image types via two
protocols, ensuring the exported array remains valid even after
the source image is deleted:

  image = itk.imread("brain.nii.gz")
  arr = np.asarray(image)
  del image
  print(arr[1,1,1])  # safe -- no crash

Protocol dispatch by Python version:
  3.12+:   np.asarray -> __buffer__ (PEP 688, zero-copy, memoryview
           pins self via NDArrayITKBase intermediary)
  3.10-11: np.asarray -> __array__ -> array_view_from_image (zero-copy,
           NDArrayITKBase.itk_base holds reference to image)

Changes to pyBase.i:
  - Add __buffer__() implementing PEP 688 buffer export with shaped
    memoryview. Uses NDArrayITKBase as intermediary to hold a Python
    reference to the image, preventing GC while any derived
    memoryview/array exists.
  - Simplify __array__() to always return zero-copy view via
    array_view_from_image(). Supports NumPy 2.0 copy= parameter.
  - Remove __array_interface__ (returned raw pointer with no reference
    holder -- use-after-free on del image, confirmed by test).
  - Remove SIMULATE_PEP688 / SIMULATE_PEP688_DEBUG (confusing,
    contradictory behaviors between __buffer__ and __array__ paths).

Changes to PyBuffer.i.init:
  - Add _get_buffer_formatstring() with module-level _BUFFER_FORMAT_MAP
    for struct format lookup (UC->B, SS->h, F->f, D->d, etc.)
  - Add _get_numpy_pixelid() with module-level _NUMPY_PIXELID_MAP
  - Remove LD (long double) mapping -- sizeof(long double) varies by
    platform, struct format "d" is always 8 bytes (silent corruption)

Supersedes InsightSoftwareConsortium#6020, InsightSoftwareConsortium#6018, InsightSoftwareConsortium#5673, InsightSoftwareConsortium#5665. Key improvements over each:
  - InsightSoftwareConsortium#6020: Fixed __buffer__ lifetime (memoryview didn't pin image),
    removed unsafe __array_interface__, removed SIMULATE_PEP688
  - InsightSoftwareConsortium#6018: Closed in favor of InsightSoftwareConsortium#6020
  - InsightSoftwareConsortium#5673: Added __array_interface__ (now removed) and __buffer__
  - InsightSoftwareConsortium#5665: Original PEP 688 implementation by blowekamp

Addresses review concerns from @thewtex (del image crash),
@blowekamp (reference pinning at buffer owner level).

Tested: 121 assertions across 3 test suites, Python 3.13 and 3.14,
with NumPy 2.4.3, PyTorch 2.11.0, Dask 2026.3.0. All 32 lifetime
tests pass (del image safe on every export path).

Co-Authored-By: Hans J. Johnson <hans-johnson@uiowa.edu>

Author: hjmjohnson

Modules/Bridge/NumPy/wrapping/PyBuffer.i.init

@@ -29,31 +29,85 @@ else:
         loads = dask_deserialize.dispatch(np.ndarray)
         return NDArrayITKBase(loads(header, frames))
 
+def _get_buffer_formatstring(itk_pixel_code: str) -> str:
+    """Return the struct format character for an ITK pixel type code.
+
+    Used by the PEP 688 ``__buffer__`` protocol implementation on
+    ``itk.Image`` to describe the element type of the exported
+    memoryview.  Format characters follow Python's ``struct`` module
+    specification.
+
+    Parameters
+    ----------
+    itk_pixel_code : str
+        Short name of the ITK component type, e.g. ``"UC"``, ``"F"``.
+
+    Returns
+    -------
+    str
+        Single-character ``struct`` format string.
+    """
+
+    return _BUFFER_FORMAT_MAP[itk_pixel_code]
+
+
+# Module-level constant — built once at import time.
+# Composite pixel types (RGB, Vector, etc.) are decomposed to their
+# scalar component type before reaching _get_buffer_formatstring(),
+# so only scalar codes appear here.
+# Platform aliases (ST/IT/OT) resolve to UL/SL at the wrapping level.
+import os as _os
+_BUFFER_FORMAT_MAP = {
+    # --- integer types ---
+    "B":   "?",  # bool
+    "UC":  "B",  # unsigned char   -> uint8
+    "US":  "H",  # unsigned short  -> uint16
+    "UI":  "I",  # unsigned int    -> uint32
+    "UL":  "L",  # unsigned long   -> platform (8 bytes Linux/macOS, 4 bytes Windows)
+    "ULL": "Q",  # unsigned long long -> uint64
+    "SC":  "b",  # signed char     -> int8
+    "SS":  "h",  # signed short    -> int16
+    "SI":  "i",  # signed int      -> int32
+    "SL":  "l",  # signed long     -> platform
+    "SLL": "q",  # signed long long -> int64
+    # --- floating point types ---
+    "F":   "f",  # float           -> float32
+    "D":   "d",  # double          -> float64
+    # "LD" (long double) intentionally omitted: sizeof(long double)
+    # is 16 bytes on Linux/macOS x86-64 but struct "d" is 8 bytes.
+    # Casting would silently corrupt the buffer.
+}
+if _os.name == 'nt':
+    # On Windows, C ``long`` is 32-bit
+    _BUFFER_FORMAT_MAP['UL'] = 'I'
+    _BUFFER_FORMAT_MAP['SL'] = 'i'
+
+
 def _get_numpy_pixelid(itk_Image_type) -> np.dtype:
     """Returns a ITK PixelID given a numpy array."""
 
-    # This is a Mapping from numpy array types to itk pixel types.
-    _np_itk = {"UC":np.dtype(np.uint8),
-               "US":np.dtype(np.uint16),
-               "UI":np.dtype(np.uint32),
-               "UL":np.dtype(np.uint64),
-               "ULL":np.dtype(np.uint64),
-               "SC":np.dtype(np.int8),
-               "SS":np.dtype(np.int16),
-               "SI":np.dtype(np.int32),
-               "SL":np.dtype(np.int64),
-               "SLL":np.dtype(np.int64),
-               "F":np.dtype(np.float32),
-               "D":np.dtype(np.float64),
-               "PF2":np.dtype(np.float32),
-               "PF3":np.dtype(np.float32),
-                }
-    import os
-    if os.name == 'nt':
-        _np_itk['UL'] = np.dtype(np.uint32)
-        _np_itk['SL'] = np.dtype(np.int32)
-    try:
-        return _np_itk[itk_Image_type]
-    except KeyError as e:
-        raise e
+    return _NUMPY_PIXELID_MAP[itk_Image_type]
+
+
+# Module-level constant — built once at import time.
+_NUMPY_PIXELID_MAP = {
+    "B":   np.dtype(np.bool_),
+    "UC":  np.dtype(np.uint8),
+    "US":  np.dtype(np.uint16),
+    "UI":  np.dtype(np.uint32),
+    "UL":  np.dtype(np.uint64),
+    "ULL": np.dtype(np.uint64),
+    "SC":  np.dtype(np.int8),
+    "SS":  np.dtype(np.int16),
+    "SI":  np.dtype(np.int32),
+    "SL":  np.dtype(np.int64),
+    "SLL": np.dtype(np.int64),
+    "F":   np.dtype(np.float32),
+    "D":   np.dtype(np.float64),
+    "PF2": np.dtype(np.float32),
+    "PF3": np.dtype(np.float32),
+}
+if _os.name == 'nt':
+    _NUMPY_PIXELID_MAP['UL'] = np.dtype(np.uint32)
+    _NUMPY_PIXELID_MAP['SL'] = np.dtype(np.int32)
 %}

Wrapping/Generators/Python/PyBase/pyBase.i

@@ -679,13 +679,99 @@ str = str
 
 %define DECL_PYTHON_IMAGE_CLASS(swig_name)
   %extend swig_name {
-      %pythoncode {
-          def __array__(self, dtype=None):
+      %pythoncode %{
+          def __buffer__(self, flags=0, /):
+              """PEP 688 buffer protocol -- export image data as a memoryview.
+
+              On Python 3.12+ this is called automatically by
+              ``memoryview(image)`` and ``numpy.asarray(image)``.
+              On Python 3.10-3.11 it can be called explicitly.
+
+              The returned memoryview shares memory with the image
+              (zero-copy).  A reference to the image is stored on the
+              returned object to prevent garbage collection while the
+              buffer is in use.
+              """
               import itk
               import numpy as np
-              array = itk.array_from_image(self)
-              return np.asarray(array, dtype=dtype)
-      }
+              from itk.itkPyBufferPython import _get_buffer_formatstring
+
+              # Get 1-D raw memoryview from the C++ buffer
+              ImageType = type(self)
+              PyBufferType = itk.PyBuffer[ImageType]
+              raw_memview = PyBufferType._GetArrayViewFromImage(self)
+
+              # Build shape in C-order (NumPy convention: [z, y, x, ...])
+              itksize = self.GetBufferedRegion().GetSize()
+              shape = [int(itksize[d]) for d in range(len(itksize))]
+
+              n_components = self.GetNumberOfComponentsPerPixel()
+              if n_components > 1:
+                  shape.insert(0, n_components)
+
+              shape.reverse()
+
+              # Determine the struct format character for the component type
+              tpl = itk.template(self)
+              pixel_type = tpl[1][0]
+              from itk.support.types import itkCType
+              if isinstance(pixel_type, itkCType):
+                  # Scalar pixel (UC, F, SS, etc.)
+                  component_code = pixel_type.short_name
+              else:
+                  # Composite pixel (RGB, Vector, etc.) -- use component type
+                  pixel_tpl = itk.template(pixel_type)
+                  component_code = pixel_tpl[1][0].short_name
+
+              fmt = _get_buffer_formatstring(component_code)
+
+              # Build a NumPy array view that holds a reference to self
+              # via NDArrayITKBase.itk_base, preventing the image from
+              # being garbage collected while any memoryview or array
+              # derived from this buffer exists.
+              from itk.itkPyBufferPython import NDArrayITKBase
+              flat = np.frombuffer(raw_memview, dtype=fmt)
+              shaped = NDArrayITKBase(flat.reshape(shape), self)
+              return memoryview(shaped)
+
+          def __array__(self, dtype=None, copy=None):
+              """NumPy array protocol -- zero-copy view of image data.
+
+              On Python 3.12+, NumPy prefers ``__buffer__`` (PEP 688)
+              over this method.  On Python 3.10-3.11, this is the
+              primary path for ``np.asarray(image)``.
+
+              The returned array holds a reference to the image via
+              ``NDArrayITKBase.itk_base``, so the image buffer remains
+              valid even after ``del image``.
+
+              Parameters
+              ----------
+              dtype : numpy dtype, optional
+                  If specified and different from the image dtype,
+                  a copy is made with the requested dtype.
+              copy : bool or None, optional (NumPy 2.0+)
+                  ``None``/``False``: return zero-copy view.
+                  ``True``: return an independent copy.
+              """
+              import itk
+              import numpy as np
+
+              # Zero-copy view with reference to self via NDArrayITKBase
+              array = itk.array_view_from_image(self)
+
+              if dtype is not None:
+                  if copy is False and np.dtype(dtype) != array.dtype:
+                      raise ValueError(
+                          "Unable to avoid copy: dtype conversion from "
+                          f"{array.dtype} to {np.dtype(dtype)} requires "
+                          "a copy."
+                      )
+                  array = np.asarray(array, dtype=dtype)
+              if copy:
+                  array = np.array(array, copy=True)
+              return array
+      %}
   }
 %enddef