simind-python-connector 1.1.0__py3-none-any.whl → 1.1.2__py3-none-any.whl

simind_python_connector/__init__.py

@@ -14,7 +14,7 @@ for _dist_name in ("simind-python-connector", __name__):
     except _meta.PackageNotFoundError:
         continue
 else:  # editable / source checkout
-    __version__ = "1.1.0"
+    __version__ = "1.1.2"
 
 
 def __getattr__(name: str) -> Any:

simind_python_connector/backends/__init__.py

@@ -22,6 +22,7 @@ import logging
 import os
 from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 
+from ..utils.import_helpers import _import_stir_extra
 from .base import AcquisitionDataInterface, ImageDataInterface
 
 
@@ -150,7 +151,7 @@ def get_backend() -> str:
     except ImportError:
         try:
             importlib.import_module("stir")
-            importlib.import_module("stirextra")
+            _import_stir_extra()
 
             _backend = "stir"
             logger.info("Auto-detected STIR Python backend")
@@ -159,7 +160,7 @@ def get_backend() -> str:
                 "Neither SIRF nor STIR Python found. "
                 "Please install one of: "
                 "\n  - SIRF (sirf.STIR)"
-                "\n  - STIR Python (stir + stirextra)"
+                "\n  - STIR Python (stir + stir.extra)"
             )
 
     _backend_initialized = True
@@ -190,7 +191,7 @@ def set_backend(backend: Literal["sirf", "stir"]) -> None:
     elif backend == "stir":
         try:
             importlib.import_module("stir")
-            importlib.import_module("stirextra")
+            _import_stir_extra()
         except ImportError:
             raise ImportError("STIR Python is not available")
 

simind_python_connector/backends/sirf_backend.py

@@ -88,7 +88,7 @@ class SirfImageData(ImageDataInterface):
 
     def maximum(self, value: float) -> None:
         """Apply element-wise maximum."""
-        self._obj.maximum(value)
+        self._obj.maximum(value, out=self._obj)
 
     @property
     def native_object(self):
@@ -150,7 +150,7 @@ class SirfImageData(ImageDataInterface):
             SirfImageData: self after modification (for chaining)
         """
         y_obj = y._obj if isinstance(y, SirfImageData) else y
-        self._obj.sapyb(a, y_obj, b)
+        self._obj.sapyb(a, y_obj, b, out=self._obj)
         return self
 
 
@@ -305,5 +305,5 @@ class SirfAcquisitionData(AcquisitionDataInterface):
             SirfAcquisitionData: self after modification (for chaining)
         """
         y_obj = y._obj if isinstance(y, SirfAcquisitionData) else y
-        self._obj.sapyb(a, y_obj, b)
+        self._obj.sapyb(a, y_obj, b, out=self._obj)
         return self

simind_python_connector/backends/stir_backend.py

@@ -12,7 +12,10 @@ import numpy as np
 
 try:
     import stir
-    import stirextra
+
+    from ..utils.import_helpers import _import_stir_extra
+
+    _import_stir_extra()
 
     STIR_AVAILABLE = True
 except ImportError:
@@ -92,7 +95,7 @@ class StirImageData(ImageDataInterface):
     def dimensions(self) -> Tuple[int, int, int]:
         """Get dimensions as (z, y, x)."""
         # Extract from numpy array shape
-        arr = stirextra.to_numpy(self._obj)
+        arr = _import_stir_extra().to_numpy(self._obj)
         # STIR arrays are typically (z, y, x)
         return arr.shape
 
@@ -104,8 +107,8 @@ class StirImageData(ImageDataInterface):
         return (grid_spacing[1], grid_spacing[2], grid_spacing[3])
 
     def as_array(self) -> np.ndarray:
-        """Convert to numpy array using stirextra."""
-        return stirextra.to_numpy(self._obj)
+        """Convert to numpy array using stir.extra."""
+        return _import_stir_extra().to_numpy(self._obj)
 
     def sum(self) -> float:
         """Sum all values."""
@@ -169,19 +172,27 @@ class StirImageData(ImageDataInterface):
             return StirImageData(self._obj / float(other))
 
     def __radd__(self, other):
-        return StirImageData(float(other) + self._obj)
+        if isinstance(other, stir.FloatVoxelsOnCartesianGrid):
+            return StirImageData(other) + self
+        return self + float(other)
 
     def __rsub__(self, other):
-        return StirImageData(float(other) - self._obj)
+        if isinstance(other, stir.FloatVoxelsOnCartesianGrid):
+            return StirImageData(other) - self
+        return (self * -1.0) + float(other)
 
     def __rmul__(self, other):
