simind-python-connector 2.0.0__py3-none-any.whl → 2.0.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__ = "2.0.0"
+    __version__ = "2.0.2"
 
 
 def __getattr__(name: str) -> Any:
@@ -25,6 +25,7 @@ def __getattr__(name: str) -> Any:
         "converters",
         "core",
         "data",
+        "normalisation",
         "utils",
     }:
         mod = importlib.import_module(f".{name}", __name__)
@@ -37,7 +38,6 @@ def __getattr__(name: str) -> Any:
         return obj
     elif name in {
         "BaseConnector",
-        "NumpyConnector",
         "PyTomographySimindAdaptor",
         "ProjectionResult",
         "RuntimeOperator",
@@ -54,7 +54,6 @@ def __getattr__(name: str) -> Any:
 
 __all__ = [
     "BaseConnector",
-    "NumpyConnector",
     "ProjectionResult",
     "PyTomographySimindAdaptor",
     "RuntimeOperator",
@@ -68,5 +67,6 @@ __all__ = [
     "converters",
     "core",
     "data",
+    "normalisation",
     "utils",
 ]

simind_python_connector/builders/_native.py

@@ -0,0 +1,92 @@
+"""Load SIRF or STIR objects for the builders.
+
+Backends are imported inside each function so importing the builders never
+imports SIRF or STIR.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Optional
+
+import numpy as np
+
+from simind_python_connector.utils import _import_stir_extra
+
+
+def _stir_available() -> bool:
+    """True when STIR Python and its array-conversion module are importable."""
+    try:
+        importlib.import_module("stir")
+        _import_stir_extra()
+    except ImportError:
+        return False
+    return True
+
+
+def resolve_backend(backend: Optional[str]) -> str:
+    """Return "sirf" or "stir". None picks SIRF if importable, else STIR."""
+    if backend is None:
+        try:
+            importlib.import_module("sirf.STIR")
+            return "sirf"
+        except ImportError:
+            pass
+        if _stir_available():
+            return "stir"
+        raise ImportError(
+            "Neither SIRF nor STIR Python found. Install one of: "
+            "SIRF (sirf.STIR) or STIR Python (stir + stir.extra)."
+        )
+    if backend == "sirf":
+        try:
+            importlib.import_module("sirf.STIR")
+        except ImportError as exc:
+            raise ImportError("SIRF is not available") from exc
+        return "sirf"
+    if backend == "stir":
+        if not _stir_available():
+            raise ImportError("STIR Python is not available")
+        return "stir"
+    raise ValueError("backend must be one of: 'sirf', 'stir', or None")
+
+
+def load_image(header_path: str, backend: Optional[str]):
+    """Read an image header as a native SIRF or STIR image."""
+    if resolve_backend(backend) == "sirf":
+        import sirf.STIR
+
+        return sirf.STIR.ImageData(header_path)
+    import stir
+
+    return stir.FloatVoxelsOnCartesianGrid.read_from_file(header_path)
+
+
+def load_acquisition(header_path: str, backend: Optional[str]):
+    """Read projection data as native SIRF or in-memory STIR data.
+
+    STIR's ProjData reads lazily from disk, so it is copied into memory;
+    the builders may delete the files afterwards.
+    """
+    if resolve_backend(backend) == "sirf":
+        import sirf.STIR
+
+        return sirf.STIR.AcquisitionData(header_path)
+    import stir
+
+    return stir.ProjDataInMemory(stir.ProjData.read_from_file(header_path))
+
+
+def refill_acquisition(acquisition, array: np.ndarray, header_path: str, backend: str):
+    """Fill a copy of acquisition with array, write it to header_path, return it."""
+    if backend == "sirf":
+        filled = acquisition.clone()
+        filled.fill(array)
+        filled.write(header_path)
+        return filled
+    import stir
+
+    filled = stir.ProjDataInMemory(acquisition)
+    filled.fill(array.flat)
+    filled.write_to_file(header_path)
+    return filled

simind_python_connector/builders/acquisition_builder.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import tempfile
 import warnings
 from pathlib import Path
 from typing import Literal, Optional
@@ -7,17 +8,7 @@ from typing import Literal, Optional
 import numpy as np
 import pydicom
 
-from simind_python_connector.utils.backend_access import BACKEND_AVAILABLE, BACKENDS
-
-# Conditional import for SIRF types
-from simind_python_connector.utils.import_helpers import get_sirf_types
-from simind_python_connector.utils.io_utils import temporary_directory
-
-
-_, AcquisitionData, SIRF_AVAILABLE = get_sirf_types()
-
-# Unpack interfaces needed by builder
-create_acquisition_data = BACKENDS.factories.create_acquisition_data
+from simind_python_connector.builders import _native
 
 
 class STIRSPECTAcquisitionDataBuilder:
@@ -92,29 +83,31 @@ 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:
+        def _write(base_path: Path):
             header_path = base_path.with_suffix(".hs")
             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:
@@ -123,70 +116,17 @@ class STIRSPECTAcquisitionDataBuilder:
 
             self.pixel_array.tofile(raw_file_path)
 
-            acqdata = self._load_acquisition(str(header_path))
-
-            acqdata = acqdata.clone()
-            acqdata.fill(self.pixel_array)
-            acqdata.write(str(header_path))
-
-            if cleanup:
-                header_path.unlink(missing_ok=True)
-                raw_file_path.unlink(missing_ok=True)
-
-            return self._unwrap_native(acqdata)
-
-        if output_path is None:
-            with temporary_directory() as tmp_dir:
-                return _write(Path(tmp_dir) / "spect_acq", cleanup=False)
-
-        return _write(Path(output_path), cleanup=False)
-
-    def _load_acquisition(self, header_path: str):
-        """Load acquisition data with optional explicit backend selection."""
-        if BACKEND_AVAILABLE and create_acquisition_data is not None:
-            if (
-                self.backend is not None
-                and BACKENDS.detection.set_backend is not None
-                and BACKENDS.detection.get_backend is not None
-            ):
-                previous_backend = None
-                try:
-                    previous_backend = BACKENDS.detection.get_backend()
-                except Exception:
-                    previous_backend = None
-                BACKENDS.detection.set_backend(self.backend)
-                try:
-                    return create_acquisition_data(header_path)
-                finally:
-                    if (
-                        previous_backend is not None
-                        and previous_backend != self.backend
-                    ):
-                        try:
-                            BACKENDS.detection.set_backend(previous_backend)
-                        except Exception:
-                            pass
-            return create_acquisition_data(header_path)
-
-        if self.backend == "stir":
-            raise ImportError(
-                "Requested STIR backend for acquisition loading, but backend wrappers "
-                "are unavailable."
+            backend = _native.resolve_backend(self.backend)
+            acqdata = _native.load_acquisition(str(header_path), backend)
+            return _native.refill_acquisition(
+                acqdata, self.pixel_array, str(header_path), backend
             )
 
-        if SIRF_AVAILABLE:
-            return AcquisitionData(header_path)
-
-        raise ImportError(
-            "Unable to load acquisition data: neither SIRF nor STIR Python "
-            "backends are available."
-        )
+        if output_path is None:
+            with tempfile.TemporaryDirectory() as tmp_dir:
+                return _write(Path(tmp_dir) / "spect_acq")
 
-    @staticmethod
-    def _unwrap_native(obj):
-        """Return native backend object when a wrapper is provided."""
-        native = getattr(obj, "native_object", None)
-        return native if native is not None else obj
+        return _write(Path(output_path))
 
     def build_multi_energy(self, output_path_base="temp", multiple_data_files=True):
         """
@@ -221,35 +161,65 @@ 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})"
+        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"
+                )
+            if not np.issubdtype(window_vector.dtype, np.integer) or not np.all(
+                (window_vector >= 1) & (window_vector <= num_windows)
+            ):
+                raise ValueError(
+                    f"EnergyWindowVector entries must be window numbers "
+                    f"1..{num_windows}"
+                )
+            frames_per_window = [
+                np.flatnonzero(window_vector == idx + 1) for idx in range(num_windows)
+            ]
+            if any(frames.size == 0 for frames in frames_per_window):
+                raise ValueError(
+                    "EnergyWindowVector selects no frames for at least one "
+                    "energy window"
+                )
+        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
             )
