isoview 0.1.0__py3-none-any.whl

isoview/fusion.py

@@ -0,0 +1,979 @@
+"""Multi-view fusion for IsoView microscopy data."""
+
+from pathlib import Path
+import numpy as np
+from typing import Literal
+
+try:
+    import pywt
+    PYWT_AVAILABLE = True
+except ImportError:
+    PYWT_AVAILABLE = False
+
+from .config import ProcessingConfig
+from .io import read_volume, write_volume
+from .transforms import (
+    estimate_registration,
+    apply_registration,
+    apply_registration_to_mask,
+    estimate_channel_transform,
+    estimate_camera_transform,
+    apply_channel_transform,
+    apply_camera_transform,
+)
+from .intensity import estimate_intensity_correction, apply_intensity_correction, estimate_background, subtract_background
+from .masks import create_fusion_mask, create_slice_mask, create_average_mask, remove_mask_anomalies
+
+
+def _find_volume_file(tm_folder: Path, specimen: int, timepoint: int, camera: int, channel: int) -> Path | None:
+    """Find volume file for given parameters."""
+    base = f"SPM{specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}"
+    for ext in [".klb", ".tif", ".zarr"]:
+        path = tm_folder / f"{base}{ext}"
+        if path.exists():
+            return path
+    return None
+
+
+def _find_mask_file(tm_folder: Path, specimen: int, timepoint: int, camera: int, channel: int) -> Path | None:
+    """Find segmentation mask file for given parameters."""
+    base = f"SPM{specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{channel:02d}.segmentationMask"
+    for ext in [".klb", ".tif", ".zarr"]:
+        path = tm_folder / f"{base}{ext}"
+        if path.exists():
+            return path
+    return None
+
+
+def fuse_views(
+    vol0: np.ndarray,
+    vol1: np.ndarray,
+    mask0: np.ndarray | None = None,
+    mask1: np.ndarray | None = None,
+    fusion_type: str = "adaptive_blending",
+    blending_range: int = 20,
+    search_x: tuple[int, int, int] = (-50, 50, 10),
+    search_y: tuple[int, int, int] = (-50, 50, 10),
+    mask_percentile: float = 1.0,
+    mode: Literal["camera", "channel"] = "camera",
+    scaling: float = 1.0,
+    optimizer: Literal["gradient_descent", "nelder_mead", "bfgs"] = "gradient_descent",
+) -> tuple[np.ndarray, dict]:
+    """
+    Fuse two 3D volumes.
+
+    This is the core fusion function with no file I/O - operates purely on arrays.
+    Supports both camera-camera and channel-channel fusion modes.
+
+    Parameters
+    ----------
+    vol0 : ndarray
+        Reference volume (Z, Y, X)
+    vol1 : ndarray
+        Moving volume (Z, Y, X)
+    mask0 : ndarray or None
+        Binary mask for vol0, created if None
+    mask1 : ndarray or None
+        Binary mask for vol1, created if None
+    fusion_type : str
+        Blending method: adaptive_blending, geometric, wavelet, average
+    blending_range : int
+        Width of transition zone in Z-planes
+    search_x : tuple
+        Registration search range (start, stop, step) for X (camera mode)
+    search_y : tuple
+        Registration search range (start, stop, step) for Y (camera mode)
+    mask_percentile : float
+        Percentile for mask creation if masks not provided
+    mode : str
+        'camera' for x/y/rotation (XY plane), 'channel' for z/rotation (XZ plane)
+    scaling : float
+        Axial/lateral pixel ratio for channel mode (z_spacing / xy_spacing)
+    optimizer : str
+        Optimization algorithm: 'gradient_descent' (MATLAB-equivalent),
+        'nelder_mead', or 'bfgs'
+
+    Returns
+    -------
+    fused : ndarray
+        Fused volume (Z, Y, X)
+    params : dict
+        Estimated parameters (transform, intensity correction)
+
+    Notes
+    -----
+    Camera mode: estimates x_offset, y_offset, rotation (around Z axis)
+        Uses coarse grid search then fine optimization with rotation.
+        Equivalent to MATLAB transformCamera.
+
+    Channel mode: estimates z_offset, rotation (in XZ plane)
+        Works on XZ slices to align light sheets from different channels.
+        Equivalent to MATLAB transformChannel.
+    """
+    # create masks if not provided
+    if mask0 is None:
+        mask0 = create_fusion_mask(vol0, mask_percentile)
+    if mask1 is None:
+        mask1 = create_fusion_mask(vol1, mask_percentile)
+
+    # estimate registration based on mode
+    if mode == "camera":
+        transform = estimate_camera_transform(
+            vol0, vol1,
+            search_x=search_x,
+            search_y=search_y,
+            optimizer=optimizer
+        )
+        # apply camera transform (x/y + rotation per XY slice)
+        vol1_transformed = apply_camera_transform(vol1, transform)
+        mask1_transformed = apply_camera_transform(mask0.astype(np.float32), transform) > 0.5
+
+    elif mode == "channel":
+        transform = estimate_channel_transform(
+            vol0, vol1,
+            scaling=scaling,
+            optimizer=optimizer
+        )
+        # apply channel transform (z + rotation per XZ slice)
+        vol1_transformed = apply_channel_transform(vol1, transform, scaling)
+        mask1_transformed = apply_channel_transform(mask1.astype(np.float32), transform, scaling) > 0.5
+
+    else:
+        raise ValueError(f"Unknown mode: {mode}. Use 'camera' or 'channel'.")
+
+    # estimate intensity correction
+    correction = estimate_intensity_correction(vol0, vol1_transformed, mask0, mask1_transformed)
+
+    # apply intensity correction
+    vol1_corrected = apply_intensity_correction(vol1_transformed, correction)
+
+    # compute blending masks
+    slice_mask0 = create_slice_mask(vol0, mask0)
+    slice_mask1 = create_slice_mask(vol1_corrected, mask1_transformed)
+    avg_mask = create_average_mask(slice_mask0, slice_mask1, mode="overlap")
+    avg_mask = remove_mask_anomalies(avg_mask, vol0.shape[0], blending_range)
+
+    # blend
+    fused = blend_views(
+        [vol0, vol1_corrected],
+        [avg_mask, avg_mask],
+        method=fusion_type,
+        blending_range=blending_range
+    )
+
+    params = {
+        'transform': transform,
+        'correction': correction,
+        'mode': mode,
+    }
+
+    return fused, params
+
+
+def multi_fuse(
+    config: ProcessingConfig,
+    estimate_params: bool = True,
+    apply_fusion: bool = True,
+    overwrite: bool = False
+) -> None:
+    """
+    Multi-view fusion (matches MATLAB multiFuse).
+
+    Parameters
+    ----------
+    config : ProcessingConfig
+        Processing configuration with fusion parameters.
+        - input_dir: where to read corrected volumes (TM###### folders)
+        - output_dir: where to write fused volumes
+    estimate_params : bool, default=True
+        Estimate transformations and corrections
+    apply_fusion : bool, default=True
+        Apply fusion and save results
+    overwrite : bool, default=False
+        Overwrite existing fusion results
+    """
+    if not config.fusion_camera_pairs and not config.fusion_channel_pairs:
+        raise ValueError("No fusion pairs specified. Set fusion_camera_pairs or fusion_channel_pairs.")
+
+    # determine fusion mode
+    # fusion_4view_only: skip camera fusion, use existing camera-fused files
+    if getattr(config, 'fusion_4view_only', False) and config.fusion_channel_pairs:
+        mode = '4view_only'
+    elif config.fusion_camera_pairs and config.fusion_channel_pairs:
+        mode = 'full'
+    elif config.fusion_channel_pairs:
+        mode = 'channel'
+    else:
+        mode = 'camera'
+
+    print(f"Fusion mode: {mode}")
+    print(f"Input: {config.input_dir}")
+    print(f"Output: {config.output_dir}")
+    print(f"Estimate params: {estimate_params}, Apply fusion: {apply_fusion}")
+
+    for timepoint in config.timepoints:
+        print(f"\nProcessing timepoint {timepoint}")
+
+        # read from input_dir
+        input_tm_folder = config.input_dir / f"TM{timepoint:06d}"
+        if not input_tm_folder.exists():
+            print(f"  Warning: TM folder not found: {input_tm_folder}, skipping")
+            continue
+
+        # write to output_dir
+        output_tm_folder = config.output_dir / f"TM{timepoint:06d}"
+
+        # step 1: camera fusion (if enabled)
+        if config.fusion_camera_pairs:
+            for cam0, cam1 in config.fusion_camera_pairs:
+                # determine channel for this camera pair
+                # cameras 0,1 use channel 1; cameras 2,3 use channel 0
+                channel = 1 if cam0 < 2 else 0
+                print(f"  Fusing cameras {cam0} + {cam1} (channel {channel})")
+                _fuse_camera_pair(
+                    input_tm_folder, output_tm_folder, config.specimen, timepoint,
+                    cam0, cam1, channel, config, estimate_params, apply_fusion, overwrite
+                )
+
+        # step 2: channel fusion
+        if config.fusion_channel_pairs:
+            if mode in ('full', '4view_only'):
+                # 4-view mode: fuse the camera-fused outputs (CHN00 + CHN01)
+                for ch0, ch1 in config.fusion_channel_pairs:
+                    print(f"  Fusing camera-fused channels {ch0} + {ch1} (4-view)")
+                    _fuse_camera_fused_channels(
+                        input_tm_folder, output_tm_folder, config.specimen, timepoint,
+                        ch0, ch1, config, estimate_params, apply_fusion, overwrite
+                    )
+            elif mode == 'channel':
+                # channel-only mode: fuse channels per camera (original behavior)
+                for ch0, ch1 in config.fusion_channel_pairs:
+                    for camera in config.cameras:
+                        print(f"  Fusing channels {ch0} + {ch1} for camera {camera}")
+                        _fuse_channel_pair(
+                            input_tm_folder, output_tm_folder, config.specimen, timepoint,
+                            camera, ch0, ch1, config, estimate_params, apply_fusion, overwrite
+                        )
+
+    print("\nFusion complete!")
+
+
+def _fuse_camera_pair(
+    input_tm_folder: Path,
+    output_tm_folder: Path,
+    specimen: int,
+    timepoint: int,
+    cam0: int,
+    cam1: int,
+    channel: int,
+    config: ProcessingConfig,
+    estimate_params: bool,
+    apply_fusion: bool,
+    overwrite: bool
+):
+    """Fuse two cameras for a single timepoint."""
+    # output path
+    output_tm_folder.mkdir(parents=True, exist_ok=True)
+    fused_file = output_tm_folder / f"SPM{specimen:02d}_TM{timepoint:06d}_CM{cam0:02d}_CM{cam1:02d}_CHN{channel:02d}.{config.output_format}"
+
+    if fused_file.exists() and not overwrite:
+        print(f"    Fusion exists: {fused_file.name}, skipping")
+        return
+
+    # find input volumes
+    vol0_path = _find_volume_file(input_tm_folder, specimen, timepoint, cam0, channel)
+    vol1_path = _find_volume_file(input_tm_folder, specimen, timepoint, cam1, channel)
+
+    if vol0_path is None:
+        print(f"    Warning: Camera {cam0} volume not found, skipping")
+        return
+    if vol1_path is None:
+        print(f"    Warning: Camera {cam1} volume not found, skipping")
+        return
+
+    # load volumes
+    print(f"    Loading {vol0_path.name}")
+    vol0 = read_volume(vol0_path)
+    print(f"    Loading {vol1_path.name}")
+    vol1 = read_volume(vol1_path)
+
+    # load or create masks
+    mask0_path = _find_mask_file(input_tm_folder, specimen, timepoint, cam0, channel)
+    mask1_path = _find_mask_file(input_tm_folder, specimen, timepoint, cam1, channel)
+
+    if mask0_path and mask0_path.exists():
+        print(f"    Loading mask {mask0_path.name}")
+        mask0 = read_volume(mask0_path) > 0
+        print(f"      mask0: {mask0.sum()}/{mask0.size} pixels ({100*mask0.sum()/mask0.size:.1f}%)")
+    else:
+        print(f"    Creating mask for camera {cam0}")
+        mask0 = create_fusion_mask(vol0, config.mask_percentile)
+        print(f"      mask0: {mask0.sum()}/{mask0.size} pixels ({100*mask0.sum()/mask0.size:.1f}%)")
+
+    if mask1_path and mask1_path.exists():
+        print(f"    Loading mask {mask1_path.name}")
+        mask1 = read_volume(mask1_path) > 0
+        print(f"      mask1: {mask1.sum()}/{mask1.size} pixels ({100*mask1.sum()/mask1.size:.1f}%)")
+    else:
+        print(f"    Creating mask for camera {cam1}")
+        mask1 = create_fusion_mask(vol1, config.mask_percentile)
+        print(f"      mask1: {mask1.sum()}/{mask1.size} pixels ({100*mask1.sum()/mask1.size:.1f}%)")
+
+    # estimate registration using camera mode (x/y + rotation)
+    if estimate_params:
+        print(f"    Estimating transformation cam{cam0} -> cam{cam1}")
+        transform = estimate_camera_transform(
+            vol0, vol1,
+            search_x=config.fusion_search_offsets_x,
+            search_y=config.fusion_search_offsets_y,
+            optimizer=getattr(config, 'fusion_optimizer', 'gradient_descent')
+        )
+
+        print(f"      Transform: offset=({transform['x_offset']:.2f}, {transform['y_offset']:.2f}), rot={transform['rotation']:.3f}°, corr={transform['correlation']:.3f}")
+    else:
+        # would need to load from metadata file - for now just estimate
+        transform = estimate_camera_transform(vol0, vol1)
+
+    if not apply_fusion:
+        return
+
+    print(f"    Applying fusion")
+
+    # apply camera transforms (x/y + rotation per XY slice)
+    vol1_transformed = apply_camera_transform(vol1, transform)
+    mask1_transformed = apply_camera_transform(mask1.astype(np.float32), transform) > 0.5
+
+    # subtract background from both volumes (MATLAB equivalent)
+    background = estimate_background(vol0, vol1_transformed, config.background_percentile)
+    vol0_sub = subtract_background(vol0, background)
+    vol1_sub = subtract_background(vol1_transformed, background)
+    print(f"      Background: {background:.1f}")
+
+    # intensity correction (applied to moving volume)
+    correction = estimate_intensity_correction(vol0_sub, vol1_sub, mask0, mask1_transformed)
+    print(f"      Intensity: factor={correction['factor']:.3f}")
+    vol1_corrected = apply_intensity_correction(vol1_sub, correction)
+
+    # compute blending masks (Y, X) containing Z-values
+    slice_mask0 = create_slice_mask(vol0_sub, mask0)
+    slice_mask1 = create_slice_mask(vol1_corrected, mask1_transformed)
+
+    # debug: check slice mask stats
+    sm0_valid = (slice_mask0 > 0).sum()
+    sm1_valid = (slice_mask1 > 0).sum()
+    print(f"      slice_mask0: {sm0_valid}/{slice_mask0.size} valid", end="")
+    if sm0_valid > 0:
+        print(f", range [{slice_mask0[slice_mask0>0].min()}-{slice_mask0[slice_mask0>0].max()}]")
+    else:
+        print()
+    print(f"      slice_mask1: {sm1_valid}/{slice_mask1.size} valid", end="")
+    if sm1_valid > 0:
+        print(f", range [{slice_mask1[slice_mask1>0].min()}-{slice_mask1[slice_mask1>0].max()}]")
+    else:
+        print()
+
+    avg_mask = create_average_mask(slice_mask0, slice_mask1, mode="union")
+
+    # check if mask is valid before removing anomalies
+    valid_before = (avg_mask > 0).sum()
+    z_size = vol0.shape[0]
+    blending = config.fusion_blending_range[1]
+
+    # automatically reduce blending if volume is too small
+    max_blending = (z_size - 1) // 2
+    effective_blending = min(blending, max_blending)
+    if effective_blending < blending:
+        print(f"      Note: reduced blending range from {blending} to {effective_blending} (z_size={z_size})")
+        blending = effective_blending
+
+    if valid_before > 0:
+        avg_mask = remove_mask_anomalies(avg_mask, z_size, blending)
+
+    # if mask is empty, use geometric center as fallback
+    valid_after = (avg_mask > 0).sum()
+    if valid_after == 0:
+        center_z = z_size // 2
+        print(f"      Mask empty after anomaly removal, using geometric center (Z={center_z})")
+        avg_mask = np.full((vol0.shape[1], vol0.shape[2]), center_z, dtype=np.uint16)
+
+    # print mask stats for debugging
+    valid_mask = avg_mask > 0
+    print(f"      Final mask: {valid_mask.sum()}/{avg_mask.size} valid, range [{avg_mask[valid_mask].min()}-{avg_mask[valid_mask].max()}]")
+
+    # blend with effective blending range
+    fused = blend_views(
+        [vol0_sub, vol1_corrected],
+        [avg_mask, avg_mask],
+        method=config.fusion_type,
+        blending_range=blending,  # use effective blending
+        front_flag=config.fusion_front_flag
+    )
+
+    # save
+    write_volume(fused, fused_file)
+    print(f"    Saved to {fused_file}")
+
+
+def _fuse_channel_pair(
+    input_tm_folder: Path,
+    output_tm_folder: Path,
+    specimen: int,
+    timepoint: int,
+    camera: int,
+    ch0: int,
+    ch1: int,
+    config: ProcessingConfig,
+    estimate_params: bool,
+    apply_fusion: bool,
+    overwrite: bool
+):
+    """Fuse two channels for a single timepoint."""
+    # output path
+    output_tm_folder.mkdir(parents=True, exist_ok=True)
+    fused_file = output_tm_folder / f"SPM{specimen:02d}_TM{timepoint:06d}_CM{camera:02d}_CHN{ch0:02d}_CHN{ch1:02d}.{config.output_format}"
+
+    if fused_file.exists() and not overwrite:
+        print(f"    Fusion exists: {fused_file.name}, skipping")
+        return
+
+    # find input volumes
+    vol0_path = _find_volume_file(input_tm_folder, specimen, timepoint, camera, ch0)
+    vol1_path = _find_volume_file(input_tm_folder, specimen, timepoint, camera, ch1)
+
+    if vol0_path is None:
+        print(f"    Warning: Channel {ch0} volume not found, skipping")
+        return
+    if vol1_path is None:
+        print(f"    Warning: Channel {ch1} volume not found, skipping")
+        return
+
+    # load volumes
+    vol0 = read_volume(vol0_path)
+    vol1 = read_volume(vol1_path)
+
+    # load or create masks
+    mask0_path = _find_mask_file(input_tm_folder, specimen, timepoint, camera, ch0)
+    mask1_path = _find_mask_file(input_tm_folder, specimen, timepoint, camera, ch1)
+
+    if mask0_path and mask0_path.exists():
+        mask0 = read_volume(mask0_path) > 0
+    else:
+        mask0 = create_fusion_mask(vol0, config.mask_percentile)
+
+    if mask1_path and mask1_path.exists():
+        mask1 = read_volume(mask1_path) > 0
+    else:
+        mask1 = create_fusion_mask(vol1, config.mask_percentile)
+
+    # estimate registration using channel mode (z-offset + rotation in XZ plane)
+    if estimate_params:
+        print(f"    Estimating transformation ch{ch0} -> ch{ch1}")
+        scaling = getattr(config, 'axial_scaling', 1.0)
+        transform = estimate_channel_transform(
+            vol0, vol1,
+            scaling=scaling,
+            optimizer=getattr(config, 'fusion_optimizer', 'gradient_descent')
+        )
+
+        print(f"      Transform: z_offset={transform['z_offset']:.2f}, rot={transform['rotation']:.3f}°, corr={transform['correlation']:.3f}")
+    else:
+        transform = estimate_channel_transform(vol0, vol1)
+
+    if not apply_fusion:
+        return
+
+    print(f"    Applying fusion")
+
+    # apply channel transforms (z + rotation per XZ slice)
+    scaling = getattr(config, 'axial_scaling', 1.0)
+    vol1_transformed = apply_channel_transform(vol1, transform, scaling)
+    mask1_transformed = apply_channel_transform(mask1.astype(np.float32), transform, scaling) > 0.5
+
+    # intensity correction
+    correction = estimate_intensity_correction(vol0, vol1_transformed, mask0, mask1_transformed)
+    print(f"      Intensity: factor={correction['factor']:.3f}")
+    vol1_corrected = apply_intensity_correction(vol1_transformed, correction)
+
+    # compute blending masks - channel fusion also blends along Z (same as camera)
+    slice_mask0 = create_slice_mask(vol0, mask0)
+    slice_mask1 = create_slice_mask(vol1_corrected, mask1_transformed)
+    avg_mask = create_average_mask(slice_mask0, slice_mask1, mode="union")
+
+    # remove anomalies based on Z dimension
+    z_size = vol0.shape[0]
+    blending = config.fusion_blending_range[0]
+    max_blending = (z_size - 1) // 2
+    effective_blending = min(blending, max_blending)
+    if effective_blending < blending:
+        print(f"      Note: reduced blending range from {blending} to {effective_blending} (z_size={z_size})")
+        blending = effective_blending
+
+    avg_mask = remove_mask_anomalies(avg_mask, z_size, blending)
+
+    # if mask is empty, use geometric center as fallback
+    valid_after = (avg_mask > 0).sum()
+    if valid_after == 0:
+        center_z = z_size // 2
+        print(f"      Mask empty, using geometric center (Z={center_z})")
+        avg_mask = np.full((vol0.shape[1], vol0.shape[2]), center_z, dtype=np.uint16)
+
+    fused = blend_views(
+        [vol0, vol1_corrected],
+        [avg_mask, avg_mask],
+        method=config.fusion_type,
+        blending_range=blending,
+        front_flag=getattr(config, 'fusion_front_flag', 1)
+    )
+
+    write_volume(fused, fused_file)
+    print(f"    Saved to {fused_file}")
+
+
+def blend_views(
+    views: list[np.ndarray],
+    masks: list[np.ndarray],
+    method: Literal["adaptive_blending", "geometric", "wavelet", "average"] = "adaptive_blending",
+    blending_range: int = 20,
+    transition_plane: int | None = None,
+    wavelet: str = "db4",
+    wavelet_level: int = 5,
+    front_flag: int = 1,
+    **kwargs
+) -> np.ndarray:
+    """
+    Blend multiple views into single fused volume.
+
+    Parameters
+    ----------
+    views : list of ndarray
+        Volumes to fuse, all same shape (Z, Y, X)
+    masks : list of ndarray
+        Binary masks or transition planes (Y, X) with Z-values
+    method : str, default='adaptive_blending'
+        Fusion method: 'adaptive_blending', 'geometric', 'wavelet', 'average'
+    blending_range : int, default=20
+        Transition zone width in pixels
+    transition_plane : int or None, default=None
+        For geometric method, Z-index of transition, None uses center
+    wavelet : str, default='db4'
+        Wavelet basis for wavelet method
+    wavelet_level : int, default=5
+        Decomposition level for wavelet method
+    front_flag : int, default=1
+        Which view is dominant in front (low Z). 1=view1, 2=view2
+
+    Returns
+    -------
+    ndarray
+        Fused volume (Z, Y, X)
+    """
+    if len(views) != 2:
+        raise ValueError("Currently only 2-view fusion is supported")
+
+    if method == "adaptive_blending":
+        return adaptive_blending(views[0], views[1], masks[0], blending_range, front_flag)
+    elif method == "geometric":
+        return geometric_blending(views[0], views[1], transition_plane, blending_range)
+    elif method == "wavelet":
+        if not PYWT_AVAILABLE:
+            raise ImportError("PyWavelets (pywt) required for wavelet fusion")
+        return wavelet_fusion(views[0], views[1], wavelet, wavelet_level)
+    elif method == "average":
+        return average_fusion(views[0], views[1])
+    else:
+        raise ValueError(f"Unknown fusion method: {method}")
+
+
+def adaptive_blending(view1, view2, mask, blending_range=20, front_flag=1):
+    """
+    Adaptive blending with smooth linear transition along Z axis.
+
+    Parameters
+    ----------
+    view1 : ndarray
+        Reference view (Z, Y, X)
+    view2 : ndarray
+        Transformed view (Z, Y, X)
+    mask : ndarray
+        Transition plane topology (Y, X) containing Z-indices
+    blending_range : int, default=20
+        Width of blending zone in Z-planes
+    front_flag : int, default=1
+        Which view is dominant in front (low Z). 1=view1, 2=view2
+
+    Returns
+    -------
+    ndarray
+        Fused volume (Z, Y, X)
+
+    Notes
+    -----
+    MATLAB convention: mask[y,x] contains the Z-plane where transition occurs.
+    front_flag controls which view dominates in the "front" (low Z values).
+    """
+    Z, Y, X = view1.shape
+    fused = np.zeros_like(view1, dtype=np.float32)
+
+    # swap views if front_flag == 2 (view2 should be in front)
+    if front_flag == 2:
+        view1, view2 = view2, view1
+
+    # pre-compute weight vectors
+    # front: view1 fades from 1.0 to 0.5, view2 fades from 0.0 to 0.5
+    w1_front = np.linspace(1.0, 0.5, blending_range, dtype=np.float32)
+    w2_front = np.linspace(0.0, 0.5, blending_range, dtype=np.float32)
+    # back: view1 fades from 0.5 to 0.0, view2 fades from 0.5 to 1.0
+    w1_back = np.linspace(0.5, 0.0, blending_range, dtype=np.float32)
+    w2_back = np.linspace(0.5, 1.0, blending_range, dtype=np.float32)
+
+    # count statistics for debugging
+    n_valid = 0
+    n_invalid = 0
+
+    for y in range(Y):
+        for x in range(X):
+            z0 = int(mask[y, x])  # transition z-plane
+
+            if z0 == 0 or z0 >= Z:
+                # no valid transition - use max of both views (not average, to preserve signal)
+                fused[:, y, x] = np.maximum(view1[:, y, x], view2[:, y, x])
+                n_invalid += 1
+                continue
+
+            n_valid += 1
+
+            # front blend zone: z0-blending_range+1 to z0
+            z_front_start = max(0, z0 - blending_range + 1)
+            z_front_end = z0 + 1  # inclusive of z0
+            front_size = z_front_end - z_front_start
+
+            if front_size > 0 and front_size <= blending_range:
+                w1 = w1_front[-front_size:]
+                w2 = w2_front[-front_size:]
+                fused[z_front_start:z_front_end, y, x] = (
+                    view1[z_front_start:z_front_end, y, x] * w1 +
+                    view2[z_front_start:z_front_end, y, x] * w2
+                )
+
+            # back blend zone: z0+1 to z0+blending_range
+            z_back_start = z0 + 1
+            z_back_end = min(Z, z0 + blending_range + 1)
+            back_size = z_back_end - z_back_start
+
+            if back_size > 0 and back_size <= blending_range:
+                w1 = w1_back[:back_size]
+                w2 = w2_back[:back_size]
+                fused[z_back_start:z_back_end, y, x] = (
+                    view1[z_back_start:z_back_end, y, x] * w1 +
+                    view2[z_back_start:z_back_end, y, x] * w2
+                )
+
+            # outside blend zones - use single view
+            if z_front_start > 0:
+                fused[:z_front_start, y, x] = view1[:z_front_start, y, x]
+            if z_back_end < Z:
+                fused[z_back_end:, y, x] = view2[z_back_end:, y, x]
+
+    # print mask statistics for debugging
+    if n_invalid > n_valid:
+        print(f"      Warning: {n_invalid}/{n_valid+n_invalid} pixels have invalid mask (using max)")
+
+    return fused.astype(view1.dtype)
+
+
+def geometric_blending(view1, view2, transition_plane=None, blending_range=20):
+    """
+    Geometric blending with fixed transition plane.
+
+    Parameters
+    ----------
+    view1 : ndarray
+        Reference view (Z, Y, X)
+    view2 : ndarray
+        Transformed view (Z, Y, X)
+    transition_plane : int or None, default=None
+        Z-index of transition, None uses center
+    blending_range : int, default=20
+        Width of blending zone in z-planes
+
+    Returns
+    -------
+    ndarray
+        Fused volume (Z, Y, X)
+    """
+    Z, Y, X = view1.shape
+    if transition_plane is None:
+        transition_plane = Z // 2
+    mask = np.full((Y, X), transition_plane, dtype=np.int32)
+    return adaptive_blending(view1, view2, mask, blending_range)
+
+
+def wavelet_fusion(view1, view2, wavelet="db4", level=5):
+    """
+    Wavelet-based fusion using frequency decomposition.
+
+    Parameters
+    ----------
+    view1 : ndarray
+        Reference view (Z, Y, X)
+    view2 : ndarray
+        Transformed view (Z, Y, X)
+    wavelet : str, default='db4'
+        Wavelet basis (Daubechies-4)
+    level : int, default=5
+        Decomposition level
+
+    Returns
+    -------
+    ndarray
+        Fused volume (Z, Y, X)
+    """
+    if not PYWT_AVAILABLE:
+        raise ImportError("PyWavelets required for wavelet fusion")
+
+    Z, Y, X = view1.shape
+    fused = np.zeros_like(view1, dtype=np.float32)
+
+    for z in range(Z):
+        slice1 = view1[z, :, :].astype(np.float32)
+        slice2 = view2[z, :, :].astype(np.float32)
+
+        coeffs1 = pywt.wavedec2(slice1, wavelet, level=level)
+        coeffs2 = pywt.wavedec2(slice2, wavelet, level=level)
+
+        fused_coeffs = []
+        for i, (c1, c2) in enumerate(zip(coeffs1, coeffs2)):
+            if i == 0:
+                fused_coeffs.append((c1 + c2) / 2)
+            else:
+                fused_coeffs.append(tuple(np.maximum(c1[j], c2[j]) for j in range(3)))
+
+        fused[z, :, :] = pywt.waverec2(fused_coeffs, wavelet)
+
+    return fused.astype(view1.dtype)
+
+
+def average_fusion(view1, view2):
+    """
+    Simple arithmetic average of two views.
+
+    Parameters
+    ----------
+    view1 : ndarray
+        Reference view (Z, Y, X)
+    view2 : ndarray
+        Transformed view (Z, Y, X)
+
+    Returns
+    -------
+    ndarray
+        Fused volume (Z, Y, X), fused = (view1 + view2) / 2
+    """
+    return ((view1.astype(np.float32) + view2.astype(np.float32)) / 2).astype(view1.dtype)
+
+
+def _find_camera_fused_file(tm_folder: Path, specimen: int, timepoint: int, cam0: int, cam1: int, channel: int) -> Path | None:
+    """Find camera-fused volume file."""
+    base = f"SPM{specimen:02d}_TM{timepoint:06d}_CM{cam0:02d}_CM{cam1:02d}_CHN{channel:02d}"
+    for ext in [".klb", ".tif", ".zarr"]:
+        path = tm_folder / f"{base}{ext}"
+        if path.exists():
+            return path
+    return None
+
+
+def _fuse_camera_fused_channels(
+    input_tm_folder: Path,
+    output_tm_folder: Path,
+    specimen: int,
+    timepoint: int,
+    ch0: int,
+    ch1: int,
+    config: ProcessingConfig,
+    estimate_params: bool,
+    apply_fusion: bool,
+    overwrite: bool
+):
+    """
+    Fuse camera-fused outputs for 4-view fusion.
+
+    This fuses the outputs of camera fusion:
+    - CM00_CM01_CHN01 (cameras 0+1, channel 1)
+    - CM02_CM03_CHN00 (cameras 2+3, channel 0)
+
+    Uses channel mode (z-offset + rotation in XZ plane) since these are
+    now effectively two different light sheet orientations.
+
+    Masks are loaded from input_tm_folder (pre-computed from raw data),
+    not created from background-subtracted camera-fused volumes.
+    """
+    output_tm_folder.mkdir(parents=True, exist_ok=True)
+
+    # output filename for 4-view fused result
+    fused_file = output_tm_folder / f"SPM{specimen:02d}_TM{timepoint:06d}_4view_fused.{config.output_format}"
+
+    if fused_file.exists() and not overwrite:
+        print(f"    Fusion exists: {fused_file.name}, skipping")
+        return
+
+    # find camera-fused inputs in output folder
+    # ch0=0, ch1=1: we need CM02_CM03_CHN00 and CM00_CM01_CHN01
+    # standard isoview: cameras 0,1 -> CHN01, cameras 2,3 -> CHN00
+
+    # find file for channel 0 (cameras 2,3)
+    vol0_path = _find_camera_fused_file(output_tm_folder, specimen, timepoint, 2, 3, 0)
+    # find file for channel 1 (cameras 0,1)
+    vol1_path = _find_camera_fused_file(output_tm_folder, specimen, timepoint, 0, 1, 1)
+
+    if vol0_path is None:
+        print(f"    Warning: Camera-fused CHN00 (CM02_CM03) not found, skipping")
+        return
+    if vol1_path is None:
+        print(f"    Warning: Camera-fused CHN01 (CM00_CM01) not found, skipping")
+        return
+
+    # load volumes
+    print(f"    Loading {vol0_path.name}")
+    vol0 = read_volume(vol0_path)
+    print(f"    Loading {vol1_path.name}")
+    vol1 = read_volume(vol1_path)
+
+    # flip second channel to match first (for opposite objective views in isoview)
+    # this is required because CHN00 and CHN01 image from opposite sides
+    flip_h = getattr(config, 'fusion_channel_flip_h', True)
+    flip_v = getattr(config, 'fusion_channel_flip_v', True)
+    if flip_h or flip_v:
+        flips = []
+        if flip_h:
+            vol1 = np.flip(vol1, axis=2)  # flip X (horizontal)
+            flips.append("H")
+        if flip_v:
+            vol1 = np.flip(vol1, axis=1)  # flip Y (vertical)
+            flips.append("V")
+        print(f"    Flipped CHN01: {'+'.join(flips)}")
+
+    # load pre-computed masks from input folder (computed from raw data before background subtraction)
+    # for CHN00 (cameras 2,3): use camera 2's mask
+    # for CHN01 (cameras 0,1): use camera 0's mask
+    mask0_path = _find_mask_file(input_tm_folder, specimen, timepoint, 2, 0)
+    mask1_path = _find_mask_file(input_tm_folder, specimen, timepoint, 0, 1)
+
+    if mask0_path and mask0_path.exists():
+        print(f"    Loading mask {mask0_path.name}")
+        mask0 = read_volume(mask0_path) > 0
+        print(f"      mask0: {mask0.sum()}/{mask0.size} pixels ({100*mask0.sum()/mask0.size:.1f}%)")
+    else:
+        print(f"    Warning: Mask for CHN00 not found, creating from volume")
+        mask0 = create_fusion_mask(vol0, config.mask_percentile)
+
+    if mask1_path and mask1_path.exists():
+        print(f"    Loading mask {mask1_path.name}")
+        mask1 = read_volume(mask1_path) > 0
+        # apply same flip as volume
+        if flip_h:
+            mask1 = np.flip(mask1, axis=2)
+        if flip_v:
+            mask1 = np.flip(mask1, axis=1)
+        print(f"      mask1: {mask1.sum()}/{mask1.size} pixels ({100*mask1.sum()/mask1.size:.1f}%)")
+    else:
+        print(f"    Warning: Mask for CHN01 not found, creating from volume")
+        mask1 = create_fusion_mask(vol1, config.mask_percentile)
+
+    # subtract background BEFORE estimating transform (matches MATLAB)
+    # MATLAB subtracts background from dataSlices before calling transformChannel
+    background = estimate_background(vol0, vol1, config.background_percentile)
+    vol0_sub = subtract_background(vol0, background)
+    vol1_sub = subtract_background(vol1, background)
+    print(f"    Background subtraction: {background:.1f}")
+
+    # estimate channel transform (z-offset + rotation in XZ plane)
+    # use background-subtracted volumes for better correlation
+    if estimate_params:
+        print(f"    Estimating channel transformation")
+        scaling = getattr(config, 'axial_scaling', 1.0)
+        slab_size = getattr(config, 'channel_slab_size', 5)  # use slab for robustness
+        transform = estimate_channel_transform(
+            vol0_sub, vol1_sub,  # use background-subtracted volumes
+            scaling=scaling,
+            optimizer=getattr(config, 'fusion_optimizer', 'gradient_descent'),
+            slab_size=slab_size,
+            verbose=True
+        )
+        print(f"      Transform: z_offset={transform['z_offset']:.2f}, rot={transform['rotation']:.3f}°, corr={transform['correlation']:.3f}")
+    else:
+        scaling = getattr(config, 'axial_scaling', 1.0)
+        transform = estimate_channel_transform(vol0_sub, vol1_sub, scaling=scaling, verbose=True)
+
+    if not apply_fusion:
+        return
+
+    print(f"    Applying 4-view fusion")
+
+    # apply channel transform (z + rotation in XZ plane)
+    scaling = getattr(config, 'axial_scaling', 1.0)
+    vol1_transformed = apply_channel_transform(vol1_sub, transform, scaling)
+    mask1_transformed = apply_channel_transform(mask1.astype(np.float32), transform, scaling) > 0.5
+
+    # intensity correction (applied to transformed moving volume)
+    correction = estimate_intensity_correction(vol0_sub, vol1_transformed, mask0, mask1_transformed)
+    print(f"      Intensity: factor={correction['factor']:.3f}")
+    vol1_corrected = apply_intensity_correction(vol1_transformed, correction)
+
+    # compute blending masks - channel fusion blends along Z (same as camera fusion)
+    slice_mask0 = create_slice_mask(vol0_sub, mask0)
+    slice_mask1 = create_slice_mask(vol1_corrected, mask1_transformed)
+
+    # debug: check slice mask stats
+    sm0_valid = (slice_mask0 > 0).sum()
+    sm1_valid = (slice_mask1 > 0).sum()
+    print(f"      slice_mask0: {sm0_valid}/{slice_mask0.size} valid", end="")
+    if sm0_valid > 0:
+        print(f", Z-range [{slice_mask0[slice_mask0>0].min()}-{slice_mask0[slice_mask0>0].max()}]")
+    else:
+        print()
+    print(f"      slice_mask1: {sm1_valid}/{slice_mask1.size} valid", end="")
+    if sm1_valid > 0:
+        print(f", Z-range [{slice_mask1[slice_mask1>0].min()}-{slice_mask1[slice_mask1>0].max()}]")
+    else:
+        print()
+
+    avg_mask = create_average_mask(slice_mask0, slice_mask1, mode="union")
+
+    # check if mask is valid before removing anomalies
+    valid_before = (avg_mask > 0).sum()
+    z_size = vol0.shape[0]  # use Z dimension for blending
+    blending = config.fusion_blending_range[0]
+
+    # automatically reduce blending if volume is too small
+    max_blending = (z_size - 1) // 2
+    effective_blending = min(blending, max_blending)
+    if effective_blending < blending:
+        print(f"      Note: reduced blending range from {blending} to {effective_blending} (z_size={z_size})")
+        blending = effective_blending
+
+    if valid_before > 0:
+        avg_mask = remove_mask_anomalies(avg_mask, z_size, blending)
+
+    # if mask is empty, use geometric center as fallback
+    valid_after = (avg_mask > 0).sum()
+    if valid_after == 0:
+        center_z = z_size // 2
+        print(f"      Mask empty after processing, using geometric center (Z={center_z})")
+        avg_mask = np.full((vol0.shape[1], vol0.shape[2]), center_z, dtype=np.uint16)  # (Y, X)
+
+    # print mask stats
+    valid_mask = avg_mask > 0
+    print(f"      Mask: {valid_mask.sum()}/{avg_mask.size} valid, Z-range [{avg_mask[valid_mask].min()}-{avg_mask[valid_mask].max()}]")
+
+    # blend along Z axis
+    fused = blend_views(
+        [vol0_sub, vol1_corrected],
+        [avg_mask, avg_mask],
+        method=config.fusion_type,
+        blending_range=blending,
+        front_flag=config.fusion_front_flag
+    )
+
+    # save
+    write_volume(fused, fused_file)
+    print(f"    Saved to {fused_file}")