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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simind-python-connector
-Version: 1.0.1
+Version: 1.1.1
 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.1}/docs/backends.rst

@@ -16,7 +16,7 @@ Dependency Matrix
    * - ``SimindPythonConnector``
      - SIMIND executable on ``PATH`` (no SIRF/STIR/PyTomography requirement)
    * - ``StirSimindAdaptor``
-     - STIR Python (``stir``)
+     - STIR Python (``stir`` and ``stirextra``)
    * - ``SirfSimindAdaptor``
      - SIRF (``sirf.STIR``)
    * - ``PyTomographySimindAdaptor``

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

@@ -7,6 +7,132 @@ 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.1 - 2026-10-11
+------------------
+
+Fixed
+~~~~~
+
+- A negative Index 1 (energies from the isotope file) turned the mu map into
+  near-vacuum; it is now converted at ``abs(Index 1)``.
+- Acquisition arrays use ``(tof, axial, view, bin)``, and DICOM matrix sizes and
+  pixel spacing are no longer swapped, so non-square projections build
+  correctly. ``create_stir_acqdata`` takes ``(bins, axial)`` and uses the same
+  layout.
+- The PyTomography adaptor reverses axial slices to match PyTomography's SIMIND
+  reader; reconstructions were flipped along z.
+- The STIR/SIRF adaptors raise a ``ValueError`` for non-cubic voxels instead of
+  using the z spacing for every axis.
+- The adaptors default ``scoring_routine`` to None, which keeps the
+  configuration's Index 84; they used to overwrite it with SCATTWIN.
+- The geometry docs give the projection axis orders correctly.
+- PyTomography PENETRATE and fallback outputs use the reader's
+  ``(view, bin, axial)`` order, and PyTomography scatter orders are validated
+  like the core's.
+- The STIR/SIRF adaptors reject a mu map whose voxel size differs from the
+  source's.
+- The legacy SIRF attenuation loader reverses the voxel sizes with the
+  dimensions.
+- The SIRF wrapper's ``maximum()`` and ``sapyb()`` update the wrapped object.
+- Piecewise Schneider conversion gives HU outside the table the nearest
+  segment's density, so metal above 4001 HU no longer becomes air.
+- MPI runs use ``$SIMIND_MPI_BIN``, else ``simind_mpi`` next to the serial
+  binary, with ``/MP`` and without a stray ``-p``.
+- An output header that cannot be read raises instead of being skipped.
+- YAML export keeps unnamed parameters and flags.
+- New header keys are written before ``!END OF INTERFILE``, and ``set()``
+  changes the last duplicate key, the one readers use.
+- A header converted into another directory points at its data by absolute
+  path, and an orbit file named like an ignored key keeps its radii.
+- DICOM frames are split by ``EnergyWindowVector`` when present; each output
+  declares one window and its share of the duration.
+- ``run()`` sets Flags 5 and 14, which SIMIND needs to write readable headers,
+  so config-defined phantom runs work.
+- Example 07C no longer drops attenuation and PSF modelling silently, and the
+  examples accept ``SIMIND_BIN``.
+- Importing the converter no longer configures root logging.
+- setuptools 77.0.3 or newer is required to build.
+
+Changed
+~~~~~~~
+
+- ``get_attenuation_coefficient`` takes keV, as documented.
+- ``NN`` must be an integer >= 1, switches reject None and bool values,
+  ``quantization_scale`` must be in (0, 1], and ``output_prefix`` must match
+  ``[a-z0-9][a-z0-9_-]*`` (SIMIND lowercases file names).
+- Publishing waits for the tests and checks the tag against the version; tests
+  also run on ``release/**`` branches.
+
+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.1}/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.1"
 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.1/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.1/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.1}/docs/examples/07C_pytomography_adaptor_osem.py

@@ -90,21 +90,13 @@ def _build_system_matrix(
 ) -> SPECTSystemMatrix:
     object_meta, proj_meta = pytomo_simind.get_metadata(str(projection_header))
 
-    obj2obj_transforms = []
-    try:
-        obj2obj_transforms.append(
-            SPECTAttenuationTransform(
-                attenuation_map=attenuation_map_xyz.to(dtype=torch.float32).contiguous()
-            )
-        )
-    except Exception:
-        pass
-
-    try:
-        psf_meta = pytomo_simind.get_psfmeta_from_header(str(projection_header))
-        obj2obj_transforms.append(SPECTPSFTransform(psf_meta=psf_meta))
-    except Exception:
-        pass
+    psf_meta = pytomo_simind.get_psfmeta_from_header(str(projection_header))
+    obj2obj_transforms = [
+        SPECTAttenuationTransform(
+            attenuation_map=attenuation_map_xyz.to(dtype=torch.float32).contiguous()
+        ),
+        SPECTPSFTransform(psf_meta=psf_meta),
+    ]
 
     return SPECTSystemMatrix(
         obj2obj_transforms=obj2obj_transforms,
@@ -144,6 +136,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.1/docs}/examples/_python_connector_helpers.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import shutil
 
 import numpy as np
@@ -8,9 +9,9 @@ from simind_python_connector import SimindPythonConnector
 
 
 def require_simind() -> None:
-    if shutil.which("simind") is None:
+    if shutil.which(os.environ.get("SIMIND_BIN") or "simind") is None:
         raise RuntimeError(
-            "SIMIND executable not found in PATH. "
+            "SIMIND executable not found ($SIMIND_BIN or simind on PATH). "
             "Install SIMIND before running this example."
         )
 

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

@@ -9,9 +9,9 @@ At-a-Glance Axis Conventions
 
 - STIR/SIRF image arrays are handled as ``(z, y, x)``.
 - STIR/SIRF projection arrays are often 4D with a singleton TOF axis:
-  ``(tof, bin, view, axial)``. For these, **view 0** is ``arr[0, :, 0, :]``.
+  ``(tof, axial, view, bin)``. For these, **view 0** is ``arr[0, :, 0, :]``.
 - Raw Interfile projection loading in ``interfile_numpy`` is exposed as
-  ``(views, bins, axial)`` when no singleton TOF axis is present.
+  ``(view, axial, bin)`` when no singleton TOF axis is present.
 - ``PyTomographySimindAdaptor`` public object-space tensors are ``(x, y, z)``.
 - PyTomography object space is ``(x, y, z)`` (``Lx, Ly, Lz``).
 - PyTomography SIMIND projections from ``pytomography.io.SPECT.simind`` are
@@ -35,10 +35,31 @@ 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 adaptors read the voxel spacing in mm and need cubic voxels; other
+  images raise a ``ValueError``. Images report ``voxel_sizes()`` as
+  ``(z, y, x)``, and raw ``get_grid_spacing()`` sequences follow the STIR
+  coordinate layout ``(unused, z, y, x)``.
+
+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 +71,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.1}/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.1}/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.1}/examples/07C_pytomography_adaptor_osem.py

@@ -90,21 +90,13 @@ def _build_system_matrix(
 ) -> SPECTSystemMatrix:
     object_meta, proj_meta = pytomo_simind.get_metadata(str(projection_header))
 
-    obj2obj_transforms = []
-    try:
-        obj2obj_transforms.append(
-            SPECTAttenuationTransform(
-                attenuation_map=attenuation_map_xyz.to(dtype=torch.float32).contiguous()
-            )
-        )
-    except Exception:
-        pass
-
-    try:
-        psf_meta = pytomo_simind.get_psfmeta_from_header(str(projection_header))
-        obj2obj_transforms.append(SPECTPSFTransform(psf_meta=psf_meta))
-    except Exception:
-        pass
+    psf_meta = pytomo_simind.get_psfmeta_from_header(str(projection_header))
+    obj2obj_transforms = [
+        SPECTAttenuationTransform(
+            attenuation_map=attenuation_map_xyz.to(dtype=torch.float32).contiguous()
+        ),
+        SPECTPSFTransform(psf_meta=psf_meta),
+    ]
 
     return SPECTSystemMatrix(
         obj2obj_transforms=obj2obj_transforms,
@@ -144,6 +136,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/docs → simind_python_connector-1.1.1}/examples/_python_connector_helpers.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import shutil
 
 import numpy as np
@@ -8,9 +9,9 @@ from simind_python_connector import SimindPythonConnector
 
 
 def require_simind() -> None:
-    if shutil.which("simind") is None:
+    if shutil.which(os.environ.get("SIMIND_BIN") or "simind") is None:
         raise RuntimeError(
-            "SIMIND executable not found in PATH. "
+            "SIMIND executable not found ($SIMIND_BIN or simind on PATH). "
             "Install SIMIND before running this example."
         )
 

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

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools>=61.0", "wheel"]
+requires = ["setuptools>=77.0.3", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "simind-python-connector"
-version = "1.0.1"
+version = "1.1.1"
 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.1}/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.1"
 
 
 def __getattr__(name: str) -> Any:

{simind_python_connector-1.0.1 → simind_python_connector-1.1.1}/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.1}/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