simind-python-connector 1.0.0__py3-none-any.whl

simind_python_connector/utils/interfile_numpy.py

@@ -0,0 +1,195 @@
+"""
+Utilities for loading Interfile projection data directly into NumPy.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping, Optional, Sequence, Union
+
+import numpy as np
+
+from .interfile_parser import parse_interfile_header
+
+
+MatrixShape = Sequence[int]
+HeaderInput = Union[str, Path]
+
+_MATRIX_SIZE_PATTERN = re.compile(r"!?matrix size\s*\[(\d+)\]", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class InterfileArray:
+    """NumPy payload and file references parsed from an Interfile header."""
+
+    array: np.ndarray
+    header_path: Path
+    data_path: Path
+    metadata: dict[str, str]
+
+
+def _lookup_header_value(header: Mapping[str, str], *keys: str) -> Optional[str]:
+    """Return the first matching value for a header key (case-insensitive)."""
+    lower_map = {key.lower(): value for key, value in header.items()}
+    for key in keys:
+        value = lower_map.get(key.lower())
+        if value is not None:
+            return value
+    return None
+
+
+def _extract_matrix_shape(header: Mapping[str, str]) -> tuple[int, ...]:
+    """Extract matrix sizes and return NumPy shape in memory order."""
+    sizes_by_index: dict[int, int] = {}
+
+    for key, raw_value in header.items():
+        match = _MATRIX_SIZE_PATTERN.fullmatch(key.strip())
+        if not match:
+            continue
+        axis = int(match.group(1))
+        sizes_by_index[axis] = int(raw_value)
+
+    if not sizes_by_index:
+        raise ValueError("No 'matrix size [i]' entries found in Interfile header")
+
+    ordered_axes = [sizes_by_index[idx] for idx in sorted(sizes_by_index)]
+    if any(size <= 0 for size in ordered_axes):
+        raise ValueError(f"Invalid matrix sizes in header: {ordered_axes}")
+
+    # Interfile stores axis [1] as the fastest changing index.
+    return tuple(reversed(ordered_axes))
+
+
+def _extract_numpy_dtype(header: Mapping[str, str]) -> np.dtype:
+    """Infer the binary payload dtype from Interfile metadata."""
+    number_format = (
+        _lookup_header_value(header, "!number format", "number format") or "float"
+    ).strip()
+    bytes_per_pixel_raw = _lookup_header_value(
+        header, "!number of bytes per pixel", "number of bytes per pixel"
+    )
+    bytes_per_pixel = int(float(bytes_per_pixel_raw)) if bytes_per_pixel_raw else 4
+
+    number_format_lc = number_format.lower()
+    if "float" in number_format_lc:
+        kind = "f"
+    elif "unsigned" in number_format_lc:
+        kind = "u"
+    elif "signed" in number_format_lc or "integer" in number_format_lc:
+        kind = "i"
+    else:
+        raise ValueError(f"Unsupported Interfile number format: {number_format!r}")
+
+    dtype = np.dtype(f"{kind}{bytes_per_pixel}")
+    byte_order = (
+        _lookup_header_value(header, "imagedata byte order", "!imagedata byte order")
+        or ""
+    ).lower()
+
+    if "big" in byte_order:
+        return dtype.newbyteorder(">")
+    if "little" in byte_order:
+        return dtype.newbyteorder("<")
+    return dtype.newbyteorder("=")
+
+
+def _extract_projection_count(header: Mapping[str, str]) -> Optional[int]:
+    """Extract projection/image count used for 3D SPECT sinograms."""
+    raw = _lookup_header_value(
+        header,
+        "!number of projections",
+        "number of projections",
+        "!total number of images",
+        "total number of images",
+        "!number of images/energy window",
+        "number of images/energy window",
+    )
+    if raw is None:
+        return None
+    try:
+        value = int(float(raw))
+    except (TypeError, ValueError):
+        return None
+    return value if value > 0 else None
+
+
+def _infer_leading_axis_count(
+    metadata: Mapping[str, str], plane_elements: int, payload_elements: int
+) -> Optional[int]:
+    """Infer leading stack axis for headers that only declare 2D planes."""
+    if plane_elements <= 0:
+        return None
+
+    # Prefer explicit projection/image-count fields from the header.
+    projection_count = _extract_projection_count(metadata)
+    if projection_count is not None:
+        return projection_count
+
+    # Otherwise infer directly from payload length when possible.
+    if payload_elements % plane_elements == 0:
+        inferred = payload_elements // plane_elements
+        if inferred > 0:
+            return inferred
+
+    # Fall back to a single-frame stack rather than treating projections as 2D.
+    return 1
+
+
+def load_interfile_array(header_path: HeaderInput) -> InterfileArray:
+    """Load projection data referenced by an Interfile header into NumPy."""
+    header_path = Path(header_path).expanduser().resolve()
+    metadata = parse_interfile_header(str(header_path))
+
+    data_filename = _lookup_header_value(
+        metadata, "!name of data file", "name of data file"
+    )
+    if not data_filename:
+        raise ValueError(
+            f"Interfile header {header_path} does not define 'name of data file'"
+        )
+
+    data_path = (header_path.parent / data_filename).resolve()
+    if not data_path.exists():
+        raise FileNotFoundError(
+            f"Interfile data file referenced by header does not exist: {data_path}"
+        )
+
+    dtype = _extract_numpy_dtype(metadata)
+    shape = _extract_matrix_shape(metadata)
+    expected_elements = int(np.prod(shape))
+
+    flat = np.fromfile(data_path, dtype=dtype)
+
+    # Projection and tomographic payloads are treated as at least 3D:
+    # [leading_axis, axis2, axis1]. If headers only declare matrix sizes [1],[2],
+    # recover the leading axis from projection count fields or payload length.
+    if len(shape) == 2:
+        leading_count = _infer_leading_axis_count(
+            metadata, expected_elements, flat.size
+        )
+        if leading_count is not None:
+            shape = (leading_count, *shape)
+            expected_elements = int(np.prod(shape))
+
+    if flat.size < expected_elements:
+        raise ValueError(
+            f"Data size mismatch for {data_path}: expected {expected_elements} "
+            f"elements for shape {shape}, found {flat.size}"
+        )
+
+    # SIMIND files can contain trailing payload not represented by Interfile keys.
+    # Use the declared geometry and discard trailing elements.
+    if flat.size > expected_elements:
+        flat = flat[:expected_elements]
+
+    return InterfileArray(
+        array=flat.reshape(shape),
+        header_path=header_path,
+        data_path=data_path,
+        metadata=dict(metadata),
+    )
+
+
+__all__ = ["InterfileArray", "load_interfile_array"]

simind_python_connector/utils/interfile_parser.py

@@ -0,0 +1,175 @@
+"""
+Shared interfile parsing utilities.
+
+This module provides consistent parsing for STIR interfile header files,
+eliminating duplicate parsing logic across the codebase.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional, Tuple, Union
+
+
+Number = Union[tuple, list, float, int, str]
+
+
+def parse_interfile_line(line: str) -> Tuple[Optional[str], Optional[str]]:
+    """Parse a single interfile line and return (key, value) tuple.
+
+    Args:
+        line: A line from an interfile header file
+
+    Returns:
+        Tuple of (key, value) or (None, None) if line is not parseable
+
+    Examples:
+        >>> parse_interfile_line("matrix size [1] := 128")
+        ('matrix size [1]', '128')
+        >>> parse_interfile_line("; This is a comment")
+        (None, None)
+        >>> parse_interfile_line("!INTERFILE :=")
+        (None, None)
+    """
+    line = line.strip()
+
+    # Skip comments, empty lines, and section headers
+    if not line or line.startswith(";") or line.startswith("#") or line.endswith(":="):
+        return None, None
+
+    # Handle := separator (preferred)
+    if ":=" in line:
+        key, _, value = line.partition(":=")
+        return key.strip(), value.strip()
+
+    return None, None
+
+
+def parse_interfile_header(filename: str) -> dict[str, str]:
+    """Parse an entire interfile header file and return key-value dict.
+
+    Args:
+        filename: Path to interfile header file (.hs, .hv, .hct, etc.)
+
+    Returns:
+        Dictionary of key-value pairs from the header
+
+    Examples:
+        >>> attrs = parse_interfile_header("template.hs")
+        >>> attrs["number of projections"]
+        '64'
+    """
+    values = {}
+    with open(filename, "r") as file:
+        for line in file:
+            key, value = parse_interfile_line(line)
+            if key is not None:
+                values[key] = value
+    return values
+
+
+def parse_interfile_with_regex(filename: str) -> dict[str, str]:
+    """Parse interfile using regex pattern (legacy compatibility).
+
+    This is the original parsing method from stir_utils.py.
+    Use parse_interfile_header() for new code.
+
+    Args:
+        filename: Path to interfile header file
+
+    Returns:
+        Dictionary of key-value pairs
+    """
+    values = {}
+    with open(filename, "r") as file:
+        for line in file:
+            if match := re.search(r"([^;].*?)\s*:=\s*(.*)", line):
+                key = match[1].strip()
+                value = match[2].strip()
+                values[key] = value
+    return values
+
+
+@dataclass
+class InterfileEntry:
+    """Represents a single line inside an interfile header."""
+
+    text: str
+    key: Optional[str]
+    value: Optional[str]
+
+    @classmethod
+    def from_line(cls, line: str) -> "InterfileEntry":
+        key, value = parse_interfile_line(line)
+        # Preserve newline from source to avoid formatting churn
+        if not line.endswith("\n"):
+            line = line + "\n"
+        return cls(text=line, key=key, value=value)
+
+    @classmethod
+    def from_key_value(cls, key: str, value: Number) -> "InterfileEntry":
+        value_str = cls._coerce_value(value)
+        return cls(text=f"{key} := {value_str}\n", key=key, value=value_str)
+
+    @staticmethod
+    def _coerce_value(value: Number) -> str:
+        if isinstance(value, (tuple, list)):
+            return "{" + ", ".join(str(v) for v in value) + "}"
+        return str(value)
+
+    def set_value(self, value: Number) -> None:
+        value_str = self._coerce_value(value)
+        self.value = value_str
+        if self.key is None:
+            raise ValueError("Cannot set value on entry without a key")
+        self.text = f"{self.key} := {value_str}\n"
+
+    def copy(self) -> "InterfileEntry":
+        return InterfileEntry(text=self.text, key=self.key, value=self.value)
+
+
+class InterfileHeader:
+    """Editable representation of a parsed interfile header."""
+
+    def __init__(self, entries: List[InterfileEntry]):
+        self._entries = entries
+
+    @classmethod
+    def from_file(cls, filename: str) -> "InterfileHeader":
+        with open(filename, "r") as file:
+            entries = [InterfileEntry.from_line(line) for line in file]
+        return cls(entries)
+
+    def copy(self) -> "InterfileHeader":
+        return InterfileHeader([entry.copy() for entry in self._entries])
+
+    def get(self, key: str, default: Optional[str] = None) -> Optional[str]:
+        for entry in reversed(self._entries):
+            if entry.key == key:
+                return entry.value
+        return default
+
+    def set(self, key: str, value: Number) -> None:
+        for entry in self._entries:
+            if entry.key == key:
+                entry.set_value(value)
+                return
+        self._entries.append(InterfileEntry.from_key_value(key, value))
+
+    def insert(self, index: int, key: str, value: Number) -> None:
+        entry = InterfileEntry.from_key_value(key, value)
+        index = max(0, min(index, len(self._entries)))
+        self._entries.insert(index, entry)
+
+    def write(self, filename: str) -> None:
+        with open(filename, "w") as file:
+            for entry in self._entries:
+                file.write(entry.text)
+
+
+__all__ = [
+    "InterfileHeader",
+    "InterfileEntry",
+    "parse_interfile_line",
+    "parse_interfile_header",
+    "parse_interfile_with_regex",
+]

