mri-normalization-tools 0.4.1__py3-none-any.whl

mnts/__init__.py

@@ -0,0 +1,9 @@
+import SimpleITK as sitk
+sitk.ProcessObject_GlobalWarningDisplayOff()
+
+from . import filters
+from . import io
+from . import utils
+
+__all__ = ['filters', 'io', 'utils']
+

mnts/filters/__init__.py

@@ -0,0 +1,9 @@
+from .mnts_filters import *
+from .mnts_filters_graph import *
+from .mpi_wrapper import *
+from .data_node import *
+
+from . import geom
+from . import intensity
+
+__all__ = ['geom', 'intensity']

mnts/filters/data_node.py

@@ -0,0 +1,119 @@
+from .mnts_filters import *
+from typing import Any, Optional
+import SimpleITK as sitk
+
+__all__ = ["TypeCastNode", "DataNode"]
+
+# SimpleITK >= 2.x inserted `outputPixelType` as the 2nd positional arg to Clamp.
+# Detect once at import time so the right call path is used regardless of version.
+_SITK_CLAMP_HAS_OUTPUT_TYPE = "outputPixelType" in (sitk.Clamp.__doc__ or "")
+
+def _sitk_clamp(image: sitk.Image, lower: float, upper: float) -> sitk.Image:
+    if _SITK_CLAMP_HAS_OUTPUT_TYPE:
+        return sitk.Clamp(image, sitk.sitkUnknown, lower, upper)
+    return sitk.Clamp(image, lower, upper)
+
+class DataNode(MNTSFilter):
+    r"""
+    Presents whatever data stored in this node. This is useful for storing intermediate results, or other data that
+    are repeatedly accessed without the need of re-computing. This can be used as the entrance node in the directed
+    graphs. See :class:`MNTSFilterGraph` for more.
+    """
+    def __init__(self, data=None):
+        super(DataNode, self).__init__()
+        self.data = data
+
+    @property
+    def data(self):
+        return self._data
+
+    @data.setter
+    def data(self, input: Any):
+        self._logger.info(f"Setting data ({type(input)}) {input}")
+        if isinstance(input, str):
+            input = self.read_image(input)
+        self._data = input
+
+    def clear_data(self):
+        self._data = None
+
+    def filter(self,
+               input: str or sitk.Image) -> Any:
+        self.data = input
+        return self.data
+
+class TypeCastNode(MNTSFilter):
+    r"""
+    A class to cast the type to a specific datatype using `sitk.Cast`.
+    It is recommended to keep a clear track of the type casting within a pipeline or a graph.
+
+    Attributes:
+        target_type (int): The target type to which the input will be casted.
+        target_type_name (str): The name of the target type.
+    """
+    def __init__(self,
+                 target_type: int = sitk.sitkInt16):
+        self._target_type = target_type
+        self._target_type_name = sitk.GetPixelIDValueAsString(self._target_type)
+        self._overflow_protection = {
+            sitk.sitkUInt8:     (0, int(2**8.) - 1),
+            sitk.sitkUInt16:    (0, int(2**16.) - 1),
+            sitk.sitkUInt32:    (0, int(2**32.) - 1),
+            sitk.sitkUInt64:    (0, int(2**64.) - 1),
+            sitk.sitkInt8:      (-int(2**7.), int(2**7.) -1),
+            sitk.sitkInt16:     (-int(2**15.), int(2 ** 15.) - 1),
+            sitk.sitkInt32:     (-int(2**31.), int(2 ** 31.) - 1),
+            sitk.sitkInt64:     (-int(2**63.), int(2 ** 63.) - 1)
+            # Ignore float numbers
+        }
+
+    @property
+    def target_type(self) -> Any:
+        r"""Return the target type as sitk code."""
+        return self._target_type
+
+    @target_type.setter
+    def target_type(self, val) -> None:
+        r"""Set the target type with sitk codes."""
+        self._target_type = val
+
+    @property
+    def target_type_name(self) -> str:
+        r"""Return the target type as string."""
+        return self._target_type_name
+
+    def filter(self, input: sitk.Image, ref_img: Optional[sitk.Image]=None) -> sitk.Image:
+        """Filter method to cast the type of the input.
+
+        If `ref_img` is not None, then the type cast references the type of it.
+        Otherwise, the type is casted as the attribute `self._target_type`.
+
+        Args:
+            input (sitk.Image):
+                The input to be casted.
+            ref_img (sitk.Image, optional):
+                The reference image to determine the type. Defaults to None.
+
+        Returns:
+            The input casted to the target type.
+
+        Raises:
+            ArithmeticError: If the type cast fails.
+        """
+        input = self.read_image(input)
+        target_type = self._target_type if ref_img is None else ref_img.GetPixelID()
+        try:
+            # Overflow protection
+            range = self._overflow_protection.get(target_type, None)
+            if range is not None:
+                f = sitk.MinimumMaximumImageFilter()
+                f.Execute(input)
+
+                max_val = f.GetMaximum()
+                min_val = f.GetMinimum()
+
+                if max_val > range[1] or min_val < range[0]:
+                    input = _sitk_clamp(input, range[0], range[1])
+            return sitk.Cast(input, self._target_type)
+        except Exception as e:
+            raise ArithmeticError(f"Type cast failed in filter with parameters: {self.__str__()}") from e

