simind-python-connector 1.0.1__tar.gz → 1.1.0__tar.gz

{simind_python_connector-1.0.1/simind_python_connector.egg-info → simind_python_connector-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simind-python-connector
-Version: 1.0.1
+Version: 1.1.0
 Summary: Python SIMIND Monte Carlo connector with STIR/SIRF/PyTomography adaptors
 Author-email: Sam Porter <sam.porter.18@ucl.ac.uk>, Rebecca Gillen <rebecca.gillen.18@ucl.ac.uk>, "Efstathios (Stahis) Varzakis" <efstathios.varzakis.22@ucl.ac.uk>
 Maintainer-email: Sam Porter <sam.porter.18@ucl.ac.uk>

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/docs/changelog.rst

@@ -7,6 +7,76 @@ All notable changes to this project are documented in this file.
 
 The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_, and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
+1.1.0 - 2026-10-11
+------------------
+
+Replaces 2.0.0 and 3.0.0, which were published by mistake and have been
+withdrawn.
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+- The projection bin size and matrix (Index 28, 76, 77) come from the
+  configuration. ``configure_voxel_phantom`` no longer sets them from the
+  phantom image, which made the projections square whenever the image slices
+  were square and took the number of axial rows from the image height.
+- ``configure_voxel_phantom`` keeps the configured scoring routine (Index 84)
+  unless ``scoring_routine`` is given.
+- ``STIRSPECTAcquisitionDataBuilder`` no longer flips projection data along the
+  last axis.
+- Runtime-operator switches passed to ``run()`` apply to that run only. They
+  are no longer kept on the connector for later runs.
+- Each run deletes earlier outputs that share the output prefix before SIMIND
+  starts.
+- The STIR backend needs ``stirextra`` as well as ``stir``.
+- STIR/SIRF adaptors take the z voxel spacing from a different axis (see
+  Fixed). Results change for anisotropic voxels.
+- Invalid inputs now raise ``ValueError``: empty, non-finite or negative source
+  and attenuation maps, array shapes that do not match the header, and
+  ``output_prefix`` values that contain a path. Energy-window validation raises
+  ``ValueError`` instead of ``AssertionError``.
+
+Added
+~~~~~
+
+- ``run()`` warns when a voxel phantom is wider or longer than the projection
+  field of view.
+
+Fixed
+~~~~~
+
+- The packaged ``configs/input.smc`` is now included in the wheel. SMC parsing
+  handles fixed-width fields and checks section counts.
+- STIR/SIRF adaptors read the z voxel spacing from the correct axis:
+  ``voxel_sizes()`` is ``(z, y, x)``, and raw ``get_grid_spacing()`` is
+  ``(unused, z, y, x)``.
+- Voxel-map dimension indices 78, 79, 81 and 82 are set correctly.
+- The executor resolves ``SIMIND_BIN`` and accepts executable paths that
+  contain spaces. The connector no longer changes the process working directory.
+- Runtime switches apply to one run only. Output prefixes cannot escape the
+  output directory. Stale outputs are removed, and ``.win``, ``.smi`` and
+  ``.dmi`` inputs are kept.
+- Energy-window validation raises ``ValueError`` instead of failing an
+  ``assert``.
+- The Interfile loader honours data offsets, strips quoted values and rejects
+  truncated or oversized payloads. The SIMIND-to-STIR converter keeps data-file
+  lines and applies the radius scale factor.
+- Attenuation utilities handle the ``rho*1000`` selector and STIR ``#`` header
+  keys, and reject unknown attenuation types.
+- Image and acquisition builders validate array shapes, split multi-energy data
+  deterministically and no longer flip images. The DICOM builder handles missing
+  timing information and 2D pixel data.
+- Backend adaptors are imported lazily, so the core package imports without
+  STIR, SIRF or PyTomography.
+
+Removed
+~~~~~~~
+
+- The legacy ``scripts/simulation.py``.
+- The "non-square matrix" warning from
+  ``SimulationConfig.validate_parameters``; SIMIND supports non-square
+  projections.
+
 1.0.1 - 2026-04-16
 ------------------
 

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/docs/conf.py

@@ -13,7 +13,7 @@ sys.path.insert(0, os.path.abspath(".."))
 project = "simind-python-connector"
 copyright = f"{datetime.now().year}, Sam Porter, Efstathios Varzakis"
 author = "Sam Porter, Efstathios Varzakis"
-release = "1.0.1"
+release = "1.1.0"
 for dist_name in ("simind-python-connector",):
     try:
         release = importlib_metadata.version(dist_name)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0/docs}/examples/07A_stir_adaptor_osem.py

