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

simind_python_connector/backends/base.py

@@ -0,0 +1,387 @@
+"""
+Base interfaces for SIRF and STIR Python backends.
+
+This module defines abstract base classes that provide a unified interface
+for working with both SIRF and STIR Python libraries.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Tuple, Union
+
+import numpy as np
+
+
+class ImageDataInterface(ABC):
+    """Abstract interface for image data objects.
+
+    Includes SIRF ``ImageData`` and STIR ``FloatVoxelsOnCartesianGrid`` types.
+    """
+
+    @classmethod
+    @abstractmethod
+    def read_from_file(cls, filepath: str) -> "ImageDataInterface":
+        """Read image data from file.
+
+        Args:
+            filepath: Path to image file (.hv)
+
+        Returns:
+            ImageDataInterface: Wrapped image object
+        """
+        pass
+
+    @abstractmethod
+    def write(self, filepath: str) -> None:
+        """Write image data to file.
+
+        Args:
+            filepath: Output file path
+        """
+        pass
+
+    @abstractmethod
+    def fill(self, data: Union[np.ndarray, float]) -> None:
+        """Fill image with data.
+
+        Args:
+            data: Numpy array or scalar value
+        """
+        pass
+
+    @abstractmethod
+    def clone(self) -> "ImageDataInterface":
+        """Create a deep copy of the image.
+
+        Returns:
+            ImageDataInterface: Cloned image object
+        """
+        pass
+
+    @abstractmethod
+    def get_uniform_copy(self, value: float) -> "ImageDataInterface":
+        """Create a uniform copy with specified value.
+
+        Args:
+            value: Value to fill the image with
+
+        Returns:
+            ImageDataInterface: New uniform image
+        """
+        pass
+
+    @abstractmethod
+    def dimensions(self) -> Tuple[int, int, int]:
+        """Get image dimensions.
+
+        Returns:
+            Tuple[int, int, int]: (z, y, x) dimensions
+        """
+        pass
+
+    @abstractmethod
+    def voxel_sizes(self) -> Tuple[float, float, float]:
+        """Get voxel sizes in mm.
+
+        Returns:
+            Tuple[float, float, float]: (z, y, x) voxel sizes
+        """
+        pass
+
+    @abstractmethod
+    def as_array(self) -> np.ndarray:
+        """Convert to numpy array.
+
+        Returns:
+            np.ndarray: Image data as numpy array
+        """
+        pass
+
+    @abstractmethod
+    def sum(self) -> float:
+        """Sum all values in the image.
+
+        Returns:
+            float: Sum of all voxel values
+        """
+        pass
+
+    @abstractmethod
+    def max(self) -> float:
+        """Return the maximum voxel value.
+
+        Returns:
+            float: Maximum voxel value
+        """
+        pass
+
+    @abstractmethod
+    def maximum(self, value: float) -> None:
+        """Apply element-wise maximum (clipping).
+
+        Args:
+            value: Minimum value to clip to
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def native_object(self):
+        """Get the underlying native object.
+
+        Returns either SIRF ``ImageData`` or STIR
+        ``FloatVoxelsOnCartesianGrid``.
+        """
+        pass
+
+    # Arithmetic operations
+    @abstractmethod
+    def __add__(self, other):
+        """Add two images or image and scalar."""
+        pass
+
+    @abstractmethod
+    def __sub__(self, other):
+        """Subtract two images or image and scalar."""
+        pass
+
+    @abstractmethod
+    def __mul__(self, other):
+        """Multiply image by scalar or element-wise."""
+        pass
+
+    @abstractmethod
+    def __truediv__(self, other):
+        """Divide image by scalar or element-wise."""
+        pass
+
+    @abstractmethod
+    def __radd__(self, other):
+        """Right-hand addition."""
+        pass
+
+    @abstractmethod
+    def __rsub__(self, other):
+        """Right-hand subtraction."""
+        pass
+
+    @abstractmethod
+    def __rmul__(self, other):
+        """Right-hand multiplication."""
+        pass
+
+    @abstractmethod
+    def __rtruediv__(self, other):
+        """Right-hand division."""
+        pass
+
+    @abstractmethod
+    def __neg__(self):
+        """Negate image."""
+        pass
+
+    @abstractmethod
+    def sapyb(
+        self, a: float, y: "ImageDataInterface", b: float
+    ) -> "ImageDataInterface":
+        """Compute self * a + y * b (element-wise), modifying self in place.
+
+        This method modifies self in place: self = self * a + y * b
+
+        Args:
+            a: Scalar multiplier for self
+            y: Other image
+            b: Scalar multiplier for y
+
+        Returns:
+            ImageDataInterface: self after modification (for chaining)
+        """
+        pass
+
+
+class AcquisitionDataInterface(ABC):
+    """Abstract interface for acquisition data (AcquisitionData or ProjData)."""
+
+    @classmethod
+    @abstractmethod
+    def read_from_file(cls, filepath: str) -> "AcquisitionDataInterface":
+        """Read acquisition data from file.
+
+        Args:
+            filepath: Path to header file (.hs)
+
+        Returns:
+            AcquisitionDataInterface: Wrapped acquisition object
+        """
+        pass
+
+    @abstractmethod
+    def write(self, filepath: str) -> None:
+        """Write acquisition data to file.
+
+        Args:
+            filepath: Output file path
+        """
+        pass
+
+    @abstractmethod
+    def fill(self, data: Union[np.ndarray, float]) -> None:
+        """Fill acquisition data.
+
+        Args:
+            data: Numpy array or scalar value
+        """
+        pass
+
+    @abstractmethod
+    def clone(self) -> "AcquisitionDataInterface":
+        """Create a deep copy.
+
+        Returns:
+            AcquisitionDataInterface: Cloned object
+        """
+        pass
+
+    @abstractmethod
+    def get_uniform_copy(self, value: float) -> "AcquisitionDataInterface":
+        """Create a uniform copy with specified value.
+
+        Args:
+            value: Value to fill the acquisition data with
+
+        Returns:
+            AcquisitionDataInterface: New uniform acquisition data
+        """
+        pass
+
+    @abstractmethod
+    def dimensions(self) -> Tuple:
+        """Get acquisition data dimensions.
+
+        Returns:
+            Tuple: Dimensions (varies by format)
+        """
+        pass
+
+    @property
+    def shape(self) -> Tuple:
+        """Get acquisition data shape (alias for dimensions()).
+
+        Returns:
+            Tuple: Dimensions (varies by format)
+        """
+        return self.dimensions()
+
+    @abstractmethod
+    def as_array(self) -> np.ndarray:
+        """Convert to numpy array.
+
+        Returns:
+            np.ndarray: Acquisition data as numpy array
+        """
+        pass
+
+    @abstractmethod
+    def sum(self) -> float:
+        """Sum all values.
+
+        Returns:
+            float: Sum of all counts
+        """
+        pass
+
+    @abstractmethod
+    def max(self) -> float:
+        """Return the maximum bin value.
+
+        Returns:
+            float: Maximum bin value
+        """
+        pass
+
+    @abstractmethod
+    def get_info(self) -> str:
+        """Get metadata information.
+
+        Returns:
+            str: Metadata string
+        """
+        pass
+
+    @abstractmethod
+    def get_energy_window_bounds(self) -> Tuple[float, float]:
+        """Get the energy window bounds for the acquisition.
+
+        Returns:
+            Tuple[float, float]: (lower_threshold, upper_threshold) in keV
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def native_object(self):
+        """Get the underlying native object (AcquisitionData or ProjData)."""
+        pass
+
+    # Arithmetic operations
+    @abstractmethod
+    def __add__(self, other):
+        """Add two acquisition data or acquisition data and scalar."""
+        pass
+
+    @abstractmethod
+    def __sub__(self, other):
+        """Subtract two acquisition data or acquisition data and scalar."""
+        pass
+
+    @abstractmethod
+    def __mul__(self, other):
+        """Multiply acquisition data by scalar or element-wise."""
+        pass
+
+    @abstractmethod
+    def __truediv__(self, other):
+        """Divide acquisition data by scalar or element-wise."""
+        pass
+
+    @abstractmethod
+    def __radd__(self, other):
+        """Right-hand addition."""
+        pass
+
+    @abstractmethod
+    def __rsub__(self, other):
+        """Right-hand subtraction."""
+        pass
+
+    @abstractmethod
+    def __rmul__(self, other):
+        """Right-hand multiplication."""
+        pass
+
+    @abstractmethod
+    def __rtruediv__(self, other):
+        """Right-hand division."""
+        pass
+
+    @abstractmethod
+    def __neg__(self):
+        """Negate acquisition data."""
+        pass
+
+    @abstractmethod
+    def sapyb(
+        self, a: float, y: "AcquisitionDataInterface", b: float
+    ) -> "AcquisitionDataInterface":
+        """Compute self * a + y * b (element-wise), modifying self in place.
+
+        This method modifies self in place: self = self * a + y * b
+
+        Args:
+            a: Scalar multiplier for self
+            y: Other acquisition data
+            b: Scalar multiplier for y
+
+        Returns:
+            AcquisitionDataInterface: self after modification (for chaining)
+        """
+        pass

simind_python_connector/backends/sirf_backend.py

@@ -0,0 +1,309 @@
+"""
+SIRF backend implementation.
+
+Provides wrappers around sirf.STIR.ImageData and sirf.STIR.AcquisitionData
+that conform to the backend interface.
+"""
+
+from typing import Tuple, Union
+
+import numpy as np
+
+from simind_python_connector.utils.import_helpers import get_sirf_types
+
+from .base import AcquisitionDataInterface, ImageDataInterface
+
+
+ImageData, AcquisitionData, SIRF_AVAILABLE = get_sirf_types()
+
+
+class SirfImageData(ImageDataInterface):
+    """Wrapper for sirf.STIR.ImageData."""
+
+    def __init__(self, sirf_obj: ImageData):
+        """Initialize wrapper.
+
+        Args:
+            sirf_obj: SIRF ImageData object
+        """
+        if not SIRF_AVAILABLE:
+            raise ImportError("SIRF is not available")
+        self._obj = sirf_obj
+
+    @classmethod
+    def read_from_file(cls, filepath: str) -> "SirfImageData":
+        """Read image from file."""
+        return cls(ImageData(filepath))
+
+    @classmethod
+    def create_empty(cls) -> "SirfImageData":
+        """Create empty image."""
+        return cls(ImageData())
+
+    def write(self, filepath: str) -> None:
+        """Write to file."""
+        self._obj.write(filepath)
+
+    def fill(self, data: Union[np.ndarray, float, "SirfImageData"]) -> None:
+        """Fill with data."""
+        # Unwrap if data is a wrapped object
+        if isinstance(data, SirfImageData):
+            self._obj.fill(data._obj)
+        else:
+            self._obj.fill(data)
+
+    def clone(self) -> "SirfImageData":
+        """Clone the image."""
+        return SirfImageData(self._obj.clone())
+
+    def get_uniform_copy(self, value: float) -> "SirfImageData":
+        """Create uniform copy."""
+        return SirfImageData(self._obj.get_uniform_copy(value))
+
+    def dimensions(self) -> Tuple[int, int, int]:
+        """Get dimensions as (z, y, x)."""
+        return self._obj.dimensions()
+
+    def voxel_sizes(self) -> Tuple[float, float, float]:
+        """Get voxel sizes as (z, y, x) in mm."""
+        return self._obj.voxel_sizes()
+
+    def as_array(self) -> np.ndarray:
+        """Convert to numpy array."""
+        # Try asarray first (newer SIRF), fall back to as_array
+        if hasattr(self._obj, "asarray"):
+            return self._obj.asarray()
+        else:
+            return self._obj.as_array()
+
+    def sum(self) -> float:
+        """Sum all values."""
+        return float(self._obj.sum())
+
+    def max(self) -> float:
+        """Return the maximum voxel value."""
+        if hasattr(self._obj, "max"):
+            return float(self._obj.max())
+        return float(np.max(self.as_array()))
+
+    def maximum(self, value: float) -> None:
+        """Apply element-wise maximum."""
+        self._obj.maximum(value)
+
+    @property
+    def native_object(self):
+        """Get underlying SIRF object."""
+        return self._obj
+
+    def __repr__(self) -> str:
+        return f"SirfImageData(dims={self.dimensions()})"
+
+    # Arithmetic operations - delegate to native SIRF object
+    def __add__(self, other):
+        if isinstance(other, SirfImageData):
+            return SirfImageData(self._obj + other._obj)
+        else:
+            return SirfImageData(self._obj + other)
+
+    def __sub__(self, other):
+        if isinstance(other, SirfImageData):
+            return SirfImageData(self._obj - other._obj)
+        else:
+            return SirfImageData(self._obj - other)
+
+    def __mul__(self, other):
+        if isinstance(other, SirfImageData):
+            return SirfImageData(self._obj * other._obj)
+        else:
+            return SirfImageData(self._obj * other)
+
+    def __truediv__(self, other):
+        if isinstance(other, SirfImageData):
+            return SirfImageData(self._obj / other._obj)
+        else:
+            return SirfImageData(self._obj / other)
+
+    def __radd__(self, other):
+        return SirfImageData(other + self._obj)
+
+    def __rsub__(self, other):
+        return SirfImageData(other - self._obj)
+
+    def __rmul__(self, other):
+        return SirfImageData(other * self._obj)
+
+    def __rtruediv__(self, other):
+        return SirfImageData(other / self._obj)
+
+    def __neg__(self):
+        return SirfImageData(-self._obj)
+
+    def sapyb(self, a: float, y: "SirfImageData", b: float) -> "SirfImageData":
+        """Compute self * a + y * b (element-wise), modifying self in place.
+
+        Args:
+            a: Scalar multiplier for self
+            y: Other image
+            b: Scalar multiplier for y
+
+        Returns:
+            SirfImageData: self after modification (for chaining)
+        """
+        y_obj = y._obj if isinstance(y, SirfImageData) else y
+        self._obj.sapyb(a, y_obj, b)
+        return self
+
+
+class SirfAcquisitionData(AcquisitionDataInterface):
+    """Wrapper for sirf.STIR.AcquisitionData."""
+
+    def __init__(self, sirf_obj: AcquisitionData):
+        """Initialize wrapper.
+
+        Args:
+            sirf_obj: SIRF AcquisitionData object
+        """
+        if not SIRF_AVAILABLE:
+            raise ImportError("SIRF is not available")
+        self._obj = sirf_obj
+
+    @classmethod
+    def read_from_file(cls, filepath: str) -> "SirfAcquisitionData":
+        """Read acquisition data from file."""
+        return cls(AcquisitionData(filepath))
+
+    @classmethod
+    def create_empty(cls) -> "SirfAcquisitionData":
+        """Create empty acquisition data."""
+        return cls(AcquisitionData())
+
+    def write(self, filepath: str) -> None:
+        """Write to file."""
+        self._obj.write(filepath)
+
+    def fill(self, data: Union[np.ndarray, float, "SirfAcquisitionData"]) -> None:
+        """Fill with data."""
+        # Unwrap if data is a wrapped object
+        if isinstance(data, SirfAcquisitionData):
+            self._obj.fill(data._obj)
+        else:
+            self._obj.fill(data)
+
+    def clone(self) -> "SirfAcquisitionData":
+        """Clone the acquisition data."""
+        return SirfAcquisitionData(self._obj.clone())
+
+    def get_uniform_copy(self, value: float) -> "SirfAcquisitionData":
+        """Create uniform copy."""
+        return SirfAcquisitionData(self._obj.get_uniform_copy(value))
+
+    def dimensions(self) -> Tuple:
+        """Get dimensions."""
+        return self._obj.dimensions()
+
+    def as_array(self) -> np.ndarray:
+        """Convert to numpy array."""
+        # Try asarray first (newer SIRF), fall back to as_array
+        if hasattr(self._obj, "asarray"):
+            return self._obj.asarray()
+        else:
+            return self._obj.as_array()
+
+    def sum(self) -> float:
+        """Sum all values."""
+        return float(self._obj.sum())
+
+    def max(self) -> float:
+        """Return the maximum bin value."""
+        if hasattr(self._obj, "max"):
+            return float(self._obj.max())
+        return float(np.max(self.as_array()))
+
+    def get_info(self) -> str:
+        """Get metadata info."""
+        return self._obj.get_info()
+
+    def get_energy_window_bounds(self) -> Tuple[float, float]:
+        """Get the energy window bounds for the acquisition.
+
+        Returns:
+            Tuple[float, float]: (lower_threshold, upper_threshold) in keV
+
+        Raises:
+            NotImplementedError: SIRF backend does not currently support
+                accessing energy window bounds.
+        """
+        raise NotImplementedError(
+            "SIRF backend does not currently support accessing energy window bounds. "
+            "Use STIR backend for this functionality."
+        )
+
+    def create_uniform_image(self, value: float = 0.0) -> SirfImageData:
+        """Create compatible uniform image."""
+        img = self._obj.create_uniform_image(value)
+        return SirfImageData(img)
+
+    @property
+    def native_object(self):
+        """Get underlying SIRF object."""
+        return self._obj
+
+    def __repr__(self) -> str:
+        return f"SirfAcquisitionData(dims={self.dimensions()})"
+
+    # Arithmetic operations - delegate to native SIRF object
+    def __add__(self, other):
+        if isinstance(other, SirfAcquisitionData):
+            return SirfAcquisitionData(self._obj + other._obj)
+        else:
+            return SirfAcquisitionData(self._obj + other)
+
+    def __sub__(self, other):
+        if isinstance(other, SirfAcquisitionData):
+            return SirfAcquisitionData(self._obj - other._obj)
+        else:
+            return SirfAcquisitionData(self._obj - other)
+
+    def __mul__(self, other):
+        if isinstance(other, SirfAcquisitionData):
+            return SirfAcquisitionData(self._obj * other._obj)
+        else:
+            return SirfAcquisitionData(self._obj * other)
+
+    def __truediv__(self, other):
+        if isinstance(other, SirfAcquisitionData):
+            return SirfAcquisitionData(self._obj / other._obj)
+        else:
+            return SirfAcquisitionData(self._obj / other)
+
+    def __radd__(self, other):
+        return SirfAcquisitionData(other + self._obj)
+
+    def __rsub__(self, other):
+        return SirfAcquisitionData(other - self._obj)
+
+    def __rmul__(self, other):
+        return SirfAcquisitionData(other * self._obj)
+
+    def __rtruediv__(self, other):
+        return SirfAcquisitionData(other / self._obj)
+
+    def __neg__(self):
+        return SirfAcquisitionData(-self._obj)
+
+    def sapyb(
+        self, a: float, y: "SirfAcquisitionData", b: float
+    ) -> "SirfAcquisitionData":
+        """Compute self * a + y * b (element-wise), modifying self in place.
+
+        Args:
+            a: Scalar multiplier for self
+            y: Other acquisition data
+            b: Scalar multiplier for y
+
+        Returns:
+            SirfAcquisitionData: self after modification (for chaining)
+        """
+        y_obj = y._obj if isinstance(y, SirfAcquisitionData) else y
+        self._obj.sapyb(a, y_obj, b)
+        return self