mnts/filters/geom/__init__.py

@@ -0,0 +1,3 @@
+from .spatial_norm import *
+from .geom_mask_crop import *
+from .reorient_filter import *

mnts/filters/geom/geom_mask_crop.py

@@ -0,0 +1,276 @@
+import SimpleITK as sitk
+import numpy as np
+from pathlib import Path
+from typing import Union, Tuple, Optional
+from ..mnts_filters import MNTSFilter
+
+
+__all__ = ['RemoveShoulder']
+
+
+class RemoveShoulder(MNTSFilter):
+    r"""
+    A geometric filter that takes a mask and calculates the slice area along a specified dimension,
+    then crops the 3D volume to a single slice along that dimension.
+
+    This filter finds the slice with the smallest mask area along the specified dimension and
+    reduces the 3D volume to just that single slice. The search of slice is done from inferior to superior
+    for identifying the shoulder. To prevent top slices (top of the head) to be accidentedly selected, a
+    barrier setting is implement that protects the top n slices from being selected.
+
+    The filter only crops along the specified dimension, leaving the other two dimensions at full size.
+    This is useful for extracting representative slices for analysis or preprocessing.
+
+    Attributes:
+        min_area_threshold (float):
+            Minimum area threshold as a fraction of the maximum area. Slices with area below
+            this threshold will be ignored to avoid noise. Default is 0.1 (10% of max area).
+
+        barrier (int):
+            Number of slices to count downwards from when searching for the minimum area slice.
+            The search starts from the end of the volume and works backwards by this many slices.
+            Default is 10 slices.
+
+        [Experimental] dimension (int):
+            This is fixed to 0 until a better way of fixing the direction of nifti is found.
+
+    Example:
+        >>> from mnts.filters.geom import RemoveShoulder
+        >>> crop_filter = RemoveShoulder(barrier=15, dimension=0)
+        >>> cropped_image = crop_filter.filter(image, mask)
+    """
+
+    def __init__(self,
+                  min_area_threshold: float = 0.1,
+                  barrier: int = 10):
+        super(RemoveShoulder, self).__init__()
+        self.min_area_threshold = min_area_threshold
+        self.barrier = barrier
+        self.dimension = 0 # This is now fixed
+
+        self._is_reversed = False
+
+    @property
+    def min_area_threshold(self):
+        return self._min_area_threshold
+
+    @min_area_threshold.setter
+    def min_area_threshold(self, threshold: float):
+        if not 0 <= threshold <= 1:
+            raise ValueError("Min area threshold must be between 0 and 1")
+        self._min_area_threshold = threshold
+        
+    @property
+    def barrier(self):
+        return self._barrier
+    
+    @barrier.setter
+    def barrier(self, val: float):
+        assert 0 <= val
+        self._barrier = val
+        
+    def filter(self,
+               image: Union[str, Path, sitk.Image],
+               mask: Union[str, Path, sitk.Image]) -> sitk.Image:
+        """
+        Apply geometric mask-based cropping to the input image.
+        """
+        image = self.read_image(image)
+        mask = self.read_image(mask)
+        size_before = image.GetSize()
+
+        if image.GetSize() != mask.GetSize():
+            raise RuntimeError("Image and mask must have the same dimensions")
+
+        if image.GetSpacing() != mask.GetSpacing():
+            self._logger.warning("Image and mask have different spacing. Using image spacing for output.")
+        if image.GetDirection() != mask.GetDirection():
+            self._logger.warning("Image and mask have different direction. Using image direction for output.")
+        if image.GetOrigin() != mask.GetOrigin():
+            self._logger.warning("Image and mask have different origin. Using image origin for output.")
+
+        # Cache geometry
+        self._image_spacing   = image.GetSpacing()   # [sx           , sy , sz]
+        self._image_origin    = image.GetOrigin()    # [ox           , oy , oz]
+        self._image_direction = image.GetDirection() # 3x3 flattened
+
+
+        # Determine orientation for the specified dimension
+        orientation = sitk.DICOMOrientImageFilter_GetOrientationFromDirectionCosines(image.GetDirection())
+        # Map dimension to orientation string index (dimension 0->z->2, 1->y->1, 2->x->0)
+        orient_idx = 2 - self.dimension
+        axis_orientation = orientation[orient_idx]
+
+        # Determine if Superior is at high or low index
+        # For anatomy: S (Superior) should be at high index in standard orientation
+        # If axis is I (Inferior), then Superior is at low index (reversed)
+        self._is_reversed = axis_orientation == 'I' if self.dimension == 0 else \
+                            axis_orientation == 'A' if self.dimension == 1 else \
+                            axis_orientation == 'L'
+
+        self._logger.info(f"Orientation: {orientation}, Dimension {self.dimension} axis: {axis_orientation}, Reversed: {self._is_reversed}")
+
+        mask_array = sitk.GetArrayFromImage(mask)  # numpy order [z, y, x]
+        if mask_array.ndim != 3:
+            raise ValueError("Mask must be 3D.")
+        if np.count_nonzero(mask_array) == 0:
+            raise ValueError("Mask is empty (all zeros).")
+
+        slice_areas = self._calculate_slice_areas(mask_array)
+        if slice_areas.size == 0 or np.all(slice_areas == 0):
+            raise ValueError("All slice areas are zero; cannot determine cropping slice.")
+        self._logger.info(f"Slice areas: {slice_areas}")
+
+        min_slice_idx = self._find_minimum_area_slice(slice_areas)
+        if min_slice_idx is None:
+            raise ValueError("No valid slice found with sufficient area. Check mask quality or thresholds.")
+
+        crop_bounds = self._get_cropping_bounds(mask_array, min_slice_idx)
+        cropped_image = self._crop_image(image, crop_bounds)
+
+        self._logger.info(f"Cropped image at slice {min_slice_idx} with bounds: {crop_bounds}. Original {size_before} -> New {cropped_image.GetSize()}")
+        return cropped_image
+
+    def _calculate_slice_areas(self, mask_array: np.ndarray) -> np.ndarray:
+        """
+        Calculate physical area (mm^2) per slice along given dimension.
+        numpy array is [z, y, x]; dimension: 0=z, 1=y, 2=x
+        Pixel size is need to handle anisotropic situation
+        """
+        # Spacing in SITK is [sx, sy, sz]; array dims are [z, y, x]
+        sx, sy, sz = self._image_spacing
+
+        # Pixel area is the product of the spacings in the two axes orthogonal to the slicing axis
+        if self.dimension == 0:      # slicing along z => area in y-x plane
+            pixel_area = sy * sx
+        elif self.dimension == 1:    # slicing along y => area in z-x plane
+            pixel_area = sz * sx
+        else:                         # slicing along x => area in z-y plane
+            pixel_area = sz * sy
+
+        num_slices = mask_array.shape[self.dimension]
+        areas = np.zeros(num_slices, dtype=np.float64)
+
+        for i in range(num_slices):
+            if self.dimension == 0:
+                slice_data = mask_array[i, :, :]     # [y, x]
+            elif self.dimension == 1:
+                slice_data = mask_array[:, i, :]     # [z, x]
+            else:  # self.dimension == 2
+                slice_data = mask_array[:, :, i]     # [z, y]
+            areas[i] = np.count_nonzero(slice_data) * pixel_area
+
+        # Replace 0 with max value to ignore empty slices
+        max_area = areas.max() if areas.max() > 0 else 1.0
+        areas[areas == 0] = max_area
+        self._logger.debug(f"Calculated areas: {areas}")
+        return areas
+
+    def _find_minimum_area_slice(self, slice_areas: np.ndarray) -> Optional[int]:
+        """
+        Apply threshold and barrier to find minimal area slice index.
+        Barrier is applied from the Superior end (where shoulders typically are).
+        """
+        if slice_areas.size == 0:
+            return None
+
+        max_area = float(np.max(slice_areas))
+        if max_area <= 0.0:
+            self._logger.warning("Maximum slice area is zero.")
+            return None
+
+        min_threshold = max_area * self.min_area_threshold
+
+        # Determine Superior end based on orientation
+        n = len(slice_areas)
+        if self.barrier >= n:
+            self._logger.warning(f"Barrier ({self.barrier}) >= number of slices ({n}), no valid indices.")
+            return None
+
+        # Superior (where head are) determination:
+        # If NOT reversed: Superior is at high index (end of array), crop from low index
+        # If reversed: Superior is at low index (start of array), crop from high index
+        if not self._is_reversed:
+            # S -> Superior at high index, apply barrier from end
+            superior_barrier_idx = n - int(self.barrier)
+            candidate_indices = np.arange(0, superior_barrier_idx)
+        else:
+            # I -> Superior at low index, apply barrier from start
+            superior_barrier_idx = int(self.barrier)
+            candidate_indices = np.arange(superior_barrier_idx, n)
+
+        if len(candidate_indices) == 0:
+            self._logger.warning("No candidate indices after applying barrier.")
+            return None
+
+        valid_mask = slice_areas[candidate_indices] >= min_threshold
+        if not np.any(valid_mask):
+            self._logger.warning("No slices meet the minimum area threshold after applying barrier.")
+            return None
+
+        valid_indices = candidate_indices[valid_mask]
+        min_idx_rel = int(np.argmin(slice_areas[valid_indices]))
+        min_slice_idx = int(valid_indices[min_idx_rel])
+
+        self._logger.info(
+            f"Found minimum area slice at index {min_slice_idx} "
+            f"(area={slice_areas[min_slice_idx]:.3f}, max={max_area:.3f}, barrier={self.barrier}, reversed={self._is_reversed})"
+        )
+        return min_slice_idx
+
+    def _get_cropping_bounds(self, mask_array: np.ndarray, min_slice_idx: int) -> Tuple[list, list]:
+        """
+        Build crop bounds as (lower_crop, upper_crop) for SimpleITK.Crop().
+        Crops from Superior (shoulder side) to the minimum area slice.
+
+        Returns:
+            Tuple of (lower_crop, upper_crop) where each is a list [x, y, z] of integers.
+        """
+        # Validate the selected slice has mask content
+        if self.dimension == 0:
+            min_slice = mask_array[min_slice_idx, :, :]
+        elif self.dimension == 1:
+            min_slice = mask_array[:, min_slice_idx, :]
+        else:
+            min_slice = mask_array[:, :, min_slice_idx]
+
+        if np.count_nonzero(min_slice) == 0:
+            raise ValueError(f"No mask pixels found in slice {min_slice_idx}")
+
+        # Calculate crop bounds in SimpleITK order [x, y, z]
+        # mask_array.shape is [z, y, x] in numpy order
+        n_slices = mask_array.shape[self.dimension]
+
+        # Determine which end to crop from based on orientation
+        if not self._is_reversed:
+            # S -> Superior at high index: crop from low index up to min_slice_idx
+            # Keep slices [min_slice_idx, end], remove [0, min_slice_idx-1]
+            crop_from_start = min_slice_idx
+            crop_from_end = 0
+        else:
+            # I -> Superior at low index: crop from high (inferior) index down to min_slice_idx
+            # Keep slices [0, min_slice_idx], remove [min_slice_idx+1, end]
+            crop_from_end = n_slices - min_slice_idx - 1
+            crop_from_start = 0
+
+        # Build crop parameters in SimpleITK order [x, y, z]
+        if self.dimension == 0:  # z-axis
+            lower_crop = [0, 0, crop_from_start]
+            upper_crop = [0, 0, crop_from_end]
+        elif self.dimension == 1:  # y-axis
+            lower_crop = [0, crop_from_start, 0]
+            upper_crop = [0, crop_from_end, 0]
+        else:  # x-axis
+            lower_crop = [crop_from_start, 0, 0]
+            upper_crop = [crop_from_end, 0, 0]
+
+        self._logger.debug(f"Cropping bounds: lower={lower_crop}, upper={upper_crop} (keeping slice {min_slice_idx})")
+        return (lower_crop, upper_crop)
+
+    def _crop_image(self, image: sitk.Image, crop_bounds: Tuple[list, list]) -> sitk.Image:
+        """
+        Crop using SimpleITK Crop with lower and upper crop parameters.
+        """
+        lower_crop, upper_crop = crop_bounds
+        cropped_img = sitk.Crop(image, lower_crop, upper_crop)
+        return cropped_img