@@ -188,6 +188,10 @@ def main() -> None:
     adaptor.add_config_value(1, 140.0)
     adaptor.add_config_value(19, 2)
     adaptor.add_config_value(53, 0)
+    # Projections on the reconstruction grid: 32 x 32 bins of 4 mm (Index 28 in cm).
+    adaptor.add_config_value(28, 0.4)
+    adaptor.add_config_value(76, 32)
+    adaptor.add_config_value(77, 32)
     adaptor.run()
 
     projection = adaptor.get_total_output(window=1)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0/docs}/examples/07B_sirf_adaptor_osem.py

@@ -170,6 +170,10 @@ def main() -> None:
     adaptor.add_config_value(1, 140.0)
     adaptor.add_config_value(19, 2)
     adaptor.add_config_value(53, 0)
+    # Projections on the reconstruction grid: 32 x 32 bins of 4 mm (Index 28 in cm).
+    adaptor.add_config_value(28, 0.4)
+    adaptor.add_config_value(76, 32)
+    adaptor.add_config_value(77, 32)
     adaptor.run()
 
     projection = adaptor.get_total_output(window=1)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/docs/examples/07C_pytomography_adaptor_osem.py

@@ -144,6 +144,10 @@ def main() -> None:
     adaptor.add_config_value(1, 140.0)
     adaptor.add_config_value(19, 2)
     adaptor.add_config_value(53, 0)
+    # Projections on the reconstruction grid: 32 x 32 bins of 4 mm (Index 28 in cm).
+    adaptor.add_config_value(28, 0.4)
+    adaptor.add_config_value(76, 32)
+    adaptor.add_config_value(77, 32)
     adaptor.run()
 
     projection_tensor = adaptor.get_total_output(window=1).to(dtype=torch.float32)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/docs/geometry.rst

@@ -35,10 +35,32 @@ Units
 - STIR/SIRF image geometry is typically expressed in **mm**.
 - Connectors handle conversion internally via voxel-size settings (for example,
   runtime switch ``PX`` is set in cm for SIMIND).
-- STIR/SIRF adaptor voxel size extraction expects z-spacing in mm. It uses
-  ``voxel_sizes()[2]`` when available, and falls back to ``get_grid_spacing()``
-  using the last spatial element (index 3 for 4-element spacing, index 2 for
-  3-element spacing).
+- STIR/SIRF adaptor voxel size extraction expects z-spacing in mm. Images
+  report ``voxel_sizes()`` as ``(z, y, x)``, so the **first** element is the z
+  spacing. Raw ``get_grid_spacing()`` sequences follow the STIR coordinate
+  layout ``(unused, z, y, x)`` and use index 1; coordinate objects with a
+  ``z`` accessor use that accessor directly.
+
+Projection Size
+---------------
+
+The projection bin size and matrix come from the configuration: Index 28 (bin
+size in cm), Index 76 (bins) and Index 77 (axial rows). Configuring a voxel
+phantom does not change them, so set them to cover the phantom; ``run()`` warns
+when the phantom is wider or longer than the projection field of view. The
+matrix does not have to be square.
+
+Some projectors need the projections sampled like the image. STIR's SPECTUB
+needs equal axial sampling, so the OSEM examples set Index 28 to the voxel size.
+
+Voxel Phantom Slices
+--------------------
+
+Image slices do not have to be square. The columns (x, Index 78 and 79) and
+rows (y, Index 81 and 82) of the source and density maps are set separately,
+and a SIMIND test checks that non-square slices give the same projections as
+the same slices padded to square. The voxels themselves must be square in-plane:
+SIMIND takes a single voxel side (Index 31 and the ``PX`` switch).
 
 Example Configuration Guardrails
 --------------------------------