-        return StirImageData(float(other) * self._obj)
+        if isinstance(other, stir.FloatVoxelsOnCartesianGrid):
+            return StirImageData(other) * self
+        return self * float(other)
 
     def __rtruediv__(self, other):
-        return StirImageData(float(other) / self._obj)
+        if isinstance(other, stir.FloatVoxelsOnCartesianGrid):
+            return StirImageData(other) / self
+        return self.get_uniform_copy(float(other)) / self
 
     def __neg__(self):
-        return StirImageData(-self._obj)
+        return self * -1.0
 
     def sapyb(self, a: float, y: "StirImageData", b: float) -> "StirImageData":
         """Compute self * a + y * b (element-wise), modifying self in place.
@@ -281,12 +292,12 @@ class StirAcquisitionData(AcquisitionDataInterface):
     def dimensions(self) -> Tuple:
         """Get dimensions."""
         # Extract from numpy array
-        arr = stirextra.to_numpy(self._obj)
+        arr = _import_stir_extra().to_numpy(self._obj)
         return arr.shape
 
     def as_array(self) -> np.ndarray:
-        """Convert to numpy array using stirextra."""
-        return stirextra.to_numpy(self._obj)
+        """Convert to numpy array using stir.extra."""
+        return _import_stir_extra().to_numpy(self._obj)
 
     def sum(self) -> float:
         """Sum all values."""
@@ -363,19 +374,27 @@ class StirAcquisitionData(AcquisitionDataInterface):
             return StirAcquisitionData(self._obj / float(other))
 
     def __radd__(self, other):
-        return StirAcquisitionData(float(other) + self._obj)
+        if isinstance(other, stir.ProjData):
+            return StirAcquisitionData(other) + self
+        return self + float(other)
 
     def __rsub__(self, other):
-        return StirAcquisitionData(float(other) - self._obj)
+        if isinstance(other, stir.ProjData):
+            return StirAcquisitionData(other) - self
+        return (self * -1.0) + float(other)
 
     def __rmul__(self, other):
-        return StirAcquisitionData(float(other) * self._obj)
+        if isinstance(other, stir.ProjData):
+            return StirAcquisitionData(other) * self
+        return self * float(other)
 
     def __rtruediv__(self, other):
-        return StirAcquisitionData(float(other) / self._obj)
+        if isinstance(other, stir.ProjData):
+            return StirAcquisitionData(other) / self
+        return self.get_uniform_copy(float(other)) / self
 
     def __neg__(self):
-        return StirAcquisitionData(-self._obj)
+        return self * -1.0
 
     def sapyb(
         self, a: float, y: "StirAcquisitionData", b: float

simind_python_connector/builders/acquisition_builder.py

@@ -92,22 +92,22 @@ class STIRSPECTAcquisitionDataBuilder:
         num_projections = int(self.header.get("!number of projections", 1))
         if self.pixel_array is None:
             self.pixel_array = np.zeros(
-                (1, matrix_size_1, num_projections, matrix_size_2), dtype=np.float32
+                (1, matrix_size_2, num_projections, matrix_size_1), dtype=np.float32
             )
         else:
             self.pixel_array = np.array(self.pixel_array, dtype=np.float32)
 
         expected_shape = (
             1,
-            matrix_size_1,
-            num_projections,
             matrix_size_2,
+            num_projections,
+            matrix_size_1,
         )
         if self.pixel_array.shape != expected_shape:
             raise ValueError(
                 f"pixel array shape {self.pixel_array.shape} does not match "
                 f"header dimensions {expected_shape} "
-                "(tof, bin, view, axial)"
+                "(tof, axial, view, bin)"
             )
 
         def _write(base_path: Path, cleanup: bool) -> AcquisitionData:
@@ -115,6 +115,8 @@ class STIRSPECTAcquisitionDataBuilder:
             raw_file_path = base_path.with_suffix(".s")
 
             self.header["name of data file"] = raw_file_path.name
+            # Keys added since an earlier build must come before the terminator.
+            self.header.pop("!END OF INTERFILE", None)
             self.header["!END OF INTERFILE"] = ""
 
             with open(header_path, "w") as f:
@@ -221,35 +223,54 @@ class STIRSPECTAcquisitionDataBuilder:
                 f"pixel array shape {self.pixel_array.shape} does not match "
                 f"declared {total_projections} projections"
             )
-        if total_projections % num_windows != 0:
-            raise ValueError(
-                f"Number of projections ({total_projections}) must be divisible "
-                f"by the number of energy windows ({num_windows})"
-            )
-        projections_per_window = total_projections // num_windows
 
-        # number of projections needs dividing by number of energy windows
-        self.header["!number of projections"] = str(projections_per_window)
+        window_vector = getattr(self, "energy_window_vector", None)
+        if window_vector is not None:
+            window_vector = np.asarray(window_vector)
+            if len(window_vector) != total_projections:
+                raise ValueError(
+                    f"EnergyWindowVector has {len(window_vector)} entries for "
+                    f"{total_projections} frames"
+                )
+            frames_per_window = [
+                np.flatnonzero(window_vector == idx + 1) for idx in range(num_windows)
+            ]
+        else:
+            if total_projections % num_windows != 0:
+                raise ValueError(
+                    f"Number of projections ({total_projections}) must be divisible "
+                    f"by the number of energy windows ({num_windows})"
+                )
+            # Without a window vector, assume one contiguous block per window.
+            frames_per_window = np.array_split(
+                np.arange(total_projections), num_windows
+            )
 
-        # split pixel_array into energy windows along 3rd axis
         original_pixel_array = self.pixel_array
+        original_header = dict(self.header)
+        duration = original_header.get("!image duration (sec)[1]")
         try:
-            pixel_array_list = np.array_split(original_pixel_array, num_windows, axis=2)
-
             acqdata_list = []
             for idx, ew in enumerate(self.energy_windows):
-                # Update header for this energy window.
+                frames = frames_per_window[idx]
+                self.header["!number of projections"] = str(len(frames))
+                self.header["!number of energy windows"] = "1"
                 self.header["energy window lower level[1]"] = ew["lower"]
                 self.header["energy window upper level[1]"] = ew["upper"]
-                suffix = f"_ew{idx + 1}"
-                output_path = output_path_base + suffix
-                self.pixel_array = pixel_array_list[idx]
+                if duration is not None:
+                    # Windows are acquired simultaneously, so each output
+                    # covers only its own frames.
+                    self.header["!image duration (sec)[1]"] = (
+                        f"{float(duration) * len(frames) / total_projections:g}"
+                    )
+                output_path = output_path_base + f"_ew{idx + 1}"
+                self.pixel_array = original_pixel_array[:, :, frames, :]
                 acqdata = self.build(output_path=output_path)
                 acqdata_list.append(acqdata)
             return acqdata_list
         finally:
             self.pixel_array = original_pixel_array
-            self.header["!number of projections"] = str(total_projections)
+            self.header = original_header
 
     def update_header_from_dicom(self, dicom_filepath):
         """