mnts/filters/geom/reorient_filter.py

@@ -0,0 +1,49 @@
+import SimpleITK as sitk
+import numpy as np
+import re
+from pathlib import Path
+from typing import Union, Tuple, Optional
+from ..mnts_filters import MNTSFilter
+
+
+__all__ = ['ReorientFilter']
+
+class ReorientFilter(MNTSFilter):
+    r"""
+    A wrapper for sitk.DICOMOrient
+
+    Attributes:
+        target_orientation (str):
+            A three character string representing orientation code. E.g., 'LPS'.
+    """
+    def __init__(self, target_orientation: str = 'RAI'):
+        super(ReorientFilter, self).__init__()
+        self.target_orientation = target_orientation
+
+    @property
+    def target_orientation(self):
+        return self._target_orientation
+
+    @target_orientation.setter
+    def target_orientation(self, val: str):
+        assert isinstance(val, str), "Input must be a string of three characters"
+        assert re.fullmatch(r"(?i)[railps]{3}", val) is not None, \
+            f"Input must be a three-character orientation code using R/L, A/P, I/S, got '{val}'"
+        self._target_orientation = val.upper()
+
+    def filter(self,
+               image: Union[str, sitk.Image],
+               mask: Union[str, sitk.Image] = None):
+        """
+        Apply DICOMOrient filter to both inputs
+        """
+        image = self.read_image(image)
+        mask = self.read_image(mask) if mask is not None else None
+
+        ori_filter = sitk.DICOMOrientImageFilter()
+        ori_filter.SetDesiredCoordinateOrientation(self._target_orientation)
+
+        if mask is not None:
+            return (ori_filter.Execute(image), ori_filter.Execute(mask))
+        else:
+            return ori_filter.Execute(image)