@@ -50,6 +72,8 @@ are reproducible:
 - ``config[29]=24`` for projection count.
 - ``config[53]=0`` to keep collimator modeling geometric-only in these tests.
 - ``config[19]=2`` to keep a consistent mapping used by current examples.
+- ``config[28]=0.4``, ``config[76]=32`` and ``config[77]=32`` to put the
+  projections on the 4 mm, 32-voxel reconstruction grid.
 
 Debug Checklist
 ---------------

{simind_python_connector-1.0.1/docs → simind_python_connector-1.1.0}/examples/07A_stir_adaptor_osem.py

@@ -188,6 +188,10 @@ def main() -> None:
     adaptor.add_config_value(1, 140.0)
     adaptor.add_config_value(19, 2)
     adaptor.add_config_value(53, 0)
+    # Projections on the reconstruction grid: 32 x 32 bins of 4 mm (Index 28 in cm).
+    adaptor.add_config_value(28, 0.4)
+    adaptor.add_config_value(76, 32)
+    adaptor.add_config_value(77, 32)
     adaptor.run()
 
     projection = adaptor.get_total_output(window=1)

{simind_python_connector-1.0.1/docs → simind_python_connector-1.1.0}/examples/07B_sirf_adaptor_osem.py

@@ -170,6 +170,10 @@ def main() -> None:
     adaptor.add_config_value(1, 140.0)
     adaptor.add_config_value(19, 2)
     adaptor.add_config_value(53, 0)
+    # Projections on the reconstruction grid: 32 x 32 bins of 4 mm (Index 28 in cm).
+    adaptor.add_config_value(28, 0.4)
+    adaptor.add_config_value(76, 32)
+    adaptor.add_config_value(77, 32)
     adaptor.run()
 
     projection = adaptor.get_total_output(window=1)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/examples/07C_pytomography_adaptor_osem.py

@@ -144,6 +144,10 @@ def main() -> None:
     adaptor.add_config_value(1, 140.0)
     adaptor.add_config_value(19, 2)
     adaptor.add_config_value(53, 0)
+    # Projections on the reconstruction grid: 32 x 32 bins of 4 mm (Index 28 in cm).
+    adaptor.add_config_value(28, 0.4)
+    adaptor.add_config_value(76, 32)
+    adaptor.add_config_value(77, 32)
     adaptor.run()
 
     projection_tensor = adaptor.get_total_output(window=1).to(dtype=torch.float32)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simind-python-connector"
-version = "1.0.1"
+version = "1.1.0"
 description = "Python SIMIND Monte Carlo connector with STIR/SIRF/PyTomography adaptors"
 readme = "README.md"
 requires-python = ">=3.9"

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/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.0.1"
+    __version__ = "1.1.0"
 
 
 def __getattr__(name: str) -> Any:

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/simind_python_connector/backends/__init__.py

@@ -19,6 +19,7 @@ Usage:
 
 import importlib
 import logging
+import os
 from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 
 from .base import AcquisitionDataInterface, ImageDataInterface
@@ -233,6 +234,9 @@ def create_image_data(
     if isinstance(filepath_or_object, ImageDataInterface):
         return filepath_or_object
 
+    if isinstance(filepath_or_object, os.PathLike):
+        filepath_or_object = os.fspath(filepath_or_object)
+
     backend_hint = detect_image_backend(filepath_or_object)
     if backend_hint is None:
         backend_hint = detect_backend_from_interface(filepath_or_object)
@@ -314,6 +318,9 @@ def create_acquisition_data(
     if isinstance(filepath_or_object, AcquisitionDataInterface):
         return filepath_or_object
 
+    if isinstance(filepath_or_object, os.PathLike):
+        filepath_or_object = os.fspath(filepath_or_object)
+
     backend_hint = detect_acquisition_backend(filepath_or_object)
     if backend_hint is None:
         backend_hint = detect_backend_from_interface(filepath_or_object)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/simind_python_connector/builders/acquisition_builder.py

@@ -97,6 +97,19 @@ class STIRSPECTAcquisitionDataBuilder:
         else:
             self.pixel_array = np.array(self.pixel_array, dtype=np.float32)
 
+        expected_shape = (
+            1,
+            matrix_size_1,
+            num_projections,
+            matrix_size_2,
+        )
+        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)"
+            )
+
         def _write(base_path: Path, cleanup: bool) -> AcquisitionData:
             header_path = base_path.with_suffix(".hs")
             raw_file_path = base_path.with_suffix(".s")