simind_python_connector/utils/io_utils.py

@@ -0,0 +1,14 @@
+import shutil
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def temporary_directory():
+    """Context manager for creating and cleaning up a temporary directory."""
+    temp_dir = tempfile.mkdtemp()
+    try:
+        yield Path(temp_dir)
+    finally:
+        shutil.rmtree(temp_dir, ignore_errors=True)

simind_python_connector/utils/simind_utils.py

@@ -0,0 +1,70 @@
+import os
+from numbers import Number
+
+
+class SimindError(Exception):
+    """Base exception for SIMIND-related errors."""
+
+
+class SimindNotFoundError(SimindError):
+    """Raised when SIMIND executable is not found."""
+
+
+def create_window_file(
+    lower_bounds: list,
+    upper_bounds: list,
+    scatter_orders: list,
+    output_filename: str = "input",
+    energy_window=None,
+    lower_ew=None,
+    upper_ew=None,
+):
+    """
+    Creates a window file for simind simulation
+
+    Args:
+        lower_bounds (list): lower bounds of energy windows
+        upper_bounds (list): upper bounds of energy windows
+        scatter_orders (list): scatter orders of energy windows
+        output_filename (str, optional): name of output file. Defaults to 'input'.
+        ! energy_window (str, optional): energy window type can be dew or dew.
+            Defaults to None.
+        ! lower_ew (list, optional): lower energy window lower and upper bounds.
+            Defaults to None.
+        ! upper_ew (list, optional): upper energy window lower and upper bounds.
+            Defaults to None.
+        ! Note that dual and triple energy windows are not yet supported by this
+        wrapper. Please define your own energy windows and work out yourself
+    """
+
+    # if path suffix is not. win, add it
+    if not output_filename.endswith(".win"):
+        output_filename += ".win"
+
+    if isinstance(lower_bounds, Number):
+        lower_bounds = [lower_bounds]
+    if isinstance(upper_bounds, Number):
+        upper_bounds = [upper_bounds]
+    if isinstance(scatter_orders, Number):
+        scatter_orders = [scatter_orders]
+
+    assert len(lower_bounds) == len(upper_bounds) == len(scatter_orders), (
+        "lower_bounds, upper_bounds and scatter_orders must have same length"
+    )
+
+    # remove previous window file if present
+    if os.path.exists(output_filename):
+        os.remove(output_filename)
+
+    with open(output_filename, "w") as file:
+        for i in range(len(lower_bounds)):
+            # for some reason simind doesn't like the last line to have a newline
+            # character
+            file.write(
+                f"{float(lower_bounds[i])},{float(upper_bounds[i])},{int(scatter_orders[i])}\n"
+            )
+        # simind sometimes doesn't output scatter files unless there's one line
+        # with a dedicated scatter order
+        # annoyingle this will create one extra total, air, scatter file
+        if max(scatter_orders) < 1:
+            file.write(f"{float(lower_bounds[i])},{float(upper_bounds[i])},1")

