isoview 0.1.0__py3-none-any.whl

isoview/transforms.py

@@ -0,0 +1,1115 @@
+from typing import Optional, Literal
+
+import numpy as np
+from scipy import ndimage
+from scipy.ndimage import map_coordinates
+from skimage.registration import phase_cross_correlation
+
+
+# -----------------------------------------------------------------------------
+# matlab-equivalent transform functions
+# -----------------------------------------------------------------------------
+
+def transform_channel_slice(
+    slice2d: np.ndarray,
+    z_offset: float,
+    rotation_deg: float,
+    scaling: float = 1.0
+) -> np.ndarray:
+    """
+    Transform 2D slice (XZ plane) with z-offset and rotation.
+
+    Equivalent to MATLAB transformChannel - applies rotation around center
+    then z translation. Used for channel-channel fusion.
+
+    Parameters
+    ----------
+    slice2d : ndarray
+        2D slice (X, Z) from XZ plane (one Y slice)
+    z_offset : float
+        Z offset in pixels
+    rotation_deg : float
+        Rotation angle in degrees
+    scaling : float
+        Axial/lateral pixel ratio for anisotropic voxels
+
+    Returns
+    -------
+    ndarray
+        Transformed slice (X, Z)
+    """
+    x_size, z_size = slice2d.shape
+
+    # create coordinate grids
+    xi, zi = np.meshgrid(np.arange(x_size), np.arange(z_size), indexing='ij')
+
+    # center coordinates
+    cx = (x_size - 1) / 2.0
+    cz = (z_size - 1) / 2.0
+
+    # center the grid
+    xi_c = xi - cx
+    zi_c = zi - cz
+
+    # rotation matrix (matches MATLAB convention)
+    # matlab uses: RR = [cos sin; -sin cos] with XZaux = (RR * [X; Z]')'
+    # which gives: X_new = cos*x + sin*z, Z_new = -sin*x + cos*z
+    theta = np.deg2rad(rotation_deg)
+    cos_t = np.cos(theta)
+    sin_t = np.sin(theta)
+
+    # apply anisotropic scaling, rotate, then unscale
+    xi_scaled = xi_c
+    zi_scaled = zi_c * scaling
+
+    # rotate (matlab convention: X_new = cos*x + sin*z, Z_new = -sin*x + cos*z)
+    xi_rot = cos_t * xi_scaled + sin_t * zi_scaled
+    zi_rot = -sin_t * xi_scaled + cos_t * zi_scaled
+
+    # unscale and recenter
+    xi_new = xi_rot + cx
+    zi_new = (zi_rot / scaling) + cz - z_offset
+
+    # interpolate
+    coords = np.array([xi_new.ravel(), zi_new.ravel()])
+    transformed = map_coordinates(
+        slice2d.astype(np.float64), coords, order=3, mode='constant', cval=0
+    ).reshape(slice2d.shape)
+
+    # mask out-of-bounds
+    valid = (xi_new >= 0) & (xi_new < x_size) & (zi_new >= 0) & (zi_new < z_size)
+    transformed = transformed * valid
+
+    return transformed.astype(slice2d.dtype)
+
+
+def transform_camera_slice(
+    slice2d: np.ndarray,
+    x_offset: float,
+    y_offset: float,
+    rotation_deg: float
+) -> np.ndarray:
+    """
+    Transform 2D slice (XY plane) with x/y offset and rotation.
+
+    Equivalent to MATLAB transformCamera - applies rotation around center
+    then x/y translation. Used for camera-camera fusion.
+
+    Parameters
+    ----------
+    slice2d : ndarray
+        2D slice (X, Y) from XY plane (one Z slice)
+    x_offset : float
+        X offset in pixels
+    y_offset : float
+        Y offset in pixels
+    rotation_deg : float
+        Rotation angle in degrees around Z axis
+
+    Returns
+    -------
+    ndarray
+        Transformed slice (X, Y)
+    """
+    x_size, y_size = slice2d.shape
+
+    # create coordinate grids
+    xi, yi = np.meshgrid(np.arange(x_size), np.arange(y_size), indexing='ij')
+
+    # center coordinates
+    cx = (x_size - 1) / 2.0
+    cy = (y_size - 1) / 2.0
+
+    # center the grid
+    xi_c = xi - cx
+    yi_c = yi - cy
+
+    # rotation matrix (matches MATLAB convention)
+    # matlab uses: RR = [cos -sin; sin cos] with XYaux = [X Y] * RR
+    # which gives: X_new = cos*x + sin*y, Y_new = -sin*x + cos*y
+    theta = np.deg2rad(rotation_deg)
+    cos_t = np.cos(theta)
+    sin_t = np.sin(theta)
+
+    # rotate around center (matlab convention: X_new = cos*x + sin*y, Y_new = -sin*x + cos*y)
+    xi_rot = cos_t * xi_c + sin_t * yi_c
+    yi_rot = -sin_t * xi_c + cos_t * yi_c
+
+    # recenter and apply translation
+    xi_new = xi_rot + cx - x_offset
+    yi_new = yi_rot + cy - y_offset
+
+    # interpolate
+    coords = np.array([xi_new.ravel(), yi_new.ravel()])
+    transformed = map_coordinates(
+        slice2d.astype(np.float64), coords, order=3, mode='constant', cval=0
+    ).reshape(slice2d.shape)
+
+    # mask out-of-bounds
+    valid = (xi_new >= 0) & (xi_new < x_size) & (yi_new >= 0) & (yi_new < y_size)
+    transformed = transformed * valid
+
+    return transformed.astype(slice2d.dtype)
+
+
+def _correlation_cost_channel(
+    params: np.ndarray,
+    slice1: np.ndarray,
+    slice2: np.ndarray,
+    scaling: float
+) -> float:
+    """
+    Cost function for channel alignment optimization.
+
+    Equivalent to MATLAB transformChannel objective function.
+    Returns negative correlation (for minimization).
+
+    Parameters
+    ----------
+    params : ndarray
+        [z_offset, rotation_deg]
+    slice1 : ndarray
+        Reference slice (X, Z)
+    slice2 : ndarray
+        Moving slice (X, Z)
+    scaling : float
+        Axial/lateral pixel ratio
+
+    Returns
+    -------
+    float
+        Negative normalized correlation coefficient
+    """
+    z_offset, rotation_deg = params
+
+    transformed = transform_channel_slice(slice2, z_offset, rotation_deg, scaling)
+
+    # compute correlation on valid region
+    valid = (transformed > 0) & (slice1 > 0)
+    if valid.sum() < 100:
+        return 1.0  # invalid, return worst case
+
+    s1 = slice1[valid].astype(np.float64)
+    s2 = transformed[valid].astype(np.float64)
+
+    # normalized correlation
+    s1_norm = s1 - s1.mean()
+    s2_norm = s2 - s2.mean()
+
+    std1 = s1_norm.std()
+    std2 = s2_norm.std()
+
+    if std1 < 1e-8 or std2 < 1e-8:
+        return 1.0
+
+    corr = np.mean(s1_norm * s2_norm) / (std1 * std2)
+    return -corr
+
+
+def _correlation_cost_camera(
+    params: np.ndarray,
+    slice1: np.ndarray,
+    slice2: np.ndarray
+) -> float:
+    """
+    Cost function for camera alignment optimization.
+
+    Equivalent to MATLAB transformCamera objective function.
+    Returns negative correlation (for minimization).
+
+    Parameters
+    ----------
+    params : ndarray
+        [x_offset, y_offset, rotation_deg]
+    slice1 : ndarray
+        Reference slice (X, Y)
+    slice2 : ndarray
+        Moving slice (X, Y)
+
+    Returns
+    -------
+    float
+        Negative normalized correlation coefficient
+    """
+    x_offset, y_offset, rotation_deg = params
+
+    transformed = transform_camera_slice(slice2, x_offset, y_offset, rotation_deg)
+
+    # compute correlation on valid region
+    valid = (transformed > 0) & (slice1 > 0)
+    if valid.sum() < 100:
+        return 1.0
+
+    s1 = slice1[valid].astype(np.float64)
+    s2 = transformed[valid].astype(np.float64)
+
+    s1_norm = s1 - s1.mean()
+    s2_norm = s2 - s2.mean()
+
+    std1 = s1_norm.std()
+    std2 = s2_norm.std()
+
+    if std1 < 1e-8 or std2 < 1e-8:
+        return 1.0
+
+    corr = np.mean(s1_norm * s2_norm) / (std1 * std2)
+    return -corr
+
+
+def gradient_descent_optimize(
+    cost_fn,
+    x0: np.ndarray,
+    step_size: np.ndarray,
+    tol_x: float = 1e-3,
+    tol_fun: float = 1e-6,
+    max_evals: int = 400,
+    beta: float = 0.5
+) -> tuple[np.ndarray, float, int]:
+    """
+    Gradient descent optimizer with adaptive step size.
+
+    Equivalent to MATLAB fminuncFA by Fernando Amat.
+    Uses numerical gradient and line search with backtracking.
+
+    Parameters
+    ----------
+    cost_fn : callable
+        Cost function f(x) -> float to minimize
+    x0 : ndarray
+        Initial parameter vector
+    step_size : ndarray
+        Step size for each parameter (for gradient estimation)
+    tol_x : float
+        Convergence tolerance for parameter change
+    tol_fun : float
+        Convergence tolerance for function value change
+    max_evals : int
+        Maximum number of function evaluations
+    beta : float
+        Line search backtracking factor
+
+    Returns
+    -------
+    x_sol : ndarray
+        Optimal parameters
+    f_val : float
+        Optimal function value
+    exit_flag : int
+        1=converged (function), 2=converged (x), 3=max evals
+    """
+    n = len(x0)
+    x = x0.copy().astype(np.float64)
+    step_size = np.asarray(step_size, dtype=np.float64)
+
+    alpha = 1.0  # adaptive multiplier for line search
+    num_eval = 0
+
+    f0 = cost_fn(x)
+    num_eval += 1
+
+    # track best found
+    f_best = f0
+    x_best = x.copy()
+
+    while num_eval < max_evals:
+        # compute gradient numerically
+        g = np.zeros(n)
+        for k in range(n):
+            h = np.zeros(n)
+            h[k] = step_size[k]
+
+            fp = cost_fn(x + h)
+            num_eval += 1
+            if fp < f_best:
+                f_best = fp
+                x_best = x + h
+
+            fm = cost_fn(x - h)
+            num_eval += 1
+            if fm < f_best:
+                f_best = fm
+                x_best = x - h
+
+            g[k] = (fp - fm) / (2.0 * step_size[k])
+
+        # line search
+        g_norm = np.linalg.norm(g)
+        if g_norm < 1e-10:
+            break
+
+        mu = alpha * 5.0 * np.min(np.abs(step_size / (g + 1e-10)))
+        f1 = cost_fn(x - mu * g)
+        num_eval += 1
+
+        aux_alpha = 1.0
+        while f1 > f0 and np.linalg.norm(mu * g) > tol_x:
+            mu *= beta
+            f1 = cost_fn(x - mu * g)
+            num_eval += 1
+            aux_alpha *= beta
+
+        # update adaptive alpha
+        alpha = 0.3 * alpha + 0.7 * alpha * aux_alpha
+
+        # check convergence
+        if np.linalg.norm(mu * g) < tol_x and f_best + tol_fun >= min(f1, f0):
+            if f1 < f0:
+                return x - mu * g, f1, 2
+            else:
+                return x, f0, 2
+
+        if abs(f1 - f0) / (abs(f0) + 1e-10) < tol_fun and f_best + tol_fun >= min(f1, f0):
+            if f1 < f0:
+                return x - mu * g, f1, 1
+            else:
+                return x, f0, 1
+
+        # update position
+        if f1 <= f_best:
+            x = x - mu * g
+            f0 = f1
+        else:
+            x = x_best.copy()
+            f0 = f_best
+
+        f_best = f0
+        x_best = x.copy()
+
+    return x, f0, 3
+
+
+def estimate_channel_transform(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    scaling: float = 1.0,
+    y_slice: Optional[int] = None,
+    optimizer: Literal["gradient_descent", "nelder_mead", "bfgs"] = "gradient_descent",
+    slab_size: int = 0,
+    verbose: bool = False
+) -> dict:
+    """
+    Estimate channel-channel alignment transform (z-offset + rotation).
+
+    Equivalent to MATLAB channel alignment in multiFuse.
+    Works on XZ slices (one Y plane) to find optimal z-offset and rotation.
+
+    Parameters
+    ----------
+    ref_volume : ndarray
+        Reference volume (Z, Y, X)
+    moving_volume : ndarray
+        Moving volume (Z, Y, X)
+    scaling : float
+        Axial/lateral pixel ratio (z_spacing / xy_spacing)
+    y_slice : int or None
+        Y slice to use for registration. None uses center slice.
+    optimizer : str
+        'gradient_descent' (MATLAB fminuncFA), 'nelder_mead', or 'bfgs'
+    slab_size : int
+        Number of Y slices to average for more robust estimation. 0 = single slice.
+    verbose : bool
+        Print debug information.
+
+    Returns
+    -------
+    dict
+        Contains 'z_offset', 'rotation', 'correlation', 'method'
+    """
+    z_size, y_size, x_size = ref_volume.shape
+
+    if y_slice is None:
+        y_slice = y_size // 2
+
+    # extract XZ slice(s) at specified Y
+    if slab_size > 0:
+        # average over a slab of Y slices for robustness
+        half = slab_size // 2
+        y_start = max(0, y_slice - half)
+        y_end = min(y_size, y_slice + half + 1)
+        slice1 = ref_volume[:, y_start:y_end, :].mean(axis=1).T.astype(np.float64)
+        slice2 = moving_volume[:, y_start:y_end, :].mean(axis=1).T.astype(np.float64)
+        if verbose:
+            print(f"        Using Y slab [{y_start}:{y_end}] ({y_end-y_start} slices)")
+    else:
+        # single slice
+        slice1 = ref_volume[:, y_slice, :].T.astype(np.float64)      # (X, Z)
+        slice2 = moving_volume[:, y_slice, :].T.astype(np.float64)   # (X, Z)
+
+    if verbose:
+        print(f"        slice1: shape={slice1.shape}, range=[{slice1.min():.1f}, {slice1.max():.1f}], mean={slice1.mean():.1f}")
+        print(f"        slice2: shape={slice2.shape}, range=[{slice2.min():.1f}, {slice2.max():.1f}], mean={slice2.mean():.1f}")
+        # compute initial correlation at identity
+        valid = (slice1 > 0) & (slice2 > 0)
+        if valid.sum() > 100:
+            s1 = slice1[valid]
+            s2 = slice2[valid]
+            s1_n = (s1 - s1.mean()) / (s1.std() + 1e-8)
+            s2_n = (s2 - s2.mean()) / (s2.std() + 1e-8)
+            init_corr = np.mean(s1_n * s2_n)
+            print(f"        Initial correlation at identity: {init_corr:.3f} ({valid.sum()} valid pixels)")
+
+    # initial guess
+    x0 = np.array([0.0, 0.0])  # [z_offset, rotation_deg]
+    step_size = np.array([1.0, 0.1])
+
+    cost_fn = lambda p: _correlation_cost_channel(p, slice1, slice2, scaling)
+
+    if optimizer == "gradient_descent":
+        x_sol, f_val, _ = gradient_descent_optimize(cost_fn, x0, step_size)
+    elif optimizer == "nelder_mead":
+        from scipy.optimize import minimize
+        result = minimize(cost_fn, x0, method='Nelder-Mead',
+                         options={'xatol': 1e-3, 'fatol': 1e-6, 'maxfev': 400})
+        x_sol = result.x
+        f_val = result.fun
+    elif optimizer == "bfgs":
+        from scipy.optimize import minimize
+        result = minimize(cost_fn, x0, method='BFGS',
+                         options={'gtol': 1e-6, 'maxiter': 200})
+        x_sol = result.x
+        f_val = result.fun
+    else:
+        raise ValueError(f"Unknown optimizer: {optimizer}")
+
+    return {
+        'z_offset': float(x_sol[0]),
+        'rotation': float(x_sol[1]),
+        'correlation': float(-f_val),
+        'scaling': scaling,
+        'method': f'channel_{optimizer}'
+    }
+
+
+def estimate_camera_transform(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    search_x: tuple[int, int, int] = (-50, 50, 10),
+    search_y: tuple[int, int, int] = (-50, 50, 10),
+    z_slice: Optional[int] = None,
+    optimizer: Literal["gradient_descent", "nelder_mead", "bfgs"] = "gradient_descent"
+) -> dict:
+    """
+    Estimate camera-camera alignment transform (x/y offset + rotation).
+
+    Equivalent to MATLAB camera alignment in multiFuse.
+    Uses coarse grid search then fine optimization with rotation.
+
+    Parameters
+    ----------
+    ref_volume : ndarray
+        Reference volume (Z, Y, X)
+    moving_volume : ndarray
+        Moving volume (Z, Y, X)
+    search_x : tuple
+        (start, stop, step) for coarse x search
+    search_y : tuple
+        (start, stop, step) for coarse y search
+    z_slice : int or None
+        Z slice to use. None uses MIP (max intensity projection).
+    optimizer : str
+        'gradient_descent' (MATLAB fminuncFA), 'nelder_mead', or 'bfgs'
+
+    Returns
+    -------
+    dict
+        Contains 'x_offset', 'y_offset', 'rotation', 'correlation', 'method'
+    """
+    z_size, y_size, x_size = ref_volume.shape
+
+    # get representative XY slice
+    if z_slice is None:
+        # use max intensity projection
+        slice1 = ref_volume.max(axis=0).astype(np.float64).T      # (X, Y)
+        slice2 = moving_volume.max(axis=0).astype(np.float64).T   # (X, Y)
+    else:
+        slice1 = ref_volume[z_slice, :, :].T.astype(np.float64)   # (X, Y)
+        slice2 = moving_volume[z_slice, :, :].T.astype(np.float64)
+
+    # coarse grid search (no rotation)
+    x_offsets = np.arange(search_x[0], search_x[1] + 1, search_x[2])
+    y_offsets = np.arange(search_y[0], search_y[1] + 1, search_y[2])
+
+    best_corr = -np.inf
+    best_x = 0.0
+    best_y = 0.0
+
+    intensity_ref = slice1.sum()
+
+    for x_off in x_offsets:
+        # shift in x
+        if x_off >= 0:
+            shifted_x = np.zeros_like(slice2)
+            shifted_x[x_off:, :] = slice2[:-x_off or None, :]
+        else:
+            shifted_x = np.zeros_like(slice2)
+            shifted_x[:x_off, :] = slice2[-x_off:, :]
+
+        for y_off in y_offsets:
+            # shift in y
+            if y_off >= 0:
+                shifted = np.zeros_like(shifted_x)
+                shifted[:, y_off:] = shifted_x[:, :-y_off or None]
+            else:
+                shifted = np.zeros_like(shifted_x)
+                shifted[:, :y_off] = shifted_x[:, -y_off:]
+
+            intensity_shifted = shifted.sum()
+            if intensity_shifted < 1e-10:
+                continue
+
+            # normalized intensity product correlation (MATLAB style)
+            product = slice1 * shifted
+            corr = product.sum() / (intensity_ref * intensity_shifted + 1e-10)
+
+            if corr > best_corr:
+                best_corr = corr
+                best_x = float(x_off)
+                best_y = float(y_off)
+
+    # fine optimization with rotation starting from coarse result
+    x0 = np.array([best_x, best_y, 0.0])  # [x_offset, y_offset, rotation_deg]
+    step_size = np.array([1.0, 1.0, 0.1])
+
+    cost_fn = lambda p: _correlation_cost_camera(p, slice1, slice2)
+
+    if optimizer == "gradient_descent":
+        x_sol, f_val, _ = gradient_descent_optimize(cost_fn, x0, step_size)
+    elif optimizer == "nelder_mead":
+        from scipy.optimize import minimize
+        result = minimize(cost_fn, x0, method='Nelder-Mead',
+                         options={'xatol': 1e-3, 'fatol': 1e-6, 'maxfev': 400})
+        x_sol = result.x
+        f_val = result.fun
+    elif optimizer == "bfgs":
+        from scipy.optimize import minimize
+        result = minimize(cost_fn, x0, method='BFGS',
+                         options={'gtol': 1e-6, 'maxiter': 200})
+        x_sol = result.x
+        f_val = result.fun
+    else:
+        raise ValueError(f"Unknown optimizer: {optimizer}")
+
+    return {
+        'x_offset': float(x_sol[0]),
+        'y_offset': float(x_sol[1]),
+        'z_offset': 0.0,
+        'rotation': float(x_sol[2]),
+        'correlation': float(-f_val),
+        'coarse_x': best_x,
+        'coarse_y': best_y,
+        'method': f'camera_{optimizer}'
+    }
+
+
+def apply_channel_transform(
+    volume: np.ndarray,
+    transform: dict,
+    scaling: float = 1.0
+) -> np.ndarray:
+    """
+    Apply channel transform (z-offset + rotation) to full volume.
+
+    Transforms each XZ slice (for each Y) with the same z-offset and rotation.
+
+    Parameters
+    ----------
+    volume : ndarray
+        Input volume (Z, Y, X)
+    transform : dict
+        Contains 'z_offset' and 'rotation'
+    scaling : float
+        Axial/lateral pixel ratio
+
+    Returns
+    -------
+    ndarray
+        Transformed volume (Z, Y, X)
+    """
+    z_offset = transform.get('z_offset', 0.0)
+    rotation = transform.get('rotation', 0.0)
+    scaling = transform.get('scaling', scaling)
+
+    z_size, y_size, x_size = volume.shape
+    result = np.zeros_like(volume)
+
+    for y in range(y_size):
+        # extract XZ slice, transform, put back
+        slice_xz = volume[:, y, :].T  # (X, Z)
+        transformed = transform_channel_slice(slice_xz, z_offset, rotation, scaling)
+        result[:, y, :] = transformed.T  # back to (Z, X)
+
+    return result
+
+
+def apply_camera_transform(
+    volume: np.ndarray,
+    transform: dict
+) -> np.ndarray:
+    """
+    Apply camera transform (x/y offset + rotation) to full volume.
+
+    Transforms each XY slice (for each Z) with the same x/y offset and rotation.
+
+    Parameters
+    ----------
+    volume : ndarray
+        Input volume (Z, Y, X)
+    transform : dict
+        Contains 'x_offset', 'y_offset', and 'rotation'
+
+    Returns
+    -------
+    ndarray
+        Transformed volume (Z, Y, X)
+    """
+    x_offset = transform.get('x_offset', 0.0)
+    y_offset = transform.get('y_offset', 0.0)
+    rotation = transform.get('rotation', 0.0)
+
+    z_size, y_size, x_size = volume.shape
+    result = np.zeros_like(volume)
+
+    for z in range(z_size):
+        # extract XY slice, transform, put back
+        slice_xy = volume[z, :, :].T  # (X, Y)
+        transformed = transform_camera_slice(slice_xy, x_offset, y_offset, rotation)
+        result[z, :, :] = transformed.T  # back to (Y, X)
+
+    return result
+
+
+# -----------------------------------------------------------------------------
+# original utility functions
+# -----------------------------------------------------------------------------
+
+def rotate_volume(volume: np.ndarray, rotation: int) -> np.ndarray:
+    """
+    Rotate 3d volume by 90 degrees.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D image stack (z, y, x)
+    rotation : int
+        0 (none), 1 (90 deg cw), -1 (90 deg ccw)
+
+    Returns
+    -------
+    ndarray
+        Rotated volume
+    """
+    if rotation == 0:
+        return volume
+    elif rotation == 1:
+        return np.rot90(volume, k=-1, axes=(1, 2))
+    elif rotation == -1:
+        return np.rot90(volume, k=1, axes=(1, 2))
+    else:
+        raise ValueError(f"invalid rotation: {rotation}")
+
+
+def flip_volume(volume: np.ndarray, horizontal: bool, vertical: bool) -> np.ndarray:
+    """
+    Flip volume horizontally and/or vertically.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D image stack (z, y, x)
+    horizontal : bool
+        Flip left-right
+    vertical : bool
+        Flip top-bottom
+
+    Returns
+    -------
+    ndarray
+        Flipped volume
+    """
+    result = volume
+    if horizontal:
+        result = result[:, :, ::-1]
+    if vertical:
+        result = result[:, ::-1, :]
+    return result
+
+
+def crop_volume(
+    volume: np.ndarray,
+    top: int = 0,
+    left: int = 0,
+    height: Optional[int] = None,
+    width: Optional[int] = None,
+    front: int = 0,
+    depth: Optional[int] = None,
+) -> np.ndarray:
+    """
+    Crop 3d volume to specified roi.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D image stack (z, y, x)
+    top : int, default=0
+        Crop start y
+    left : int, default=0
+        Crop start x
+    height : int or None, default=None
+        Crop height, None uses full
+    width : int or None, default=None
+        Crop width, None uses full
+    front : int, default=0
+        Crop start z
+    depth : int or None, default=None
+        Crop depth, None uses full
+
+    Returns
+    -------
+    ndarray
+        Cropped volume
+    """
+    z, y, x = volume.shape
+
+    if height is None:
+        height = y - top
+    if width is None:
+        width = x - left
+    if depth is None:
+        depth = z - front
+
+    return volume[
+        front : front + depth,
+        top : top + height,
+        left : left + width,
+    ]
+
+
+def apply_mask(volume: np.ndarray, mask: np.ndarray) -> np.ndarray:
+    """
+    Apply binary mask to volume.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D image stack
+    mask : ndarray
+        Binary mask (0 or 1)
+
+    Returns
+    -------
+    ndarray
+        Masked volume
+    """
+    return volume * mask
+
+
+def estimate_registration(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    ref_mask: np.ndarray,
+    moving_mask: np.ndarray,
+    search_x: tuple[int, int, int] = (-50, 50, 10),
+    search_y: tuple[int, int, int] = (-50, 50, 10),
+    method: Literal["phase_cross_correlation", "correlation"] = "phase_cross_correlation",
+    slab_size: int = 0
+) -> dict:
+    """
+    Estimate registration transformation between two views.
+
+    Parameters
+    ----------
+    ref_volume : ndarray
+        Reference view (Z, Y, X)
+    moving_volume : ndarray
+        View to transform (Z, Y, X)
+    ref_mask : ndarray
+        Binary mask for ref (Z, Y, X)
+    moving_mask : ndarray
+        Binary mask for moving (Z, Y, X)
+    search_x : tuple of int, default=(-50, 50, 10)
+        (start, stop, step) for x search range
+    search_y : tuple of int, default=(-50, 50, 10)
+        (start, stop, step) for y search range
+    method : str, default='phase_cross_correlation'
+        'phase_cross_correlation' (subpixel, fast) or 'correlation' (coarse search)
+    slab_size : int, default=0
+        Adaptive slab size for correlation, 0 for slice mode, <0 for full 3D
+
+    Returns
+    -------
+    dict
+        Contains 'x_offset', 'y_offset', 'z_offset', 'rotation', 'correlation', 'method'
+
+    Notes
+    -----
+    Phase cross correlation uses FFT for fast subpixel registration.
+    Correlation method searches discrete grid (slower but more robust to rotation).
+    Masks focus registration on valid regions.
+    Slab mode processes volume in Z slabs for memory efficiency.
+    """
+    # Apply slab-based processing if enabled
+    if slab_size > 0:
+        return _estimate_registration_slab(
+            ref_volume, moving_volume, ref_mask, moving_mask,
+            search_x, search_y, method, slab_size
+        )
+
+    if method == "phase_cross_correlation":
+        return _estimate_registration_phase(ref_volume, moving_volume, ref_mask, moving_mask)
+    elif method == "correlation":
+        return _estimate_registration_correlation(
+            ref_volume, moving_volume, ref_mask, moving_mask, search_x, search_y
+        )
+    else:
+        raise ValueError(f"Unknown method: {method}")
+
+
+def _estimate_registration_phase(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    ref_mask: np.ndarray,
+    moving_mask: np.ndarray
+) -> dict:
+    """Estimate registration using phase cross-correlation, FFT-based subpixel method."""
+    # Apply masks
+    ref_masked = ref_volume * ref_mask
+    moving_masked = moving_volume * moving_mask
+
+    # Estimate shift using phase cross-correlation
+    shift, error, _ = phase_cross_correlation(
+        ref_masked, moving_masked, upsample_factor=10
+    )
+
+    z_offset, y_offset, x_offset = shift
+    correlation = 1.0 / (1.0 + error) if error > 0 else 1.0
+
+    return {
+        'x_offset': float(x_offset),
+        'y_offset': float(y_offset),
+        'z_offset': float(z_offset),
+        'rotation': 0.0,
+        'correlation': float(correlation),
+        'method': 'phase_cross_correlation'
+    }
+
+
+def _estimate_registration_correlation(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    ref_mask: np.ndarray,
+    moving_mask: np.ndarray,
+    search_x: tuple[int, int, int],
+    search_y: tuple[int, int, int]
+) -> dict:
+    """Estimate registration using correlation search over discrete grid."""
+    ref_masked = ref_volume * ref_mask
+    moving_masked = moving_volume * moving_mask
+
+    x_start, x_stop, x_step = search_x
+    y_start, y_stop, y_step = search_y
+    x_offsets = np.arange(x_start, x_stop + 1, x_step)
+    y_offsets = np.arange(y_start, y_stop + 1, y_step)
+
+    best_corr = -np.inf
+    best_x = 0.0
+    best_y = 0.0
+
+    for x_off in x_offsets:
+        for y_off in y_offsets:
+            shifted = ndimage.shift(
+                moving_masked, shift=(0, y_off, x_off), order=1, mode='constant', cval=0
+            )
+
+            overlap_mask = (ref_masked > 0) & (shifted > 0)
+            if overlap_mask.sum() == 0:
+                continue
+
+            ref_overlap = ref_masked[overlap_mask].astype(np.float64)
+            mov_overlap = shifted[overlap_mask].astype(np.float64)
+
+            ref_norm = (ref_overlap - ref_overlap.mean()) / (ref_overlap.std() + 1e-8)
+            mov_norm = (mov_overlap - mov_overlap.mean()) / (mov_overlap.std() + 1e-8)
+            corr = np.mean(ref_norm * mov_norm)
+
+            if corr > best_corr:
+                best_corr = corr
+                best_x = x_off
+                best_y = y_off
+
+    return {
+        'x_offset': float(best_x),
+        'y_offset': float(best_y),
+        'z_offset': 0.0,
+        'rotation': 0.0,
+        'correlation': float(best_corr),
+        'method': 'correlation'
+    }
+
+
+def apply_registration(
+    volume: np.ndarray,
+    transform: dict,
+    order: int = 3
+) -> np.ndarray:
+    """
+    Apply registration transformation to volume.
+
+    Parameters
+    ----------
+    volume : ndarray
+        Input volume (Z, Y, X)
+    transform : dict
+        Dict from estimate_registration containing x_offset, y_offset, z_offset, rotation
+    order : int, default=3
+        Interpolation order: 0=nearest, 1=linear, 3=cubic
+
+    Returns
+    -------
+    ndarray
+        Transformed volume (Z, Y, X)
+
+    Notes
+    -----
+    Applies rotation first (per Z-slice in XY plane), then translation.
+    """
+    x_offset = transform.get('x_offset', 0.0)
+    y_offset = transform.get('y_offset', 0.0)
+    z_offset = transform.get('z_offset', 0.0)
+    rotation = transform.get('rotation', 0.0)
+
+    result = volume.copy()
+
+    # Apply rotation if non-zero (per Z-slice in XY plane)
+    if abs(rotation) > 1e-6:
+        Z = result.shape[0]
+        rotated = np.zeros_like(result)
+        for z in range(Z):
+            rotated[z, :, :] = ndimage.rotate(
+                result[z, :, :], rotation, reshape=False, order=order, mode='constant', cval=0
+            )
+        result = rotated
+
+    # Apply translation
+    # use mode='nearest' to avoid zeroing boundary slices
+    if abs(x_offset) > 1e-6 or abs(y_offset) > 1e-6 or abs(z_offset) > 1e-6:
+        result = ndimage.shift(
+            result, shift=(z_offset, y_offset, x_offset), order=order, mode='nearest'
+        )
+
+    return result
+
+
+def apply_registration_to_mask(mask: np.ndarray, transform: dict) -> np.ndarray:
+    """
+    Apply registration transformation to binary mask.
+
+    Parameters
+    ----------
+    mask : ndarray
+        Binary mask (Z, Y, X) or (X, Z) transition plane topology
+    transform : dict
+        Transformation parameters
+
+    Returns
+    -------
+    ndarray
+        Transformed mask, same shape as input
+
+    Notes
+    -----
+    Uses order=1 linear interpolation then thresholds at 0.5 to preserve binary nature.
+    """
+    transformed = apply_registration(mask.astype(np.float32), transform, order=1)
+    return (transformed > 0.5).astype(mask.dtype)
+
+
+def _estimate_registration_slab(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    ref_mask: np.ndarray,
+    moving_mask: np.ndarray,
+    search_x: tuple[int, int, int],
+    search_y: tuple[int, int, int],
+    method: str,
+    slab_size: int
+) -> dict:
+    """
+    Estimate registration using slab-based processing.
+
+    Parameters
+    ----------
+    ref_volume : ndarray
+        Reference view (Z, Y, X)
+    moving_volume : ndarray
+        View to transform (Z, Y, X)
+    ref_mask : ndarray
+        Binary mask for ref (Z, Y, X)
+    moving_mask : ndarray
+        Binary mask for moving (Z, Y, X)
+    search_x : tuple of int
+        (start, stop, step) for x search range
+    search_y : tuple of int
+        (start, stop, step) for y search range
+    method : str
+        Registration method
+    slab_size : int
+        Slab thickness in Z
+
+    Returns
+    -------
+    dict
+        Contains averaged registration parameters
+
+    Notes
+    -----
+    Processes volume in Z slabs, estimates registration for each slab,
+    then averages results. More memory-efficient for large volumes.
+    """
+    Z = ref_volume.shape[0]
+
+    # Collect results from each slab
+    slab_results = []
+
+    for z_start in range(0, Z, slab_size):
+        z_end = min(z_start + slab_size, Z)
+
+        # Extract slab
+        ref_slab = ref_volume[z_start:z_end, :, :]
+        moving_slab = moving_volume[z_start:z_end, :, :]
+        ref_mask_slab = ref_mask[z_start:z_end, :, :]
+        moving_mask_slab = moving_mask[z_start:z_end, :, :]
+
+        # Estimate registration for this slab
+        if method == "phase_cross_correlation":
+            result = _estimate_registration_phase(
+                ref_slab, moving_slab, ref_mask_slab, moving_mask_slab
+            )
+        elif method == "correlation":
+            result = _estimate_registration_correlation(
+                ref_slab, moving_slab, ref_mask_slab, moving_mask_slab,
+                search_x, search_y
+            )
+        else:
+            raise ValueError(f"Unknown method: {method}")
+
+        slab_results.append(result)
+
+    # Average results across slabs (weighted by correlation)
+    correlations = np.array([r['correlation'] for r in slab_results])
+    total_corr = correlations.sum()
+
+    if total_corr > 0:
+        weights = correlations / total_corr
+    else:
+        weights = np.ones(len(slab_results)) / len(slab_results)
+
+    averaged = {
+        'x_offset': sum(w * r['x_offset'] for w, r in zip(weights, slab_results)),
+        'y_offset': sum(w * r['y_offset'] for w, r in zip(weights, slab_results)),
+        'z_offset': sum(w * r['z_offset'] for w, r in zip(weights, slab_results)),
+        'rotation': sum(w * r['rotation'] for w, r in zip(weights, slab_results)),
+        'correlation': correlations.mean(),
+        'method': f"{method}_slab"
+    }
+
+    return averaged