isoview 0.1.0__py3-none-any.whl

isoview/intensity.py

@@ -0,0 +1,427 @@
+"""Intensity correction estimation and application for multi-view fusion."""
+
+import numpy as np
+from typing import Literal, Tuple
+
+from .corrections import percentile_interp
+
+
+def estimate_background(
+    view1: np.ndarray,
+    view2: np.ndarray,
+    percentile: float = 5.0,
+    subsample: int = 100
+) -> float:
+    """
+    Estimate combined background from two views.
+
+    Parameters
+    ----------
+    view1 : ndarray
+        First view (Z, Y, X)
+    view2 : ndarray
+        Second view (Z, Y, X)
+    percentile : float, default=5.0
+        Percentile for background estimation
+    subsample : int, default=100
+        Subsampling factor (use every Nth pixel)
+
+    Returns
+    -------
+    float
+        Background intensity value
+    """
+    # subsample (flatten and take every Nth)
+    flat1 = view1.ravel()[::subsample]
+    flat2 = view2.ravel()[::subsample]
+
+    # combine nonzero pixels from both views
+    valid1 = flat1[flat1 > 0]
+    valid2 = flat2[flat2 > 0]
+    combined = np.concatenate([valid1, valid2])
+
+    if len(combined) == 0:
+        return 0.0
+
+    return float(percentile_interp(combined.astype(np.float64), percentile))
+
+
+def subtract_background(
+    volume: np.ndarray,
+    background: float
+) -> np.ndarray:
+    """
+    Subtract background from volume, clipping to zero.
+
+    Parameters
+    ----------
+    volume : ndarray
+        Input volume (Z, Y, X)
+    background : float
+        Background value to subtract
+
+    Returns
+    -------
+    ndarray
+        Background-subtracted volume, same dtype as input
+    """
+    result = volume.astype(np.float32) - background
+    result = np.maximum(result, 0)
+
+    # preserve original dtype
+    if np.issubdtype(volume.dtype, np.integer):
+        dtype_info = np.iinfo(volume.dtype)
+        result = np.clip(result, dtype_info.min, dtype_info.max)
+
+    return result.astype(volume.dtype)
+
+
+def subtract_background_pair(
+    view1: np.ndarray,
+    view2: np.ndarray,
+    percentile: float = 5.0,
+    subsample: int = 100
+) -> Tuple[np.ndarray, np.ndarray, float]:
+    """
+    Estimate and subtract background from two views.
+
+    Convenience function combining estimate_background and subtract_background.
+
+    Parameters
+    ----------
+    view1 : ndarray
+        First view (Z, Y, X)
+    view2 : ndarray
+        Second view (Z, Y, X)
+    percentile : float, default=5.0
+        Percentile for background estimation
+    subsample : int, default=100
+        Subsampling factor
+
+    Returns
+    -------
+    view1_sub : ndarray
+        Background-subtracted first view
+    view2_sub : ndarray
+        Background-subtracted second view
+    background : float
+        The subtracted background value
+    """
+    background = estimate_background(view1, view2, percentile, subsample)
+    view1_sub = subtract_background(view1, background)
+    view2_sub = subtract_background(view2, background)
+    return view1_sub, view2_sub, background
+
+
+def estimate_intensity_correction(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    ref_mask: np.ndarray,
+    moving_mask: np.ndarray,
+    percentile: float = 5.0,
+    method: Literal["percentile_ratio", "mean_ratio"] = "percentile_ratio"
+) -> dict:
+    """
+    Estimate intensity correction factor between two views.
+
+    Parameters
+    ----------
+    ref_volume : ndarray
+        Reference view (Z, Y, X)
+    moving_volume : ndarray
+        View to correct (Z, Y, X)
+    ref_mask : ndarray
+        Binary mask defining valid regions
+    moving_mask : ndarray
+        Binary mask
+    percentile : float, default=5.0
+        Background estimation percentile
+    method : str, default='percentile_ratio'
+        'percentile_ratio' (robust) or 'mean_ratio' (simple)
+
+    Returns
+    -------
+    dict
+        Contains 'factor', 'operation', 'overlap_correlation', 'method',
+        'ref_background', 'moving_background'
+
+    Notes
+    -----
+    percentile_ratio: find overlap, compute percentile backgrounds,
+    subtract, compute ratio, invert if < 1.
+    Percentile method more robust to outliers.
+    Mean ratio faster but sensitive to background.
+    """
+    if method == "percentile_ratio":
+        return _estimate_correction_percentile(
+            ref_volume, moving_volume, ref_mask, moving_mask, percentile
+        )
+    elif method == "mean_ratio":
+        return _estimate_correction_mean(
+            ref_volume, moving_volume, ref_mask, moving_mask
+        )
+    else:
+        raise ValueError(f"Unknown method: {method}")
+
+
+def _estimate_correction_percentile(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    ref_mask: np.ndarray,
+    moving_mask: np.ndarray,
+    percentile: float
+) -> dict:
+    """
+    Estimate correction using percentile-based background subtraction.
+
+    MATLAB-equivalent: computes factor to multiply moving volume by.
+    If ref is brighter, factor > 1 (multiply moving to match).
+    If moving is brighter, factor < 1 (reduce moving to match).
+    """
+    # get valid (nonzero) pixels from each masked region
+    ref_valid = ref_volume[(ref_mask > 0) & (ref_volume > 0)].astype(np.float64)
+    mov_valid = moving_volume[(moving_mask > 0) & (moving_volume > 0)].astype(np.float64)
+
+    if len(ref_valid) == 0 or len(mov_valid) == 0:
+        return {
+            'factor': 1.0,
+            'operation': 'multiply',
+            'overlap_correlation': 0.0,
+            'method': 'percentile_ratio',
+            'ref_background': 0.0,
+            'moving_background': 0.0
+        }
+
+    combined = np.concatenate([ref_valid, mov_valid])
+    background = percentile_interp(combined, percentile)
+
+    # subtract background
+    ref_fg = np.maximum(ref_valid - background, 0)
+    mov_fg = np.maximum(mov_valid - background, 0)
+
+    ref_sum = ref_fg[ref_fg > 0].sum()
+    mov_sum = mov_fg[mov_fg > 0].sum()
+
+    if mov_sum == 0 or ref_sum == 0:
+        return {
+            'factor': 1.0,
+            'operation': 'multiply',
+            'overlap_correlation': 0.0,
+            'method': 'percentile_ratio',
+            'ref_background': float(background),
+            'moving_background': float(background)
+        }
+
+    # factor to apply to moving volume to match reference
+    # if ref brighter: factor > 1 (scale moving up)
+    # if moving brighter: factor < 1 (scale moving down)
+    factor = ref_sum / mov_sum
+
+    # correlation metric
+    overlap_mask = (ref_mask > 0) & (moving_mask > 0)
+    if overlap_mask.sum() > 0:
+        ref_ovl = ref_volume[overlap_mask].astype(np.float64) - background
+        mov_ovl = moving_volume[overlap_mask].astype(np.float64) - background
+        ref_ovl = np.maximum(ref_ovl, 0)
+        mov_ovl = np.maximum(mov_ovl, 0)
+        if ref_ovl.std() > 0 and mov_ovl.std() > 0:
+            correlation = np.corrcoef(ref_ovl, mov_ovl)[0, 1]
+        else:
+            correlation = 0.0
+    else:
+        correlation = 0.0
+
+    return {
+        'factor': float(factor),
+        'operation': 'multiply',  # always multiply moving by factor
+        'overlap_correlation': float(correlation),
+        'method': 'percentile_ratio',
+        'ref_background': float(background),
+        'moving_background': float(background)
+    }
+
+
+def _estimate_correction_mean(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    ref_mask: np.ndarray,
+    moving_mask: np.ndarray
+) -> dict:
+    """
+    Simple mean ratio correction (no background subtraction).
+
+    Faster but less robust than percentile method.
+    Returns factor to multiply moving volume by to match reference.
+    """
+    # Find overlap region - exclude low intensity pixels
+    # use 5th percentile as threshold to exclude background/edge regions
+    bg_pct = 5.0
+    ref_thresh = percentile_interp(ref_volume[ref_mask > 0].ravel().astype(np.float64), bg_pct) if (ref_mask > 0).any() else 0
+    mov_thresh = percentile_interp(moving_volume[moving_mask > 0].ravel().astype(np.float64), bg_pct) if (moving_mask > 0).any() else 0
+    overlap_mask = (ref_mask > 0) & (moving_mask > 0) & \
+                   (ref_volume > ref_thresh) & (moving_volume > mov_thresh)
+
+    if overlap_mask.sum() == 0:
+        return {
+            'factor': 1.0,
+            'operation': 'multiply',
+            'overlap_correlation': 0.0,
+            'method': 'mean_ratio',
+            'ref_background': 0.0,
+            'moving_background': 0.0
+        }
+
+    # Extract overlap regions
+    ref_overlap = ref_volume[overlap_mask].astype(np.float64)
+    moving_overlap = moving_volume[overlap_mask].astype(np.float64)
+
+    # Compute means
+    ref_mean = ref_overlap.mean()
+    moving_mean = moving_overlap.mean()
+
+    # factor to apply to moving volume to match reference
+    if moving_mean > 0:
+        factor = ref_mean / moving_mean
+    else:
+        factor = 1.0
+
+    # Correlation
+    if ref_overlap.std() > 0 and moving_overlap.std() > 0:
+        ref_norm = (ref_overlap - ref_mean) / ref_overlap.std()
+        moving_norm = (moving_overlap - moving_mean) / moving_overlap.std()
+        correlation = np.mean(ref_norm * moving_norm)
+    else:
+        correlation = 0.0
+
+    return {
+        'factor': float(factor),
+        'operation': 'multiply',  # always multiply moving by factor
+        'overlap_correlation': float(correlation),
+        'method': 'mean_ratio',
+        'ref_background': 0.0,
+        'moving_background': 0.0
+    }
+
+
+def apply_intensity_correction(
+    volume: np.ndarray,
+    correction: dict
+) -> np.ndarray:
+    """
+    Apply intensity correction to volume.
+
+    Parameters
+    ----------
+    volume : ndarray
+        Input volume (Z, Y, X) - the moving volume to correct
+    correction : dict
+        Dict from estimate_intensity_correction with 'factor'
+
+    Returns
+    -------
+    ndarray
+        Corrected volume, same dtype as input
+
+    Notes
+    -----
+    Multiplies volume by factor. Factor > 1 brightens, < 1 dims.
+    """
+    factor = correction['factor']
+
+    # Convert to float for computation
+    corrected = volume.astype(np.float32) * factor
+
+    # Clip to valid range for dtype
+    if np.issubdtype(volume.dtype, np.integer):
+        dtype_info = np.iinfo(volume.dtype)
+        corrected = np.clip(corrected, dtype_info.min, dtype_info.max)
+
+    return corrected.astype(volume.dtype)
+
+
+def apply_median_filter(
+    parameters: np.ndarray,
+    window: int = 100
+) -> np.ndarray:
+    """
+    Apply median filter to parameters across time.
+
+    Parameters
+    ----------
+    parameters : ndarray
+        Parameter values (N,) or (N, M)
+    window : int, default=100
+        Filter window size, 0 to disable
+
+    Returns
+    -------
+    ndarray
+        Filtered parameters
+
+    Notes
+    -----
+    Uses scipy median filter with reflect mode at boundaries.
+    """
+    if window <= 0:
+        return parameters
+
+    from scipy.signal import medfilt
+
+    if parameters.ndim == 1:
+        # Ensure window is odd
+        w = window if window % 2 == 1 else window + 1
+        return medfilt(parameters, kernel_size=w)
+    else:
+        # Filter each column independently
+        filtered = np.zeros_like(parameters)
+        w = window if window % 2 == 1 else window + 1
+        for i in range(parameters.shape[1]):
+            filtered[:, i] = medfilt(parameters[:, i], kernel_size=w)
+        return filtered
+
+
+def apply_gauss_filter(
+    volume: np.ndarray,
+    kernel_size: int = 3,
+    sigma: float = 1.0,
+    precise: bool = True
+) -> np.ndarray:
+    """
+    Apply Gaussian filter to volume.
+
+    Parameters
+    ----------
+    volume : ndarray
+        Input volume (Z, Y, X)
+    kernel_size : int, default=3
+        Kernel size, 0 to disable
+    sigma : float, default=1.0
+        Gaussian sigma
+    precise : bool, default=True
+        True for float64 precision, False for uint16 (faster)
+
+    Returns
+    -------
+    ndarray
+        Filtered volume, same dtype as input
+
+    Notes
+    -----
+    Precise mode recommended for low-intensity data to avoid rounding errors.
+    """
+    if kernel_size <= 0:
+        return volume
+
+    from scipy.ndimage import gaussian_filter
+
+    if precise:
+        filtered = gaussian_filter(volume.astype(np.float64), sigma=sigma)
+    else:
+        filtered = gaussian_filter(volume.astype(np.float32), sigma=sigma)
+
+    # Convert back to original dtype
+    if np.issubdtype(volume.dtype, np.integer):
+        dtype_info = np.iinfo(volume.dtype)
+        filtered = np.clip(filtered, dtype_info.min, dtype_info.max)
+
+    return filtered.astype(volume.dtype)