@@ -112,9 +125,8 @@ class STIRSPECTAcquisitionDataBuilder:
 
             acqdata = self._load_acquisition(str(header_path))
 
-            flipped = np.flip(self.pixel_array, axis=-1)
             acqdata = acqdata.clone()
-            acqdata.fill(flipped)
+            acqdata.fill(self.pixel_array)
             acqdata.write(str(header_path))
 
             if cleanup:
@@ -194,27 +206,50 @@ class STIRSPECTAcquisitionDataBuilder:
             acqdata = self.build(output_path=output_path_base)
             return [acqdata]
 
+        if self.pixel_array is None:
+            raise ValueError(
+                "build_multi_energy requires pixel_array to be set "
+                "(use update_header_from_dicom or set it directly)"
+            )
+
+        num_windows = len(self.energy_windows)
+        total_projections = int(self.header.get("!number of projections", 1))
+        if self.pixel_array.ndim != 4 or (
+            self.pixel_array.shape[2] != total_projections
+        ):
+            raise ValueError(
+                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
-        num_projections = int(self.header.get("!number of projections", 1))
-        num_projections //= len(self.energy_windows)
-        self.header["!number of projections"] = str(num_projections)
+        self.header["!number of projections"] = str(projections_per_window)
 
         # split pixel_array into energy windows along 3rd axis
-        pixel_array_list = np.array_split(
-            self.pixel_array, len(self.energy_windows), axis=2
-        )
-
-        acqdata_list = []
-        for idx, ew in enumerate(self.energy_windows):
-            # Update header for this energy window.
-            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]
-            acqdata = self.build(output_path=output_path)
-            acqdata_list.append(acqdata)
-        return acqdata_list
+        original_pixel_array = self.pixel_array
+        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.
+                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]
+                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)
 
     def update_header_from_dicom(self, dicom_filepath):
         """
@@ -303,6 +338,8 @@ class STIRSPECTAcquisitionDataBuilder:
             )
 
         # Rotation Information Sequence processing
+        num_frames = ds.get("NumberOfFrames", None)
+        time_per_projection = None
         try:
             if (0x0054, 0x0052) in ds:
                 rot_seq = ds[(0x0054, 0x0052)].value
@@ -322,16 +359,17 @@ class STIRSPECTAcquisitionDataBuilder:
                             rot_item[(0x0018, 0x1242)].value / 1000
                         )
 
-                    if num_frames is not None:
+                    if time_per_projection is not None and num_frames is not None:
                         self.header["number of time frames"] = str(1)
                         self.header["!image duration (sec)[1]"] = str(
                             int(
                                 np.round(
-                                    float(time_per_projection) * float(num_frames), 0
+                                    float(time_per_projection) * float(num_frames),
+                                    0,
                                 )
                             )
                         )
-                    else:
+                    elif time_per_projection is not None:
                         self.header["!time per projection (sec)[1]"] = (
                             time_per_projection
                         )
@@ -516,11 +554,21 @@ class STIRSPECTAcquisitionDataBuilder:
         except AttributeError:
             warnings.warn("StudyDescription not found in DICOM.")
         try:
-            self.pixel_array = ds.pixel_array
-            print(self.pixel_array.shape)
-            self.pixel_array = np.transpose(self.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)
+            raw_pixel_array = ds.pixel_array
         except AttributeError:
             warnings.warn("Pixel data not found in DICOM.")
+            return
+
+        raw_pixel_array = np.asarray(raw_pixel_array)
+        if raw_pixel_array.ndim == 2:
+            # Single frame: promote to (frames=1, rows, columns) so the
+            # transpose below sees the same layout as multiframe data.
+            raw_pixel_array = raw_pixel_array[np.newaxis, :, :]
+        elif raw_pixel_array.ndim != 3:
+            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)

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/simind_python_connector/builders/image_builder.py

@@ -79,12 +79,24 @@ class STIRSPECTImageDataBuilder:
 
     def _resolve_data_array(self) -> np.ndarray:
         if self.pixel_array is not None:
-            return np.asarray(self.pixel_array, dtype=np.float32)
-
-        dim_x = int(self.header["!matrix size [1]"])
-        dim_y = int(self.header["!matrix size [2]"])
-        dim_z = int(self.header["!matrix size [3]"])
-        return np.zeros((dim_z, dim_y, dim_x), dtype=np.float32)
+            data = np.asarray(self.pixel_array, dtype=np.float32)
+        else:
+            dim_x = int(self.header["!matrix size [1]"])
+            dim_y = int(self.header["!matrix size [2]"])
+            dim_z = int(self.header["!matrix size [3]"])
+            data = np.zeros((dim_z, dim_y, dim_x), dtype=np.float32)
+
+        expected_shape = (
+            int(self.header["!matrix size [3]"]),
+            int(self.header["!matrix size [2]"]),
+            int(self.header["!matrix size [1]"]),
+        )
+        if data.shape != expected_shape:
+            raise ValueError(
+                f"pixel array shape {data.shape} does not match header "
+                f"dimensions {expected_shape} (z, y, x)"
+            )
+        return data
 
     def build(self, output_path: Optional[str | Path] = None):
         """