-        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)
-
-        # 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 +243,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."
@@ -299,7 +271,29 @@ class STIRSPECTAcquisitionDataBuilder:
         except Exception as e:
             warnings.warn("Error accessing NumberOfFrames from DICOM: " + str(e))
 
-            # Extract energy window information
+        # A malformed EnergyWindowVector must propagate: the broad handler around
+        # the sequence parsing below would otherwise swallow it and leave an
+        # empty energy_windows, silently falling back to the ordinary build.
+        vector = ds.get("EnergyWindowVector")
+        if vector is None:
+            self.energy_window_vector = None
+        else:
+            self.energy_window_vector = []
+            for value in np.atleast_1d(vector):
+                try:
+                    number = float(value)
+                except (TypeError, ValueError) as exc:
+                    raise ValueError(
+                        f"Invalid EnergyWindowVector entry {value!r}"
+                    ) from exc
+                if not number.is_integer():
+                    raise ValueError(
+                        "EnergyWindowVector entries must be whole window "
+                        f"numbers, got {value!r}"
+                    )
+                self.energy_window_vector.append(int(number))
+
+        # Extract energy window information
         try:
             ewi_seq_tag = (0x0054, 0x0012)
             self.energy_windows = []  # list to hold each energy window's info
@@ -348,10 +342,12 @@ class STIRSPECTAcquisitionDataBuilder:
 
                     # Extract basic rotation parameters
                     if "StartAngle" in rot_item:
-                        self.header["start angle"] = str(rot_item.StartAngle)
+                        self.header["start angle"] = str(
+                            round(float(rot_item.StartAngle))
+                        )
                     elif (0x0054, 0x0200) in rot_item:
                         self.header["start angle"] = str(
-                            rot_item[(0x0054, 0x0200)].value
+                            round(float(rot_item[(0x0054, 0x0200)].value))
                         )
 
                     if (0x0018, 0x1242) in rot_item:
@@ -568,7 +564,4 @@ class STIRSPECTAcquisitionDataBuilder:
             raise ValueError(
                 f"pixel data must be 2D or 3D, got {raw_pixel_array.ndim}D"
             )
-        self.pixel_array = np.transpose(raw_pixel_array, (2, 0, 1))
-        # rotate the image by 90 degrees cW in axis 1
-        self.pixel_array = np.rot90(self.pixel_array, 3, axes=(0, 2))
-        self.pixel_array = np.expand_dims(self.pixel_array, axis=0)
+        self.pixel_array = np.transpose(raw_pixel_array, (1, 0, 2))[np.newaxis]

simind_python_connector/builders/image_builder.py

@@ -1,16 +1,12 @@
 from __future__ import annotations
 
+import tempfile
 from pathlib import Path
 from typing import Literal, Optional
 
 import numpy as np
 
-from simind_python_connector.utils.backend_access import BACKEND_AVAILABLE, BACKENDS
-from simind_python_connector.utils.import_helpers import get_sirf_types
-from simind_python_connector.utils.io_utils import temporary_directory
-
-
-ImageData, _, SIRF_AVAILABLE = get_sirf_types()
+from simind_python_connector.builders import _native
 
 
 class STIRSPECTImageDataBuilder:
@@ -100,17 +96,17 @@ class STIRSPECTImageDataBuilder:
 
     def build(self, output_path: Optional[str | Path] = None):
         """
-        Build and return the STIR ImageData object.
-
-        Returns:
-            ImageData: The constructed STIR ImageData object.
+        Build and return the image as a native SIRF or STIR object.
         """
         data = self._resolve_data_array()
 
-        def _write(base_path: Path, cleanup: bool):
+        def _write(base_path: Path):
             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
@@ -123,67 +119,13 @@ class STIRSPECTImageDataBuilder:
                     f.write(temp_str)
 
             data.tofile(raw_path)
-
-            image_data = self._load_image(str(header_path))
-
-            if cleanup:
-                header_path.unlink(missing_ok=True)
-                raw_path.unlink(missing_ok=True)
-            return self._unwrap_native(image_data)
+            return _native.load_image(str(header_path), self.backend)
 
         if output_path is None:
-            with temporary_directory() as tmp_dir:
-                return _write(Path(tmp_dir) / "spect_image", cleanup=False)
-
-        return _write(Path(output_path), cleanup=False)
-
-    def _load_image(self, header_path: str):
-        """Load an image with optional explicit backend selection."""
-        if BACKEND_AVAILABLE and BACKENDS.factories.create_image_data is not None:
-            if (
-                self.backend is not None
-                and BACKENDS.detection.set_backend is not None
-                and BACKENDS.detection.get_backend is not None
-            ):
-                previous_backend = None
-                try:
-                    previous_backend = BACKENDS.detection.get_backend()
-                except Exception:
-                    previous_backend = None
-                BACKENDS.detection.set_backend(self.backend)
-                try:
-                    return BACKENDS.factories.create_image_data(header_path)
-                finally:
-                    if (
-                        previous_backend is not None
-                        and previous_backend != self.backend
-                    ):
-                        try:
-                            BACKENDS.detection.set_backend(previous_backend)
-                        except Exception:
-                            pass
-
-            return BACKENDS.factories.create_image_data(header_path)
-
-        if self.backend == "stir":
-            raise ImportError(
-                "Requested STIR backend for image loading, "
-                "but backend wrappers are unavailable."
-            )
-
-        if SIRF_AVAILABLE:
-            return ImageData(header_path)
-
-        raise ImportError(
-            "Unable to load image data: neither SIRF nor STIR Python "
-            "backends are available."
-        )
+            with tempfile.TemporaryDirectory() as tmp_dir:
+                return _write(Path(tmp_dir) / "spect_image")
 
-    @staticmethod
-    def _unwrap_native(obj):
-        """Return native backend object when a wrapper is provided."""
-        native = getattr(obj, "native_object", None)
-        return native if native is not None else obj
+        return _write(Path(output_path))
 
     @staticmethod
     def create_spect_uniform_image_from_sinogram(sinogram, origin=None):
@@ -202,10 +144,12 @@ class STIRSPECTImageDataBuilder:
             ImageData: A uniform SPECT image initialized with the computed dimensions
                 and voxel sizes.
         """
-        if not SIRF_AVAILABLE:
+        try:
+            import sirf.STIR
+        except ImportError as exc:
             raise ImportError(
                 "create_spect_uniform_image_from_sinogram requires the SIRF backend."
-            )
+            ) from exc
 
         # Create a uniform image from the sinogram and adjust z-voxel size.
         image = sinogram.create_uniform_image(1)
@@ -224,6 +168,6 @@ class STIRSPECTImageDataBuilder:
             origin = (0, 0, 0)
 
         # Initialize a new image with computed dimensions, voxel sizes, and origin.
-        new_image = ImageData()
+        new_image = sirf.STIR.ImageData()
         new_image.initialise(tuple(dims), tuple(voxel_size), tuple(origin))
         return new_image

simind_python_connector/configs/__init__.py

@@ -4,23 +4,29 @@ Packaged scanner presets (YAML or SMC).
 Example
 -------
 >>> from simind_python_connector.configs import get
->>> cfg = get("AnyScan.yaml")          # Path object
+>>> cfg = get("AnyScan.yaml")          # Traversable
 
 >>> from simind_python_connector.core import SimulationConfig
 >>> sim_cfg = SimulationConfig(cfg)    # load file
 """
 
 from importlib import resources as _res
-from pathlib import Path
 from typing import Union
 
 
+try:  # Python 3.11 moved Traversable into importlib.resources.abc
+    from importlib.resources.abc import Traversable
+except ImportError:  # pragma: no cover - Python 3.10
+    from importlib.abc import Traversable
+
+
 __all__ = ["get", "list"]
 
 
-def get(name: str) -> Path:
+def get(name: str) -> Traversable:
     """
-    Return a **Path** to a bundled config file.
+    Return the bundled config file as an importlib.resources Traversable (a Path for
+    normal installs).
 
     Parameters
     ----------

simind_python_connector/connectors/__init__.py

@@ -8,7 +8,6 @@ import importlib
 
 from .base import BaseConnector
 from .python_connector import (
-    NumpyConnector,
     ProjectionResult,
     RuntimeOperator,
     SimindPythonConnector,
@@ -33,7 +32,6 @@ def __getattr__(name):
 
 __all__ = [
     "BaseConnector",
-    "NumpyConnector",
     "PyTomographySimindAdaptor",
     "ProjectionResult",
     "RuntimeOperator",