@@ -273,16 +294,18 @@ class STIRSPECTAcquisitionDataBuilder:
                 "Modality not found in DICOM. Retaining default '!imaging modality'."
             )
         try:
-            self.header["!matrix size [1]"] = str(ds.Rows)
-            self.header["!matrix size [2]"] = str(ds.Columns)
+            self.header["!matrix size [1]"] = str(ds.Columns)
+            self.header["!matrix size [2]"] = str(ds.Rows)
         except AttributeError:
             warnings.warn(
                 "Rows/Columns not found in DICOM. Retaining default matrix sizes."
             )
         try:
             pixel_spacing = ds.PixelSpacing
-            self.header["scaling factor (mm/pixel) [1]"] = str(pixel_spacing[0])
-            self.header["scaling factor (mm/pixel) [2]"] = str(pixel_spacing[1])
+            # DICOM PixelSpacing is [row spacing, column spacing]; Interfile
+            # [1] is the column/bin axis and [2] the row/axial axis.
+            self.header["scaling factor (mm/pixel) [1]"] = str(pixel_spacing[1])
+            self.header["scaling factor (mm/pixel) [2]"] = str(pixel_spacing[0])
         except AttributeError:
             warnings.warn(
                 "PixelSpacing not found in DICOM. Retaining default scaling factors."
@@ -303,6 +326,10 @@ class STIRSPECTAcquisitionDataBuilder:
         try:
             ewi_seq_tag = (0x0054, 0x0012)
             self.energy_windows = []  # list to hold each energy window's info
+            vector = ds.get("EnergyWindowVector")
+            self.energy_window_vector = (
+                [int(v) for v in np.atleast_1d(vector)] if vector is not None else None
+            )
             if ewi_seq_tag in ds:
                 ewi_seq = ds[ewi_seq_tag].value
                 for ewi_item in ewi_seq:

simind_python_connector/builders/image_builder.py

@@ -111,6 +111,9 @@ class STIRSPECTImageDataBuilder:
             header_path = base_path.with_suffix(".hv")
             raw_path = base_path.with_suffix(".v")
             self.header["!name of data file"] = raw_path.name
+            # Keys added after construction must come before the terminator.
+            self.header.pop("!END OF INTERFILE", None)
+            self.header["!END OF INTERFILE"] = ""
 
             with open(header_path, "w") as f:
                 line = 0

simind_python_connector/connectors/_spacing.py

@@ -2,74 +2,198 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Optional
+
+import numpy as np
+
+
+def normalize_voxel_size_mm(voxel_size_mm: Any) -> tuple[float, float, float]:
+    """Return positive voxel spacing in canonical ``(z, y, x)`` order."""
+    try:
+        values = np.asarray(voxel_size_mm, dtype=float)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            "voxel_size_mm must be a scalar or a (z, y, x) sequence"
+        ) from exc
+    if values.ndim == 0:
+        z = y = x = float(values)
+    elif values.ndim == 1 and values.size == 3:
+        z, y, x = (float(value) for value in values)
+    else:
+        raise ValueError("voxel_size_mm must be a scalar or a (z, y, x) sequence")
+    if not np.isfinite((z, y, x)).all() or min(z, y, x) <= 0:
+        raise ValueError(
+            "voxel_size_mm must be > 0 and all spacing values must be finite"
+        )
+    if abs(y - x) > 1e-3:
+        raise ValueError(
+            f"SIMIND requires square in-plane voxels; got y={y} mm and x={x} mm"
+        )
+    return z, y, x
 
 
 def _call_or_value(value: Any) -> Any:
     return value() if callable(value) else value
 
 