simind_python_connector/utils/sirf_stir_utils.py

@@ -0,0 +1,194 @@
+"""
+Helpers for working with SIRF/STIR native objects alongside the backend interfaces.
+
+These utilities hide the wrapping/unwrapping boilerplate so callers can pass the
+objects they already have, while the simulator continues to interact with the
+uniform interface layer.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+
+from simind_python_connector.backends import (
+    AcquisitionDataInterface,
+    ImageDataInterface,
+    create_acquisition_data,
+    create_image_data,
+    detect_acquisition_backend,
+    detect_backend_from_interface,
+    detect_image_backend,
+    get_backend,
+    set_backend,
+    unwrap,
+)
+
+
+image_like = Union[str, ImageDataInterface, Any]
+acquisition_like = Union[str, AcquisitionDataInterface, Any]
+
+
+def _validate_backend_name(name: str) -> str:
+    if name not in ("sirf", "stir"):
+        raise ValueError(f"Backend must be 'sirf' or 'stir', got {name!r}")
+    return name
+
+
+def _ensure_backend(preferred: Optional[str]) -> None:
+    """Ensure a particular backend is active if explicitly requested."""
+    if preferred is None:
+        return
+
+    preferred = _validate_backend_name(preferred)
+    if get_backend() != preferred:
+        set_backend(preferred)
+
+
+def ensure_image_interface(
+    value: image_like, preferred_backend: Optional[str] = None
+) -> ImageDataInterface:
+    """Return an ImageDataInterface for the provided value."""
+    if isinstance(value, ImageDataInterface):
+        if preferred_backend:
+            backend = detect_backend_from_interface(value)
+            preferred_backend = _validate_backend_name(preferred_backend)
+            if backend and backend != preferred_backend:
+                raise ValueError(
+                    f"Image is backed by {backend}, expected {preferred_backend}"
+                )
+        return value
+
+    if preferred_backend:
+        _ensure_backend(preferred_backend)
+    return create_image_data(value)
+
+
+def ensure_acquisition_interface(
+    value: acquisition_like, preferred_backend: Optional[str] = None
+) -> AcquisitionDataInterface:
+    """Return an AcquisitionDataInterface for the provided value."""
+    if isinstance(value, AcquisitionDataInterface):
+        if preferred_backend:
+            backend = detect_backend_from_interface(value)
+            preferred_backend = _validate_backend_name(preferred_backend)
+            if backend and backend != preferred_backend:
+                raise ValueError(
+                    f"Acquisition data is backed by {backend}, "
+                    f"expected {preferred_backend}"
+                )
+        return value
+
+    if preferred_backend:
+        _ensure_backend(preferred_backend)
+    return create_acquisition_data(value)
+
+
+def to_native_image(
+    value: image_like,
+    preferred_backend: Optional[str] = None,
+    ensure_interface: bool = True,
+) -> Any:
+    """
+    Retrieve a native SIRF/STIR image from any supported input.
+
+    Args:
+        value: Path, interface, or native object.
+        preferred_backend: Optional backend to enforce. When provided and value
+            is a path, the backend will be switched before loading.
+        ensure_interface: When True, non-interface values are wrapped so that
+            the simulator's interface guarantees remain intact before unwrapping.
+    """
+    if ensure_interface or not isinstance(value, ImageDataInterface):
+        wrapper = ensure_image_interface(value, preferred_backend)
+    else:
+        wrapper = value
+
+    native = unwrap(wrapper)
+    if preferred_backend:
+        expected = _validate_backend_name(preferred_backend)
+        actual = detect_image_backend(native)
+        if actual and actual != expected:
+            raise ValueError(f"Image native backend is {actual}, expected {expected}")
+    return native
+
+
+def to_native_acquisition(
+    value: acquisition_like,
+    preferred_backend: Optional[str] = None,
+    ensure_interface: bool = True,
+) -> Any:
+    """Retrieve a native acquisition object from any supported input."""
+    if ensure_interface or not isinstance(value, AcquisitionDataInterface):
+        wrapper = ensure_acquisition_interface(value, preferred_backend)
+    else:
+        wrapper = value
+
+    native = unwrap(wrapper)
+    if preferred_backend:
+        expected = _validate_backend_name(preferred_backend)
+        actual = detect_acquisition_backend(native)
+        if actual and actual != expected:
+            raise ValueError(
+                f"Acquisition native backend is {actual}, expected {expected}"
+            )
+    return native
+
+
+def register_and_enforce_backend(
+    detected_backend: Optional[str], current_backend: Optional[str]
+) -> Optional[str]:
+    """Register and enforce backend consistency across simulator inputs.
+
+    This helper manages backend hints and ensures that all inputs to the
+    simulator use the same backend (either SIRF or STIR). Once a backend
+    is detected from the first input, subsequent inputs must match.
+
+    Args:
+        detected_backend: Backend detected from current input ('sirf', 'stir', or None)
+        current_backend: Currently registered backend preference (or None)
+
+    Returns:
+        Updated backend preference (either current_backend or detected_backend)
+
+    Raises:
+        ValueError: If detected_backend conflicts with current_backend
+
+    Example:
+        >>> backend = None
+        >>> backend = register_and_enforce_backend('sirf', backend)  # Returns 'sirf'
+        >>> backend = register_and_enforce_backend('sirf', backend)  # OK, matches
+        >>> backend = register_and_enforce_backend('stir', backend)  # Raises ValueError
+    """
+    if detected_backend:
+        detected_backend = detected_backend.lower()
+
+        # Validate backend name
+        if detected_backend not in ("sirf", "stir"):
+            raise ValueError(
+                f"Backend must be 'sirf' or 'stir', got {detected_backend!r}"
+            )
+
+        # Check for conflicts
+        if current_backend and current_backend != detected_backend:
+            raise ValueError(
+                f"Backend mismatch: simulator already configured for "
+                f"{current_backend.upper()} backend but received "
+                f"{detected_backend.upper()} data."
+            )
+
+        # Register the backend globally
+        current_backend = detected_backend
+        current = get_backend()
+        if current != detected_backend:
+            set_backend(detected_backend)
+
+    return current_backend
+
+
+__all__ = [
+    "ensure_image_interface",
+    "ensure_acquisition_interface",
+    "to_native_image",
+    "to_native_acquisition",
+    "register_and_enforce_backend",
+]