isoview 0.1.0__py3-none-any.whl

isoview/segmentation.py

@@ -0,0 +1,173 @@
+"""Foreground segmentation for microscopy data."""
+
+import numpy as np
+from scipy.ndimage import convolve1d
+
+from .corrections import percentile_interp
+
+
+def _make_gaussian_kernel(sigma: float, size: int) -> np.ndarray:
+    """Create 1D Gaussian kernel."""
+    half = int(np.ceil(size / 2))
+    x = np.arange(-half, half + 1)
+    kernel = np.exp(-(x ** 2) / (2 * sigma ** 2))
+    return kernel / kernel.sum()
+
+
+def _imgaussian_anisotropy(volume: np.ndarray, sigma: np.ndarray, size: np.ndarray) -> np.ndarray:
+    """Apply separable 3D anisotropic Gaussian filter."""
+    kernel_z = _make_gaussian_kernel(sigma[0], size[0])
+    kernel_y = _make_gaussian_kernel(sigma[1], size[1])
+    kernel_x = _make_gaussian_kernel(sigma[2], size[2])
+
+    result = convolve1d(volume, kernel_z, axis=0, mode='nearest')
+    result = convolve1d(result, kernel_y, axis=1, mode='nearest')
+    result = convolve1d(result, kernel_x, axis=2, mode='nearest')
+
+    return result
+
+
+def segment_foreground(
+    volume: np.ndarray,
+    kernel_sigma: float,
+    kernel_size: int,
+    threshold: float,
+    mask_percentile: float,
+    scaling: float,
+    splitting: int = 10,
+    subsample_factor: int = 100,
+    verbose: bool = False,
+) -> np.ndarray:
+    """Generate binary foreground mask using anisotropic gaussian filtering.
+
+    Args:
+        volume: 3d image stack (z, y, x)
+        kernel_sigma: gaussian sigma in xy
+        kernel_size: gaussian kernel size in xy
+        threshold: adaptive threshold (0-1)
+        mask_percentile: percentile for minimum intensity
+        scaling: z/xy pixel spacing ratio
+        splitting: number of slabs for memory efficiency
+        subsample_factor: subsampling for percentile calculation
+        verbose: print statistics
+
+    Returns:
+        binary mask (uint16: 0 or 1)
+    """
+    sigma_z = max(1.0, kernel_sigma / scaling)
+    size_z = max(1, int(kernel_size / scaling))
+    sigma = np.array([sigma_z, kernel_sigma, kernel_sigma])
+    size = np.array([size_z, kernel_size, kernel_size])
+
+    z_dim, y_dim, x_dim = volume.shape
+    filtered = np.zeros_like(volume, dtype=np.uint16)
+    margin = 2 * kernel_size
+
+    for i in range(splitting):
+        start = max(0, round((i / splitting) * y_dim) - margin)
+        stop = min(y_dim, round(((i + 1) / splitting) * y_dim) + margin)
+
+        slab = volume[:, start:stop, :].astype(np.float64)
+        conv = _imgaussian_anisotropy(slab, sigma, size)
+
+        if i == 0:
+            filtered[:, :stop - margin, :] = np.round(conv[:, : stop - margin - start, :]).astype(np.uint16)
+        elif i == splitting - 1:
+            filtered[:, start + margin:, :] = np.round(conv[:, margin:, :]).astype(np.uint16)
+        else:
+            inner_start = margin
+            inner_stop = stop - start - margin
+            filtered[:, start + margin : stop - margin, :] = np.round(conv[:, inner_start:inner_stop, :]).astype(np.uint16)
+
+    min_intensity = percentile_interp(filtered.ravel()[::subsample_factor], mask_percentile)
+
+    total_sum = 0.0
+    total_count = 0
+    for i in range(splitting):
+        start = round((i / splitting) * y_dim)
+        stop = round(((i + 1) / splitting) * y_dim)
+        slab = filtered[:, start:stop, :]
+        above_min = slab[slab > min_intensity]
+        total_sum += float(above_min.sum())
+        total_count += above_min.size
+
+    mean_intensity = total_sum / total_count if total_count > 0 else min_intensity
+    level = min_intensity + (mean_intensity - min_intensity) * threshold
+
+    mask = (filtered > level).astype(np.uint16)
+
+    if verbose:
+        fg_pct = 100 * mask.sum() / mask.size
+        print(f"foreground: {fg_pct:.1f}%, min={min_intensity:.2f}, mean={mean_intensity:.2f}, level={level:.2f}")
+
+    return mask
+
+
+def fuse_masks(masks: list[np.ndarray]) -> np.ndarray:
+    """Fuse multiple segmentation masks using logical or.
+
+    Args:
+        masks: list of binary masks
+
+    Returns:
+        fused binary mask
+    """
+    if not masks:
+        raise ValueError("no masks to fuse")
+
+    result = masks[0].astype(bool)
+    for mask in masks[1:]:
+        result |= mask.astype(bool)
+
+    return result.astype(np.uint16)
+
+
+def create_coordinate_masks(
+    mask: np.ndarray,
+    splitting: int = 10,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate coordinate masks for interpolation.
+
+    Args:
+        mask: binary foreground mask (z, y, x)
+        splitting: number of slabs to split y-axis for memory-efficient processing
+
+    Returns:
+        xz_mask: shape (y, z), stores mean x coordinate at each (y, z) position
+        xy_mask: shape (y, x), stores mean z coordinate at each (y, x) position
+    """
+    z_size, y_size, x_size = mask.shape
+
+    # xz_mask: (y, z) - for each (y, z), mean x coordinate
+    xz_mask = np.zeros((y_size, z_size), dtype=np.uint16)
+    for i in range(splitting):
+        y_start = round((i / splitting) * y_size)
+        y_stop = round(((i + 1) / splitting) * y_size)
+        slab_height = y_stop - y_start
+
+        # x coordinates: broadcast to (z, slab_height, x)
+        x_coords = np.arange(x_size)[np.newaxis, np.newaxis, :]
+        coord_vol = np.broadcast_to(x_coords, (z_size, slab_height, x_size)).astype(np.float32)
+        coord_vol = np.copy(coord_vol)
+        coord_vol[mask[:, y_start:y_stop, :] == 0] = np.nan
+        # average over x axis (axis=2), result is (z, slab_height)
+        slab_result = np.round(np.nanmean(coord_vol, axis=2)).astype(np.uint16)
+        # transpose to (slab_height, z) and store
+        xz_mask[y_start:y_stop, :] = slab_result.T
+
+    # xy_mask: (y, x) - for each (y, x), mean z coordinate
+    xy_mask = np.zeros((y_size, x_size), dtype=np.uint16)
+    for i in range(splitting):
+        y_start = round((i / splitting) * y_size)
+        y_stop = round(((i + 1) / splitting) * y_size)
+        slab_height = y_stop - y_start
+
+        # z coordinates: broadcast to (z, slab_height, x)
+        z_coords = np.arange(z_size)[:, np.newaxis, np.newaxis]
+        coord_vol = np.broadcast_to(z_coords, (z_size, slab_height, x_size)).astype(np.float32)
+        coord_vol = np.copy(coord_vol)
+        coord_vol[mask[:, y_start:y_stop, :] == 0] = np.nan
+        # average over z axis (axis=0), result is (slab_height, x)
+        xy_mask[y_start:y_stop, :] = np.round(np.nanmean(coord_vol, axis=0)).astype(np.uint16)
+
+    return xz_mask, xy_mask

isoview/temporal.py

@@ -0,0 +1,373 @@
+"""Temporal parameter processing for multi-timepoint fusion."""
+
+import numpy as np
+from typing import Optional
+from scipy.signal import savgol_filter
+
+
+def smooth_parameters_rloess(
+    timepoints: np.ndarray,
+    parameters: np.ndarray,
+    window_size: int = 100
+) -> np.ndarray:
+    """
+    Apply robust locally-weighted scatterplot smoothing to parameters.
+
+    Parameters
+    ----------
+    timepoints : ndarray
+        Time point indices (N,)
+    parameters : ndarray
+        Parameter values (N,) or (N, M) for M parameters
+    window_size : int, default=100
+        Smoothing window size
+
+    Returns
+    -------
+    ndarray
+        Smoothed parameters, same shape as input
+
+    Notes
+    -----
+    Uses Savitzky-Golay filter as approximation to rloess.
+    Window size adjusted to odd number if needed.
+    """
+    if parameters.ndim == 1:
+        parameters = parameters[:, np.newaxis]
+        squeeze = True
+    else:
+        squeeze = False
+
+    N, M = parameters.shape
+    smoothed = np.zeros_like(parameters)
+
+    # Ensure window size is odd and valid
+    window = min(window_size, N)
+    if window % 2 == 0:
+        window -= 1
+    if window < 3:
+        return parameters.squeeze() if squeeze else parameters
+
+    # Apply savgol filter to each parameter column
+    for m in range(M):
+        valid_mask = ~np.isnan(parameters[:, m])
+        if valid_mask.sum() < window:
+            smoothed[:, m] = parameters[:, m]
+            continue
+
+        # Apply filter only to valid values
+        smoothed[valid_mask, m] = savgol_filter(
+            parameters[valid_mask, m],
+            window_length=min(window, valid_mask.sum()),
+            polyorder=2,
+            mode='interp'
+        )
+        # Preserve NaN locations
+        smoothed[~valid_mask, m] = np.nan
+
+    return smoothed.squeeze() if squeeze else smoothed
+
+
+def interpolate_missing_timepoints(
+    full_interval: np.ndarray,
+    measured_timepoints: np.ndarray,
+    measured_parameters: np.ndarray
+) -> np.ndarray:
+    """
+    Interpolate parameters for missing timepoints.
+
+    Parameters
+    ----------
+    full_interval : ndarray
+        All timepoints to fill (M,)
+    measured_timepoints : ndarray
+        Timepoints with measurements (N,)
+    measured_parameters : ndarray
+        Parameter values at measured timepoints (N,) or (N, P)
+
+    Returns
+    -------
+    ndarray
+        Parameters for all timepoints (M,) or (M, P)
+
+    Notes
+    -----
+    Uses distance-weighted linear interpolation between nearest neighbors.
+    If no neighbors on both sides, uses nearest value.
+    """
+    if measured_parameters.ndim == 1:
+        measured_parameters = measured_parameters[:, np.newaxis]
+        squeeze = True
+    else:
+        squeeze = False
+
+    M = len(full_interval)
+    _, P = measured_parameters.shape
+    interpolated = np.zeros((M, P))
+
+    for i, tp in enumerate(full_interval):
+        if tp in measured_timepoints:
+            # Direct measurement available
+            idx = np.where(measured_timepoints == tp)[0][0]
+            interpolated[i, :] = measured_parameters[idx, :]
+        else:
+            # Interpolate from neighbors
+            distances = measured_timepoints - tp
+            positive_dist = distances * (distances > 0)
+            negative_dist = distances * (distances < 0)
+
+            has_upper = np.any(positive_dist > 0)
+            has_lower = np.any(negative_dist < 0)
+
+            if has_upper and has_lower:
+                # Interpolate between neighbors
+                upper_idx = np.argmin(positive_dist[positive_dist > 0])
+                lower_idx = np.argmax(negative_dist[negative_dist < 0])
+
+                # Get actual indices in measured arrays
+                upper_idx = np.where(positive_dist == positive_dist[positive_dist > 0][upper_idx])[0][0]
+                lower_idx = np.where(negative_dist == negative_dist[negative_dist < 0][lower_idx])[0][0]
+
+                upper_dist = measured_timepoints[upper_idx] - tp
+                lower_dist = tp - measured_timepoints[lower_idx]
+
+                # Distance-weighted interpolation
+                total_dist = upper_dist + lower_dist
+                upper_weight = lower_dist / total_dist
+                lower_weight = upper_dist / total_dist
+
+                interpolated[i, :] = (
+                    upper_weight * measured_parameters[upper_idx, :] +
+                    lower_weight * measured_parameters[lower_idx, :]
+                )
+            else:
+                # Use nearest neighbor
+                abs_dist = np.abs(distances)
+                nearest_idx = np.argmin(abs_dist)
+                interpolated[i, :] = measured_parameters[nearest_idx, :]
+
+    return interpolated.squeeze() if squeeze else interpolated
+
+
+def apply_temporal_averaging(
+    parameters: np.ndarray,
+    offset_range: int = 10,
+    angle_range: int = 10,
+    intensity_range: int = 5,
+    method: str = "median",
+    parameter_types: Optional[list[str]] = None
+) -> np.ndarray:
+    """
+    Apply temporal averaging with different windows per parameter type.
+
+    Parameters
+    ----------
+    parameters : ndarray
+        Parameter matrix (T, P) for T timepoints and P parameters
+    offset_range : int, default=10
+        Averaging range for spatial offsets
+    angle_range : int, default=10
+        Averaging range for rotation angles
+    intensity_range : int, default=5
+        Averaging range for intensity correction
+    method : str, default='median'
+        Averaging method: 'median' or 'mean'
+    parameter_types : list of str or None
+        Type of each parameter: 'offset', 'angle', 'intensity', 'flag'
+        If None, assumes first params are offsets, then angles, then intensity
+
+    Returns
+    -------
+    ndarray
+        Averaged parameters (T, P)
+
+    Notes
+    -----
+    Flags are not averaged, just copied.
+    Each parameter type uses its own temporal window.
+    """
+    T, P = parameters.shape
+    averaged = np.zeros_like(parameters)
+
+    # Default parameter type assignment if not provided
+    if parameter_types is None:
+        # Assume typical order: offsets, angles, intensity, flags
+        parameter_types = ['offset'] * min(3, P)
+        if P > 3:
+            parameter_types.append('angle')
+        if P > 4:
+            parameter_types.append('intensity')
+        if P > 5:
+            parameter_types.extend(['flag'] * (P - 5))
+
+    for p, ptype in enumerate(parameter_types):
+        if ptype == 'flag':
+            # Flags not averaged
+            averaged[:, p] = parameters[:, p]
+            continue
+
+        # Determine window size
+        if ptype == 'offset':
+            window = offset_range
+        elif ptype == 'angle':
+            window = angle_range
+        elif ptype == 'intensity':
+            window = intensity_range
+        else:
+            window = offset_range  # default
+
+        # Apply temporal averaging
+        for t in range(T):
+            t_start = max(0, t - window)
+            t_end = min(T, t + window + 1)
+            window_data = parameters[t_start:t_end, p]
+
+            # Remove NaN values
+            valid_data = window_data[~np.isnan(window_data)]
+
+            if len(valid_data) == 0:
+                averaged[t, p] = np.nan
+            elif method == 'median':
+                averaged[t, p] = np.median(valid_data)
+            elif method == 'mean':
+                averaged[t, p] = np.mean(valid_data)
+            else:
+                raise ValueError(f"Unknown averaging method: {method}")
+
+    return averaged
+
+
+def compute_static_parameters(
+    parameters: np.ndarray,
+    method: str = "mean"
+) -> np.ndarray:
+    """
+    Compute static (time-averaged) parameters.
+
+    Parameters
+    ----------
+    parameters : ndarray
+        Parameter matrix (T, P)
+    method : str, default='mean'
+        Averaging method: 'mean' or 'median'
+
+    Returns
+    -------
+    ndarray
+        Static parameters (T, P) with same value for all timepoints
+
+    Notes
+    -----
+    Computes global average across all timepoints, then broadcasts to all times.
+    Useful for datasets with minimal drift.
+    """
+    T, P = parameters.shape
+
+    if method == 'mean':
+        static_values = np.nanmean(parameters, axis=0)
+    elif method == 'median':
+        static_values = np.nanmedian(parameters, axis=0)
+    else:
+        raise ValueError(f"Unknown method: {method}")
+
+    # Broadcast to all timepoints
+    static_params = np.tile(static_values, (T, 1))
+
+    return static_params
+
+
+def create_lookup_table(
+    timepoints: np.ndarray,
+    transformations: dict,
+    intensity_corrections: dict,
+    mode: str = 'camera'
+) -> dict:
+    """
+    Create lookup table from transformation and intensity correction data.
+
+    Parameters
+    ----------
+    timepoints : ndarray
+        Time point indices
+    transformations : dict
+        Dict mapping timepoints to transformation dicts
+    intensity_corrections : dict
+        Dict mapping timepoints to intensity correction dicts
+    mode : str, default='camera'
+        Fusion mode: 'camera', 'channel', or 'full'
+
+    Returns
+    -------
+    dict
+        Lookup table with arrays for each parameter
+
+    Notes
+    -----
+    Includes timepoint column and all transformation/intensity parameters.
+    """
+    N = len(timepoints)
+
+    # Initialize lookup table
+    lookup = {
+        'timepoints': timepoints.copy(),
+        'x_offset': np.zeros(N),
+        'y_offset': np.zeros(N),
+        'z_offset': np.zeros(N),
+        'rotation': np.zeros(N),
+        'correlation': np.zeros(N),
+        'intensity_factor': np.ones(N),
+        'intensity_operation': np.zeros(N, dtype=int),
+        'intensity_correlation': np.zeros(N)
+    }
+
+    # Fill from dictionaries
+    for i, tp in enumerate(timepoints):
+        if tp in transformations:
+            t = transformations[tp]
+            lookup['x_offset'][i] = t.get('x_offset', 0.0)
+            lookup['y_offset'][i] = t.get('y_offset', 0.0)
+            lookup['z_offset'][i] = t.get('z_offset', 0.0)
+            lookup['rotation'][i] = t.get('rotation', 0.0)
+            lookup['correlation'][i] = t.get('correlation', 0.0)
+
+        if tp in intensity_corrections:
+            ic = intensity_corrections[tp]
+            lookup['intensity_factor'][i] = ic.get('factor', 1.0)
+            # Convert operation to flag: multiply=2, divide=1
+            op = ic.get('operation', 'multiply')
+            lookup['intensity_operation'][i] = 2 if op == 'multiply' else 1
+            lookup['intensity_correlation'][i] = ic.get('overlap_correlation', 0.0)
+
+    return lookup
+
+
+def save_lookup_table(
+    lookup_table: dict,
+    output_path: str,
+    format: str = 'npz'
+) -> None:
+    """
+    Save lookup table to file.
+
+    Parameters
+    ----------
+    lookup_table : dict
+        Lookup table from create_lookup_table
+    output_path : str
+        Output file path
+    format : str, default='npz'
+        File format: 'npz' or 'csv'
+
+    Notes
+    -----
+    NPZ format preserves all data types and is compact.
+    CSV format is human-readable but loses precision.
+    """
+    if format == 'npz':
+        np.savez(output_path, **lookup_table)
+    elif format == 'csv':
+        import pandas as pd
+        df = pd.DataFrame(lookup_table)
+        df.to_csv(output_path, index=False)
+    else:
+        raise ValueError(f"Unknown format: {format}")