isoview 0.1.0__py3-none-any.whl

isoview/masks.py

@@ -0,0 +1,421 @@
+"""Binary mask creation from unsegmented data for fusion."""
+
+import numpy as np
+from scipy import ndimage
+from skimage.morphology import remove_small_objects, disk
+
+from .corrections import percentile_interp
+
+
+def create_fusion_mask(
+    volume: np.ndarray,
+    percentile: float = 5.0,
+    mask_factor: float = 1.0,
+    min_size: int | None = None,
+    morphology_iterations: int = 1
+) -> np.ndarray:
+    """
+    Create binary mask from unsegmented volume.
+
+    Args:
+        volume: input volume (Z, Y, X)
+        percentile: percentile for background estimation (default: 5.0)
+        mask_factor: threshold factor (default: 1.0)
+            threshold = min + mask_factor * (mean - min)
+        min_size: minimum object size (voxels), None = auto (0.1% of volume)
+        morphology_iterations: closing iterations for cleanup (default: 1)
+
+    Returns:
+        binary mask (Z, Y, X)
+
+    Algorithm:
+        1. Estimate minimum intensity using percentile (avoid true min)
+        2. Compute mean of values above minimum
+        3. Threshold at: min + mask_factor * (mean - min)
+        4. Apply morphological closing to fill holes
+        5. Remove small objects
+
+    Notes:
+        - percentile=5 is typical for noisy data
+        - mask_factor=1.0 means threshold at mean
+        - mask_factor=0.5 means threshold halfway between min and mean
+    """
+    # Estimate minimum using percentile to avoid outliers
+    min_intensity = percentile_interp(volume.ravel().astype(np.float64), percentile)
+
+    # Compute mean of values above minimum
+    above_min = volume[volume > min_intensity]
+    if len(above_min) > 0:
+        mean_intensity = above_min.mean()
+    else:
+        mean_intensity = volume.mean()
+
+    # Threshold
+    threshold = min_intensity + mask_factor * (mean_intensity - min_intensity)
+    mask = volume > threshold
+
+    # Morphological closing to fill small holes
+    if morphology_iterations > 0:
+        structure = ndimage.generate_binary_structure(3, 1)  # 3D connectivity
+        mask = ndimage.binary_closing(
+            mask,
+            structure=structure,
+            iterations=morphology_iterations
+        )
+
+    # Remove small objects
+    if min_size is None:
+        # Auto: 0.1% of volume
+        min_size = int(0.001 * volume.size)
+
+    if min_size > 0:
+        # Label connected components
+        labeled, num_features = ndimage.label(mask)
+
+        # Compute sizes
+        sizes = ndimage.sum(mask, labeled, range(1, num_features + 1))
+
+        # Remove small components
+        mask_sizes = sizes < min_size
+        remove_indices = mask_sizes.nonzero()[0] + 1  # +1 because labels start at 1
+        mask[np.isin(labeled, remove_indices)] = 0
+
+    return mask.astype(np.uint8)
+
+
+def create_slice_mask(
+    volume: np.ndarray,
+    binary_mask: np.ndarray
+) -> np.ndarray:
+    """
+    Create slice topology mask from binary 3D mask for camera fusion.
+
+    Args:
+        volume: input volume (Z, Y, X)
+        binary_mask: binary mask (Z, Y, X)
+
+    Returns:
+        slice mask (Y, X) containing Z-indices of average mask position
+
+    Algorithm:
+        For each (y, x) pixel:
+        1. Extract Z-profile of binary mask
+        2. Compute weighted average Z-position
+        3. Store in (y, x) array
+
+    Notes:
+        This creates the transition plane topology used for adaptive blending.
+        For camera fusion: blending along Z, mask is (Y, X) with Z-values.
+        Returns 0 where no mask exists.
+    """
+    Z, Y, X = volume.shape
+    slice_mask = np.zeros((Y, X), dtype=np.uint16)
+
+    for y in range(Y):
+        for x in range(X):
+            # get Z-profile of mask at this (y, x)
+            z_profile = binary_mask[:, y, x]
+
+            if z_profile.sum() == 0:
+                # no mask at this (y, x)
+                slice_mask[y, x] = 0
+            else:
+                # compute weighted average Z-position
+                z_indices = np.arange(Z)
+                weighted_z = (z_indices * z_profile).sum() / z_profile.sum()
+                slice_mask[y, x] = int(round(weighted_z))
+
+    return slice_mask
+
+
+def create_channel_slice_mask(
+    volume: np.ndarray,
+    binary_mask: np.ndarray
+) -> np.ndarray:
+    """
+    Create slice topology mask from binary 3D mask for channel fusion.
+
+    Args:
+        volume: input volume (Z, Y, X)
+        binary_mask: binary mask (Z, Y, X)
+
+    Returns:
+        slice mask (X, Z) containing Y-indices of average mask position
+
+    Algorithm:
+        For each (x, z) pixel:
+        1. Extract Y-profile of binary mask
+        2. Compute weighted average Y-position
+        3. Store in (x, z) array
+
+    Notes:
+        For channel fusion: blending along Y (XZ plane), mask is (X, Z) with Y-values.
+        This matches MATLAB multiFuse behavior for channel-channel fusion.
+        Returns 0 where no mask exists.
+    """
+    Z, Y, X = volume.shape
+    slice_mask = np.zeros((X, Z), dtype=np.uint16)
+
+    # vectorized implementation for speed
+    y_indices = np.arange(Y)
+
+    for x in range(X):
+        for z in range(Z):
+            # get Y-profile of mask at this (x, z)
+            y_profile = binary_mask[z, :, x]
+
+            if y_profile.sum() == 0:
+                slice_mask[x, z] = 0
+            else:
+                # compute weighted average Y-position
+                weighted_y = (y_indices * y_profile).sum() / y_profile.sum()
+                slice_mask[x, z] = int(round(weighted_y))
+
+    return slice_mask
+
+
+def create_average_mask(
+    slice_mask1: np.ndarray,
+    slice_mask2: np.ndarray,
+    mode: str = "overlap"
+) -> np.ndarray:
+    """
+    Create average transition mask from two slice masks.
+
+    Args:
+        slice_mask1: first slice mask with position values
+        slice_mask2: second slice mask with position values
+        mode: 'overlap' (average only where both exist) or
+              'union' (average where either exists)
+
+    Returns:
+        average mask with same shape as inputs
+
+    Notes:
+        - mode='overlap': conservative, only fuse where both masks exist
+        - mode='union': aggressive, fuse wherever signal exists
+        - works for both camera masks (Y, X) and channel masks (X, Z)
+    """
+    average_mask = np.zeros(slice_mask1.shape, dtype=np.uint16)
+
+    if mode == "overlap":
+        # average only where both exist
+        both_valid = (slice_mask1 > 0) & (slice_mask2 > 0)
+        average_mask[both_valid] = (slice_mask1[both_valid].astype(np.int32) +
+                                     slice_mask2[both_valid].astype(np.int32)) // 2
+    elif mode == "union":
+        # average where both exist
+        both_valid = (slice_mask1 > 0) & (slice_mask2 > 0)
+        average_mask[both_valid] = (slice_mask1[both_valid].astype(np.int32) +
+                                     slice_mask2[both_valid].astype(np.int32)) // 2
+        # use single value where only one exists
+        only1 = (slice_mask1 > 0) & (slice_mask2 == 0)
+        only2 = (slice_mask1 == 0) & (slice_mask2 > 0)
+        average_mask[only1] = slice_mask1[only1]
+        average_mask[only2] = slice_mask2[only2]
+    else:
+        raise ValueError(f"Unknown mode: {mode}")
+
+    return average_mask
+
+
+def remove_mask_anomalies(
+    slice_mask: np.ndarray,
+    dim_size: int,
+    blending_range: int
+) -> np.ndarray:
+    """
+    Remove anomalies from slice mask (values too close to dimension edges).
+
+    Args:
+        slice_mask: slice mask with position values
+        dim_size: size of the dimension being blended (Z for camera, Y for channel)
+        blending_range: blending range in pixels
+
+    Returns:
+        cleaned mask with same shape as input
+
+    Notes:
+        Sets to 0 any mask values that are:
+        - Less than effective_range from front (pos=0)
+        - Less than effective_range from back (pos=dim_size)
+
+        Automatically reduces blending range if volume is too small.
+    """
+    cleaned = slice_mask.copy()
+
+    # automatically reduce blending range if volume is too small
+    # need at least 2*blending_range + 1 for a valid transition zone
+    max_blending = (dim_size - 1) // 2
+    effective_range = min(blending_range, max_blending)
+
+    if effective_range <= 0:
+        # volume too small for any blending, keep all valid values
+        return cleaned
+
+    # remove values too close to front
+    cleaned[cleaned < effective_range] = 0
+
+    # remove values too close to back
+    cleaned[cleaned > (dim_size - effective_range)] = 0
+
+    return cleaned
+
+
+def apply_bwareaopen(
+    mask: np.ndarray,
+    fraction: float = 1e-5
+) -> np.ndarray:
+    """
+    Remove small objects from binary mask using area threshold.
+
+    Parameters
+    ----------
+    mask : ndarray
+        Binary mask (Z, Y, X)
+    fraction : float, default=1e-5
+        Minimum object size as fraction of total volume
+
+    Returns
+    -------
+    ndarray
+        Cleaned binary mask
+
+    Notes
+    -----
+    Set fraction=0 to disable.
+    """
+    if fraction <= 0:
+        return mask
+
+    min_size = int(fraction * mask.size)
+    if min_size < 1:
+        return mask
+
+    return remove_small_objects(mask.astype(bool), min_size=min_size).astype(mask.dtype)
+
+
+def pad_mask_to_center(
+    mask: np.ndarray,
+    mode: int = 0,
+    disk_radius: int = 50
+) -> np.ndarray:
+    """
+    Pad mask edges toward center coordinate.
+
+    Parameters
+    ----------
+    mask : ndarray
+        Binary mask (Z, Y, X)
+    mode : int, default=0
+        0: no padding
+        1: replace zeros with center coordinate
+        2: smooth padding toward center with disk element
+    disk_radius : int, default=50
+        Radius for disk structuring element in smooth mode
+
+    Returns
+    -------
+    ndarray
+        Padded mask
+
+    Notes
+    -----
+    Mode 2 creates smooth transition zone using morphological dilation
+    with disk structuring element.
+    """
+    if mode == 0:
+        return mask
+
+    Z, Y, X = mask.shape
+    center_z = Z // 2
+    center_y = Y // 2
+    center_x = X // 2
+
+    if mode == 1:
+        # Replace zeros with center coordinate
+        padded = mask.copy()
+        padded[padded == 0] = 1
+        return padded
+
+    elif mode == 2:
+        # Smooth padding with disk element
+        # Create 3D structuring element (disk in each slice)
+        struct = np.zeros((3, 2*disk_radius+1, 2*disk_radius+1), dtype=bool)
+        disk_elem = disk(disk_radius)
+        for i in range(3):
+            struct[i, :, :] = disk_elem
+
+        # Dilate mask
+        padded = ndimage.binary_dilation(mask, structure=struct)
+        return padded.astype(mask.dtype)
+
+    else:
+        raise ValueError(f"Unknown padding mode: {mode}")
+
+
+def combine_masks(
+    mask1: np.ndarray,
+    mask2: np.ndarray,
+    mode: int = 1
+) -> np.ndarray:
+    """
+    Combine two binary masks for fusion.
+
+    Parameters
+    ----------
+    mask1 : ndarray
+        First binary mask (Z, Y, X)
+    mask2 : ndarray
+        Second binary mask (Z, Y, X)
+    mode : int, default=1
+        0: use only overlap regions
+        1: combine full information from both masks (union)
+
+    Returns
+    -------
+    ndarray
+        Combined binary mask
+
+    Notes
+    -----
+    Mode 0: conservative, only regions where both masks agree
+    Mode 1: aggressive, regions where either mask has signal
+    """
+    if mode == 0:
+        # Overlap only
+        return (mask1 & mask2).astype(mask1.dtype)
+    elif mode == 1:
+        # Union
+        return (mask1 | mask2).astype(mask1.dtype)
+    else:
+        raise ValueError(f"Unknown mask fusion mode: {mode}")
+
+
+def subsample_for_percentile(
+    volume: np.ndarray,
+    slice_subsample: int = 1,
+    stack_subsample: int = 100
+) -> np.ndarray:
+    """
+    Subsample volume for percentile computation.
+
+    Parameters
+    ----------
+    volume : ndarray
+        Input volume (Z, Y, X)
+    slice_subsample : int, default=1
+        Take every Nth pixel in Y and X
+    stack_subsample : int, default=100
+        Take every Nth slice in Z
+
+    Returns
+    -------
+    ndarray
+        Subsampled volume
+
+    Notes
+    -----
+    Reduces memory for percentile calculation on large volumes.
+    """
+    return volume[::stack_subsample, ::slice_subsample, ::slice_subsample]