mnts/filters/geom/spatial_norm.py

@@ -0,0 +1,89 @@
+import SimpleITK as sitk
+import numpy as np
+from pathlib import Path
+from typing import Union, Tuple
+from ..mnts_filters import MNTSFilter
+
+
+__all__ = ['SpatialNorm']
+
+class SpatialNorm(MNTSFilter):
+    r"""
+    This class utilize the SimpleITK filter `ResampleImageFilter` to change the spacing. All other factors remains
+    unchanged. However, note that the floating point rounding might results in slightly different image dimension, so
+    this filter should be used with the cropping filter if you require uniform data size.
+
+    Attributes:
+        out_spacing (float, tuple of floats):
+            Desired uniform spacing. Unit is mm. Use 0 or negative values if spacing is to be kept
+
+    """
+    def __init__(self,
+                 out_spacing: Union[float, Tuple[float, float, float]] = None,
+                 interpolation_method: str = 'linear'):
+        super(SpatialNorm, self).__init__()
+        self.out_spacing = out_spacing
+        self._interpolation_names = {
+            'linear': sitk.sitkLinear,
+            'bspline': sitk.sitkBSpline,
+            'nearest': sitk.sitkNearestNeighbor,
+        }
+        self._interpolation = self._interpolation_names[interpolation_method]
+
+
+    @property
+    def out_spacing(self):
+        return self._out_spacing
+
+    @out_spacing.setter
+    def out_spacing(self, out_spacing: Union[float, Tuple[float, float, float]]):
+        self._out_spacing = out_spacing if isinstance(out_spacing, (list, tuple)) else [out_spacing]*3
+
+    @property
+    def interpolation(self):
+        return list(self._interpolation_names.keys())[
+            list(self._interpolation_names.values()).index(self._interpolation)
+        ]
+
+    @interpolation.setter
+    def interpolation(self, val):
+        if isinstance(val, str):
+            self._interpolation = self._interpolation_names.get(val, 'linear')
+        else:
+            assert val in self._interpolation_names.values(), f"{val} is not in available methods " \
+                                                              f"{self._interpolation_names}"
+            self._interpolation = val
+
+        if not self._interpolation in self._interpolation_names.values():
+            raise IndexError(f"Incorrect interpolation scheme specified, possible options are:"
+                             f"{list(self._interpolation_names.keys())}, , got '{val}' instead.")
+
+
+    def filter(self,
+               input: Union[str, Path, sitk.Image]
+               ):
+        input = self.read_image(input)
+
+        original_size = np.asarray(input.GetSize())
+        original_spacing = np.asarray(input.GetSpacing())
+
+        # Keep spacing if there's a negative value in out_spacing
+        new_spacing = np.asarray(self.out_spacing, dtype='float')
+        new_spacing[new_spacing <= 0] = original_spacing[new_spacing <=0]
+        new_size = np.round((original_size * original_spacing) / new_spacing).astype('int').tolist()
+        self._logger.info(f"\n"
+                          f"\tSiz \t{original_size} \t-> {new_size}\n"
+                          f"\tSpc \t{original_spacing} \t-> {new_spacing}")
+
+        # For segmentation, force to use nearest neighbor to avoid funny results.
+        if input.GetPixelID() == sitk.sitkUInt8:
+            self._interpolation = sitk.sitkNearestNeighbor
+
+        f = sitk.ResampleImageFilter()
+        f.SetReferenceImage(input)
+        f.SetOutputSpacing(new_spacing.tolist())
+        f.SetSize(new_size)
+        f.SetInterpolator(self._interpolation)
+        out = f.Execute(input)
+        return out
+

mnts/filters/intensity/__init__.py

@@ -0,0 +1,7 @@
+from .linear_rescale import *
+from .linear_z_score import *
+from .range_rescale import *
+from .masking import *
+from .hist_piecewise import *
+from .n4_bias_field_correction import *
+from .si_rebinning import *