simind-python-connector 1.2.0__py3-none-any.whl → 2.0.1__py3-none-any.whl

simind_python_connector/__init__.py

@@ -3,9 +3,18 @@ simind-python-connector connector/adaptor API.
 """
 
 import importlib
+from importlib import metadata as _meta
 from typing import Any
 
-from ._version import __version__ as __version__
+
+for _dist_name in ("simind-python-connector", __name__):
+    try:  # installed (pip/poetry)
+        __version__ = _meta.version(_dist_name)
+        break
+    except _meta.PackageNotFoundError:
+        continue
+else:  # editable / source checkout
+    __version__ = "2.0.1"
 
 
 def __getattr__(name: str) -> Any:
@@ -16,6 +25,7 @@ def __getattr__(name: str) -> Any:
         "converters",
         "core",
         "data",
+        "normalisation",
         "utils",
     }:
         mod = importlib.import_module(f".{name}", __name__)
@@ -28,7 +38,6 @@ def __getattr__(name: str) -> Any:
         return obj
     elif name in {
         "BaseConnector",
-        "NumpyConnector",
         "PyTomographySimindAdaptor",
         "ProjectionResult",
         "RuntimeOperator",
@@ -45,13 +54,12 @@ def __getattr__(name: str) -> Any:
 
 __all__ = [
     "BaseConnector",
-    "NumpyConnector",
     "ProjectionResult",
     "PyTomographySimindAdaptor",
     "RuntimeOperator",
+    "SirfSimindAdaptor",
     "SimindPythonConnector",
     "SimulationConfig",
-    "SirfSimindAdaptor",
     "StirSimindAdaptor",
     "builders",
     "configs",
@@ -59,5 +67,6 @@ __all__ = [
     "converters",
     "core",
     "data",
+    "normalisation",
     "utils",
 ]

simind_python_connector/builders/__init__.py

@@ -9,10 +9,10 @@ import importlib
 def __getattr__(name):
     if name == "STIRSPECTAcquisitionDataBuilder":
         mod = importlib.import_module(".acquisition_builder", __name__)
-        return mod.STIRSPECTAcquisitionDataBuilder
+        return getattr(mod, "STIRSPECTAcquisitionDataBuilder")
     elif name == "STIRSPECTImageDataBuilder":
         mod = importlib.import_module(".image_builder", __name__)
-        return mod.STIRSPECTImageDataBuilder
+        return getattr(mod, "STIRSPECTImageDataBuilder")
     raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
 
 

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,23 +1,14 @@
 from __future__ import annotations
 
+import tempfile
 import warnings
 from pathlib import Path
-from typing import Literal
+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:
@@ -32,7 +23,7 @@ class STIRSPECTAcquisitionDataBuilder:
     def __init__(
         self,
         header_overrides=None,
-        backend: Literal["sirf", "stir"] | None = None,
+        backend: Optional[Literal["sirf", "stir"]] = None,
     ):
         if backend is not None and backend not in {"sirf", "stir"}:
             raise ValueError("backend must be one of: 'sirf', 'stir', or None")
@@ -80,7 +71,7 @@ class STIRSPECTAcquisitionDataBuilder:
         """
         self.header.update(updates)
 
-    def build(self, output_path: str | Path | None = None):
+    def build(self, output_path: Optional[str | Path] = None):
         """
         Build and return the STIR AcquisitionData object.
         """
@@ -110,7 +101,7 @@ class STIRSPECTAcquisitionDataBuilder:
                 "(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")
 
@@ -120,76 +111,22 @@ class STIRSPECTAcquisitionDataBuilder:
             self.header["!END OF INTERFILE"] = ""
 
             with open(header_path, "w") as f:
-                f.writelines(
-                    f"{key} := {value}\n" for key, value in self.header.items()
-                )
+                for key, value in self.header.items():
+                    f.write(f"{key} := {value}\n")
 
             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):
         """
@@ -224,7 +161,6 @@ class STIRSPECTAcquisitionDataBuilder:
                 f"pixel array shape {self.pixel_array.shape} does not match "
                 f"declared {total_projections} projections"
             )
-
         window_vector = getattr(self, "energy_window_vector", None)
         if window_vector is not None:
             window_vector = np.asarray(window_vector)
@@ -233,9 +169,21 @@ class STIRSPECTAcquisitionDataBuilder:
                     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(
@@ -323,14 +271,32 @@ 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
-            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:
@@ -376,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:
@@ -454,9 +422,17 @@ class STIRSPECTAcquisitionDataBuilder:
                                 self.header.pop("Radius", None)
 
                             radial_processed = True
+                            print(
+                                f"Debug: Direct radii processed - all same: "
+                                f"{len(set(rp_list)) == 1}, values: {rp_list[:5]}..."
+                            )
+
                         else:
                             # Single value
                             mean_radial_position = float(rp_val)
+                            print(
+                                f"Debug: Single radial position: {mean_radial_position}"
+                            )
                     else:
                         warnings.warn(
                             "Mean radial position not found in Rotation Information "
@@ -467,6 +443,11 @@ class STIRSPECTAcquisitionDataBuilder:
                     # Only process tomo view offset if we haven't already processed
                     # direct radii
                     if not radial_processed:
+                        print(
+                            "Debug: Processing tomo view offset since direct radii "
+                            "not processed"
+                        )
+
                         # Process Detector Information Sequence & Tomo View Offset
                         det_info_seq_tag = (0x0055, 0x1022)
                         tomo_view_offset_tag = (0x0013, 0x101E)
@@ -520,6 +501,11 @@ class STIRSPECTAcquisitionDataBuilder:
                         else:
                             self.header["Radius"] = str(mean_radial_position)
                             self.header["orbit"] = "circular"
+                    else:
+                        print(
+                            "Debug: Skipping tomo view offset processing - direct "
+                            "radii already processed"
+                        )
 
                 else:
                     warnings.warn("Rotation Information Sequence is empty.")
@@ -534,11 +520,11 @@ class STIRSPECTAcquisitionDataBuilder:
         try:
             self.header[";#acquisition date"] = ds.AcquisitionDate
         except AttributeError:
-            warnings.warn("AcquisitionDate not found in DICOM.")
+            warnings.warn("StudyDate not found in DICOM.")
         try:
             self.header[";#acquisition time"] = ds.AcquisitionTime
         except AttributeError:
-            warnings.warn("AcquisitionTime not found in DICOM.")
+            warnings.warn("StudyTime not found in DICOM.")
         try:
             acq_num = ds.get("AcquisitionNumber", None)
             if acq_num is not None:
@@ -578,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
+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:
@@ -24,7 +20,7 @@ class STIRSPECTImageDataBuilder:
     def __init__(
         self,
         header_overrides=None,
-        backend: Literal["sirf", "stir"] | None = None,
+        backend: Optional[Literal["sirf", "stir"]] = None,
     ):
         if backend is not None and backend not in {"sirf", "stir"}:
             raise ValueError("backend must be one of: 'sirf', 'stir', or None")
@@ -58,7 +54,7 @@ class STIRSPECTImageDataBuilder:
             "!END OF INTERFILE": "",
         }
 
-        self.pixel_array: np.ndarray | None = None
+        self.pixel_array: Optional[np.ndarray] = None
 
         # Override defaults if header_overrides is provided.
         if header_overrides is not None:
@@ -98,16 +94,13 @@ class STIRSPECTImageDataBuilder:
             )
         return data
 
-    def build(self, output_path: str | Path | None = None):
+    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
@@ -126,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):
@@ -205,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)
@@ -227,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,22 +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
     ----------
@@ -29,7 +36,7 @@ def get(name: str) -> Path:
     return _res.files(__package__).joinpath(name)
 
 
-def list(ext: str | tuple[str, ...] = (".yaml", ".smc")) -> list[str]:
+def list(ext: Union[str, tuple[str, ...]] = (".yaml", ".smc")) -> list[str]:
     """
     List files in this package (default: *.yaml / *.smc).
     """

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,11 +32,10 @@ def __getattr__(name):
 
 __all__ = [
     "BaseConnector",
-    "NumpyConnector",
-    "ProjectionResult",
     "PyTomographySimindAdaptor",
+    "ProjectionResult",
     "RuntimeOperator",
-    "SimindPythonConnector",
     "SirfSimindAdaptor",
+    "SimindPythonConnector",
     "StirSimindAdaptor",
 ]