simind_python_connector-1.1.0/simind_python_connector/connectors/__init__.py

@@ -0,0 +1,43 @@
+"""Connector/adaptor APIs.
+
+Backend-specific adaptors are exposed lazily so that importing this package
+never imports SIRF, STIR, or PyTomography.
+"""
+
+import importlib
+
+from .base import BaseConnector
+from .python_connector import (
+    NumpyConnector,
+    ProjectionResult,
+    RuntimeOperator,
+    SimindPythonConnector,
+)
+
+
+_LAZY_ADAPTORS = {
+    "PyTomographySimindAdaptor": "pytomography_adaptor",
+    "SirfSimindAdaptor": "sirf_adaptor",
+    "StirSimindAdaptor": "stir_adaptor",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_ADAPTORS:
+        module = importlib.import_module(f".{_LAZY_ADAPTORS[name]}", __name__)
+        obj = getattr(module, name)
+        globals()[name] = obj
+        return obj
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "BaseConnector",
+    "NumpyConnector",
+    "PyTomographySimindAdaptor",
+    "ProjectionResult",
+    "RuntimeOperator",
+    "SirfSimindAdaptor",
+    "SimindPythonConnector",
+    "StirSimindAdaptor",
+]

{simind_python_connector-1.0.1 → simind_python_connector-1.1.0}/simind_python_connector/connectors/_spacing.py

@@ -17,9 +17,11 @@ def _voxel_size_from_spacing(spacing: Any) -> float | None:
 
     if values:
         if len(values) >= 4:
-            return float(values[3])
-        if len(values) >= 3:
-            return float(values[2])
+            # 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 hasattr(spacing, "z"):
         try:
@@ -28,13 +30,13 @@ def _voxel_size_from_spacing(spacing: Any) -> float | None:
             pass
 
     if hasattr(spacing, "at"):
-        for index in (3, 2):
+        for index in (1, 2, 3):
             try:
                 return float(spacing.at(index))
             except Exception:
                 continue
 
-    for index in (3, 2):
+    for index in (1, 2, 3):
         try:
             return float(spacing[index])
         except Exception:
@@ -44,12 +46,16 @@ def _voxel_size_from_spacing(spacing: Any) -> float | None:
 
 
 def extract_voxel_size_mm(image: Any, backend_name: str) -> float:
-    """Extract z voxel spacing in mm from backend image metadata."""
+    """Extract z voxel spacing in mm from backend image metadata.
+
+    Backend images report ``voxel_sizes()`` in ``(z, y, x)`` order, so the
+    first element is the z spacing.
+    """
     if hasattr(image, "voxel_sizes"):
         voxel_sizes = image.voxel_sizes()
         try:
             if len(voxel_sizes) >= 3:
-                return float(voxel_sizes[2])
+                return float(voxel_sizes[0])
         except Exception:
             pass