-def _voxel_size_from_spacing(spacing: Any) -> float | None:
+def _spacing_zyx(spacing: Any) -> Optional[tuple[float, float, float]]:
     try:
         values = tuple(float(v) for v in spacing)
     except Exception:
         values = ()
 
-    if values:
-        if len(values) >= 4:
-            # Raw STIR-style coordinate sequence: (unused, z, y, x)
-            return float(values[1])
-        if len(values) == 3:
-            # Public (z, y, x) convention
-            return float(values[0])
+    if len(values) >= 4:
+        # Raw STIR-style coordinate sequence: (unused, z, y, x)
+        return values[1], values[2], values[3]
+    if len(values) == 3:
+        # Public (z, y, x) convention
+        return values[0], values[1], values[2]
 
-    if hasattr(spacing, "z"):
+    if all(hasattr(spacing, axis) for axis in ("z", "y", "x")):
         try:
-            return float(_call_or_value(getattr(spacing, "z")))
+            z, y, x = (float(_call_or_value(getattr(spacing, axis))) for axis in "zyx")
+            return z, y, x
         except Exception:
             pass
 
-    if hasattr(spacing, "at"):
-        for index in (1, 2, 3):
-            try:
-                return float(spacing.at(index))
-            except Exception:
-                continue
-
-    for index in (1, 2, 3):
+    # Non-iterable STIR coordinates index (z, y, x) from 1.
+    for accessor in (
+        getattr(spacing, "at", None),
+        getattr(spacing, "__getitem__", None),
+    ):
+        if accessor is None:
+            continue
         try:
-            return float(spacing[index])
+            z, y, x = (float(accessor(index)) for index in (1, 2, 3))
+            return z, y, x
         except Exception:
             continue
 
     return None
 
 
-def extract_voxel_size_mm(image: Any, backend_name: str) -> float:
-    """Extract z voxel spacing in mm from backend image metadata.
+def extract_voxel_spacing_mm(
+    image: Any, backend_name: str
+) -> tuple[float, float, float]:
+    """Return voxel spacing in mm from backend image metadata, in (z, y, x).
 
-    Backend images report ``voxel_sizes()`` in ``(z, y, x)`` order, so the
-    first element is the z spacing.
+    SIMIND supports axial spacing distinct from the in-plane image spacing;
+    the in-plane dimensions must remain square.
     """
+    zyx = None
     if hasattr(image, "voxel_sizes"):
-        voxel_sizes = image.voxel_sizes()
         try:
+            voxel_sizes = tuple(float(v) for v in image.voxel_sizes())
             if len(voxel_sizes) >= 3:
-                return float(voxel_sizes[0])
+                zyx = voxel_sizes[:3]
         except Exception:
             pass
 
-    if hasattr(image, "get_grid_spacing"):
-        voxel_size_mm = _voxel_size_from_spacing(image.get_grid_spacing())
-        if voxel_size_mm is not None:
-            return voxel_size_mm
+    if zyx is None and hasattr(image, "get_grid_spacing"):
+        zyx = _spacing_zyx(image.get_grid_spacing())
+        if zyx is None:
+            raise ValueError(
+                f"Unable to read voxel spacing from {backend_name} get_grid_spacing()."
+            )
+
+    if zyx is None:
         raise ValueError(
-            f"Unable to read voxel spacing from {backend_name} get_grid_spacing()."
+            f"{backend_name} source object must expose voxel_sizes() or "
+            "get_grid_spacing()."
         )
+    try:
+        return normalize_voxel_size_mm(zyx)
+    except ValueError as exc:
+        raise ValueError(
+            f"{backend_name} voxel spacing is invalid (z, y, x) = {tuple(zyx)} mm: "
+            f"{exc}"
+        ) from exc
+
+
+def extract_voxel_size_mm(image: Any, backend_name: str) -> float:
+    """Return a scalar for legacy callers when backend voxels are cubic."""
+    z, y, x = extract_voxel_spacing_mm(image, backend_name)
+    if max(z, y, x) - min(z, y, x) > 1e-3:
+        raise ValueError(
+            f"{backend_name} images must have cubic voxels; got (z, y, x) = "
+            f"{(z, y, x)} mm"
+        )
+    return z
+
+
+def _numeric_array(value: Any) -> Optional[np.ndarray]:
+    try:
+        return np.asarray(value, dtype=float).reshape(-1)
+    except (TypeError, ValueError):
+        return None
+
+
+def _spatial_geometry(image: Any) -> Optional[tuple[Any, ...]]:
+    """Read native geometry where the backend exposes a documented API.
+
+    SIRF's ImageData returns a GeometricalInfo from
+    ``get_geometrical_info()``, with offset, spacing, and direction-matrix getters.
+    STIR's VoxelsOnCartesianGrid exposes origin and signed grid spacing.
+    """
+    native_object = getattr(image, "native_object", image)
+    image = native_object() if callable(native_object) else native_object
+
+    get_geometrical_info = getattr(image, "get_geometrical_info", None)
+    if callable(get_geometrical_info):
+        info = get_geometrical_info()
+        getters = ("get_offset", "get_spacing", "get_direction_matrix")
+        if not all(callable(getattr(info, name, None)) for name in getters):
+            raise ValueError(
+                "Unable to read SIRF geometry from get_geometrical_info()."
+            )
+        arrays = [_numeric_array(getattr(info, name)()) for name in getters]
+        if any(array is None or not array.size for array in arrays):
+            raise ValueError(
+                "Unable to read SIRF geometry from get_geometrical_info()."
+            )
+        if any(not np.isfinite(array).all() for array in arrays if array is not None):
+            raise ValueError("SIRF geometry values must be finite.")
+        return ("sirf", np.concatenate(arrays))
+
+    get_origin = getattr(image, "get_origin", None)
+    get_grid_spacing = getattr(image, "get_grid_spacing", None)
+    if callable(get_origin) and callable(get_grid_spacing):
+        origin = _spacing_zyx(get_origin())
+        spacing = _spacing_zyx(get_grid_spacing())
+        if origin is None or spacing is None:
+            return None
+        minimum_indices = []
+        for axis in "zyx":
+            getter = getattr(image, f"get_min_{axis}", None)
+            if not callable(getter):
+                return None
+            minimum_indices.append(float(getter()))
+        physical_start = np.asarray(origin) + np.asarray(minimum_indices) * np.asarray(
+            spacing
+        )
+        return (
+            "stir",
+            physical_start,
+        )
+    return None
+
 
-    raise ValueError(
-        f"{backend_name} source object must expose voxel_sizes() or get_grid_spacing()."
+def same_spatial_geometry(source: Any, mu_map: Any) -> bool:
+    """Compare origins, spacing, and axis directions when both APIs expose them."""
+    source_geometry = _spatial_geometry(source)
+    mu_geometry = _spatial_geometry(mu_map)
+    if source_geometry is None and mu_geometry is None:
+        return True
+    if source_geometry is None or mu_geometry is None:
+        return False
+    return source_geometry[0] == mu_geometry[0] and np.allclose(
+        source_geometry[1], mu_geometry[1], rtol=0.0, atol=1e-3
     )
 
 
-__all__ = ["extract_voxel_size_mm"]
+__all__ = [
+    "extract_voxel_size_mm",
+    "extract_voxel_spacing_mm",
+    "normalize_voxel_size_mm",
+    "same_spatial_geometry",
+]