isoview 0.1.0__py3-none-any.whl

isoview/viz.py

@@ -0,0 +1,723 @@
+"""Visualization utilities for isoview processing pipeline."""
+
+from pathlib import Path
+from typing import Optional, Union
+import numpy as np
+from matplotlib import pyplot as plt
+from matplotlib.colors import LinearSegmentedColormap
+
+
+# Default style settings
+STYLE = {
+    "facecolor": "black",
+    "text_color": "white",
+    "grid_color": "gray",
+    "grid_alpha": 0.3,
+    "dpi": 150,
+    "font_size": 10,
+    "title_size": 12,
+    "label_size": 10,
+}
+
+
+def _apply_dark_style(ax, fig=None):
+    """Apply dark theme to axes."""
+    ax.set_facecolor(STYLE["facecolor"])
+    ax.tick_params(colors=STYLE["text_color"], labelsize=STYLE["font_size"])
+    for spine in ax.spines.values():
+        spine.set_color(STYLE["text_color"])
+    if fig is not None:
+        fig.patch.set_facecolor(STYLE["facecolor"])
+
+
+def _save_or_show(fig, save_path: Optional[Union[str, Path]] = None):
+    """Save figure to file or display."""
+    if save_path:
+        plt.savefig(
+            save_path,
+            dpi=STYLE["dpi"],
+            facecolor=fig.get_facecolor(),
+            bbox_inches="tight"
+        )
+        plt.close(fig)
+    else:
+        plt.show()
+
+
+def plot_projections(
+    volume: np.ndarray,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Volume Projections",
+    cmap: str = "gray"
+) -> None:
+    """
+    Plot maximum intensity projections along all three axes.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D volume (Z, Y, X)
+    save_path : str or Path, optional
+        Path to save figure
+    title : str, default='Volume Projections'
+        Figure title
+    cmap : str, default='gray'
+        Colormap
+    """
+    fig, axes = plt.subplots(1, 3, figsize=(12, 4), facecolor=STYLE["facecolor"])
+
+    proj_z = np.max(volume, axis=0)  # Z projection -> (Y, X)
+    proj_y = np.max(volume, axis=1)  # Y projection -> (Z, X)
+    proj_x = np.max(volume, axis=2)  # X projection -> (Z, Y)
+
+    titles = ["XY (max Z)", "XZ (max Y)", "YZ (max X)"]
+    projs = [proj_z, proj_y, proj_x]
+
+    for ax, proj, t in zip(axes, projs, titles):
+        _apply_dark_style(ax)
+        ax.imshow(proj, cmap=cmap, aspect="auto")
+        ax.set_title(t, color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+        ax.set_xticks([])
+        ax.set_yticks([])
+
+    fig.suptitle(title, color=STYLE["text_color"], fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_histogram(
+    volume: np.ndarray,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Intensity Histogram",
+    bins: int = 256,
+    log_scale: bool = True,
+    percentile_lines: tuple = (1, 5, 95, 99)
+) -> None:
+    """
+    Plot intensity histogram with percentile markers.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D volume
+    save_path : str or Path, optional
+        Path to save figure
+    title : str, default='Intensity Histogram'
+        Figure title
+    bins : int, default=256
+        Number of histogram bins
+    log_scale : bool, default=True
+        Use log scale for y-axis
+    percentile_lines : tuple, default=(1, 5, 95, 99)
+        Percentile values to mark with vertical lines
+    """
+    fig, ax = plt.subplots(figsize=(8, 4), facecolor=STYLE["facecolor"])
+    _apply_dark_style(ax, fig)
+
+    flat = volume.ravel()
+    ax.hist(flat, bins=bins, color="#3498db", alpha=0.8, edgecolor="none")
+
+    if log_scale:
+        ax.set_yscale("log")
+
+    # Add percentile lines
+    colors = ["#e74c3c", "#f39c12", "#f39c12", "#e74c3c"]
+    for p, c in zip(percentile_lines, colors):
+        val = np.percentile(flat, p)
+        ax.axvline(val, color=c, linestyle="--", alpha=0.8, linewidth=1.5)
+        ax.text(val, ax.get_ylim()[1] * 0.9, f"{p}%",
+                color=c, fontsize=8, ha="center", va="top")
+
+    ax.set_xlabel("Intensity", color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+    ax.set_ylabel("Count", color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+    ax.set_title(title, color=STYLE["text_color"], fontsize=STYLE["title_size"], fontweight="bold")
+
+    ax.grid(True, alpha=STYLE["grid_alpha"], color=STYLE["grid_color"])
+    _save_or_show(fig, save_path)
+
+
+def plot_segmentation_mask(
+    volume: np.ndarray,
+    mask: np.ndarray,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Segmentation Mask",
+    slice_idx: Optional[int] = None,
+    alpha: float = 0.4
+) -> None:
+    """
+    Plot volume slice with segmentation mask overlay.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D volume (Z, Y, X)
+    mask : ndarray
+        Binary mask (Z, Y, X)
+    save_path : str or Path, optional
+        Path to save figure
+    title : str, default='Segmentation Mask'
+        Figure title
+    slice_idx : int, optional
+        Z-slice to display, None uses middle slice
+    alpha : float, default=0.4
+        Mask overlay transparency
+    """
+    if slice_idx is None:
+        slice_idx = volume.shape[0] // 2
+
+    fig, axes = plt.subplots(1, 3, figsize=(12, 4), facecolor=STYLE["facecolor"])
+
+    vol_slice = volume[slice_idx]
+    mask_slice = mask[slice_idx]
+
+    # Normalize volume for display
+    vmin, vmax = np.percentile(vol_slice, [1, 99])
+    vol_norm = np.clip((vol_slice - vmin) / (vmax - vmin + 1e-8), 0, 1)
+
+    # Original
+    _apply_dark_style(axes[0])
+    axes[0].imshow(vol_norm, cmap="gray")
+    axes[0].set_title("Original", color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+    axes[0].set_xticks([])
+    axes[0].set_yticks([])
+
+    # Mask
+    _apply_dark_style(axes[1])
+    axes[1].imshow(mask_slice, cmap="Reds")
+    axes[1].set_title("Mask", color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+    axes[1].set_xticks([])
+    axes[1].set_yticks([])
+
+    # Overlay
+    _apply_dark_style(axes[2])
+    axes[2].imshow(vol_norm, cmap="gray")
+    mask_overlay = np.ma.masked_where(mask_slice == 0, mask_slice)
+    axes[2].imshow(mask_overlay, cmap="Reds", alpha=alpha)
+    axes[2].set_title("Overlay", color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+    axes[2].set_xticks([])
+    axes[2].set_yticks([])
+
+    fig.suptitle(f"{title} (z={slice_idx})", color=STYLE["text_color"],
+                 fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_registration_result(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    transformed_volume: np.ndarray,
+    transform: dict,
+    save_path: Optional[Union[str, Path]] = None,
+    slice_idx: Optional[int] = None
+) -> None:
+    """
+    Plot registration result showing before/after alignment.
+
+    Parameters
+    ----------
+    ref_volume : ndarray
+        Reference volume (Z, Y, X)
+    moving_volume : ndarray
+        Original moving volume before registration
+    transformed_volume : ndarray
+        Moving volume after registration
+    transform : dict
+        Transform parameters from estimate_registration
+    save_path : str or Path, optional
+        Path to save figure
+    slice_idx : int, optional
+        Z-slice to display, None uses middle
+    """
+    if slice_idx is None:
+        slice_idx = ref_volume.shape[0] // 2
+
+    fig, axes = plt.subplots(2, 3, figsize=(12, 8), facecolor=STYLE["facecolor"])
+
+    slices = [
+        ref_volume[slice_idx],
+        moving_volume[slice_idx],
+        transformed_volume[slice_idx]
+    ]
+    titles = ["Reference", "Moving (before)", "Moving (after)"]
+
+    # Top row: individual images
+    for ax, s, t in zip(axes[0], slices, titles):
+        _apply_dark_style(ax)
+        vmin, vmax = np.percentile(s, [1, 99])
+        ax.imshow(s, cmap="gray", vmin=vmin, vmax=vmax)
+        ax.set_title(t, color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+        ax.set_xticks([])
+        ax.set_yticks([])
+
+    # Bottom row: overlays (ref=magenta, moving=green)
+    def create_overlay(ref, mov):
+        vmin_r, vmax_r = np.percentile(ref, [1, 99])
+        vmin_m, vmax_m = np.percentile(mov, [1, 99])
+        ref_norm = np.clip((ref - vmin_r) / (vmax_r - vmin_r + 1e-8), 0, 1)
+        mov_norm = np.clip((mov - vmin_m) / (vmax_m - vmin_m + 1e-8), 0, 1)
+        overlay = np.stack([ref_norm, mov_norm, ref_norm], axis=-1)
+        return overlay
+
+    # Before registration
+    _apply_dark_style(axes[1, 0])
+    overlay_before = create_overlay(slices[0], slices[1])
+    axes[1, 0].imshow(overlay_before)
+    axes[1, 0].set_title("Before (ref=magenta, mov=green)", color=STYLE["text_color"],
+                         fontsize=STYLE["label_size"], fontweight="bold")
+    axes[1, 0].set_xticks([])
+    axes[1, 0].set_yticks([])
+
+    # After registration
+    _apply_dark_style(axes[1, 1])
+    overlay_after = create_overlay(slices[0], slices[2])
+    axes[1, 1].imshow(overlay_after)
+    axes[1, 1].set_title("After (ref=magenta, mov=green)", color=STYLE["text_color"],
+                         fontsize=STYLE["label_size"], fontweight="bold")
+    axes[1, 1].set_xticks([])
+    axes[1, 1].set_yticks([])
+
+    # Transform info
+    _apply_dark_style(axes[1, 2])
+    axes[1, 2].axis("off")
+    info_text = (
+        f"Transform Parameters\n"
+        f"─────────────────────\n"
+        f"X offset: {transform.get('x_offset', 0):.2f} px\n"
+        f"Y offset: {transform.get('y_offset', 0):.2f} px\n"
+        f"Z offset: {transform.get('z_offset', 0):.2f} px\n"
+        f"Rotation: {transform.get('rotation', 0):.2f} deg\n"
+        f"Correlation: {transform.get('correlation', 0):.4f}\n"
+        f"Method: {transform.get('method', 'unknown')}"
+    )
+    axes[1, 2].text(0.5, 0.5, info_text, transform=axes[1, 2].transAxes,
+                    fontsize=STYLE["font_size"], color=STYLE["text_color"],
+                    ha="center", va="center", family="monospace")
+
+    fig.suptitle(f"Registration Result (z={slice_idx})", color=STYLE["text_color"],
+                 fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_intensity_correction(
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    corrected_volume: np.ndarray,
+    correction: dict,
+    save_path: Optional[Union[str, Path]] = None
+) -> None:
+    """
+    Plot intensity correction result with histograms.
+
+    Parameters
+    ----------
+    ref_volume : ndarray
+        Reference volume
+    moving_volume : ndarray
+        Moving volume before correction
+    corrected_volume : ndarray
+        Moving volume after correction
+    correction : dict
+        Correction parameters from estimate_intensity_correction
+    save_path : str or Path, optional
+        Path to save figure
+    """
+    fig, axes = plt.subplots(1, 3, figsize=(12, 4), facecolor=STYLE["facecolor"])
+
+    # Sample for histograms
+    ref_sample = ref_volume.ravel()[::100]
+    mov_sample = moving_volume.ravel()[::100]
+    corr_sample = corrected_volume.ravel()[::100]
+
+    bins = np.linspace(0, np.percentile(ref_sample, 99.5), 100)
+
+    _apply_dark_style(axes[0], fig)
+    axes[0].hist(ref_sample, bins=bins, alpha=0.7, color="#3498db", label="Reference")
+    axes[0].hist(mov_sample, bins=bins, alpha=0.7, color="#e74c3c", label="Moving")
+    axes[0].set_xlabel("Intensity", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[0].set_ylabel("Count", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[0].set_title("Before Correction", color=STYLE["text_color"],
+                      fontsize=STYLE["label_size"], fontweight="bold")
+    axes[0].legend(facecolor=STYLE["facecolor"], edgecolor=STYLE["text_color"],
+                   labelcolor=STYLE["text_color"], fontsize=8)
+
+    _apply_dark_style(axes[1], fig)
+    axes[1].hist(ref_sample, bins=bins, alpha=0.7, color="#3498db", label="Reference")
+    axes[1].hist(corr_sample, bins=bins, alpha=0.7, color="#2ecc71", label="Corrected")
+    axes[1].set_xlabel("Intensity", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[1].set_ylabel("Count", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[1].set_title("After Correction", color=STYLE["text_color"],
+                      fontsize=STYLE["label_size"], fontweight="bold")
+    axes[1].legend(facecolor=STYLE["facecolor"], edgecolor=STYLE["text_color"],
+                   labelcolor=STYLE["text_color"], fontsize=8)
+
+    # Correction info
+    _apply_dark_style(axes[2], fig)
+    axes[2].axis("off")
+    info_text = (
+        f"Intensity Correction\n"
+        f"─────────────────────\n"
+        f"Factor: {correction.get('factor', 1.0):.4f}\n"
+        f"Operation: {correction.get('operation', 'multiply')}\n"
+        f"Ref background: {correction.get('ref_background', 0):.1f}\n"
+        f"Mov background: {correction.get('moving_background', 0):.1f}\n"
+        f"Overlap corr: {correction.get('overlap_correlation', 0):.4f}\n"
+        f"Method: {correction.get('method', 'unknown')}"
+    )
+    axes[2].text(0.5, 0.5, info_text, transform=axes[2].transAxes,
+                 fontsize=STYLE["font_size"], color=STYLE["text_color"],
+                 ha="center", va="center", family="monospace")
+
+    fig.suptitle("Intensity Correction", color=STYLE["text_color"],
+                 fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_fusion_result(
+    view1: np.ndarray,
+    view2: np.ndarray,
+    fused: np.ndarray,
+    save_path: Optional[Union[str, Path]] = None,
+    slice_idx: Optional[int] = None,
+    title: str = "Fusion Result"
+) -> None:
+    """
+    Plot fusion result comparing input views and fused output.
+
+    Parameters
+    ----------
+    view1 : ndarray
+        First input view (Z, Y, X)
+    view2 : ndarray
+        Second input view (Z, Y, X)
+    fused : ndarray
+        Fused output (Z, Y, X)
+    save_path : str or Path, optional
+        Path to save figure
+    slice_idx : int, optional
+        Z-slice to display, None uses middle
+    title : str, default='Fusion Result'
+        Figure title
+    """
+    if slice_idx is None:
+        slice_idx = view1.shape[0] // 2
+
+    fig, axes = plt.subplots(2, 2, figsize=(10, 10), facecolor=STYLE["facecolor"])
+
+    slices = [view1[slice_idx], view2[slice_idx], fused[slice_idx]]
+    titles = ["View 1", "View 2", "Fused"]
+
+    for ax, s, t in zip(axes.flat[:3], slices, titles):
+        _apply_dark_style(ax)
+        vmin, vmax = np.percentile(s, [1, 99])
+        ax.imshow(s, cmap="gray", vmin=vmin, vmax=vmax)
+        ax.set_title(t, color=STYLE["text_color"], fontsize=STYLE["label_size"], fontweight="bold")
+        ax.set_xticks([])
+        ax.set_yticks([])
+
+    # Difference/comparison
+    _apply_dark_style(axes[1, 1])
+    # Show fused with color indicating which view dominates
+    v1_norm = (view1[slice_idx] - view1[slice_idx].min()) / (view1[slice_idx].max() - view1[slice_idx].min() + 1e-8)
+    v2_norm = (view2[slice_idx] - view2[slice_idx].min()) / (view2[slice_idx].max() - view2[slice_idx].min() + 1e-8)
+    f_norm = (fused[slice_idx] - fused[slice_idx].min()) / (fused[slice_idx].max() - fused[slice_idx].min() + 1e-8)
+    # RGB: R=view1 contribution, G=fused, B=view2 contribution
+    comparison = np.stack([v1_norm, f_norm, v2_norm], axis=-1)
+    axes[1, 1].imshow(comparison)
+    axes[1, 1].set_title("Comparison (R=V1, G=fused, B=V2)", color=STYLE["text_color"],
+                         fontsize=STYLE["label_size"], fontweight="bold")
+    axes[1, 1].set_xticks([])
+    axes[1, 1].set_yticks([])
+
+    fig.suptitle(f"{title} (z={slice_idx})", color=STYLE["text_color"],
+                 fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_blending_weights(
+    mask: np.ndarray,
+    blending_range: int,
+    save_path: Optional[Union[str, Path]] = None,
+    slice_idx: Optional[int] = None
+) -> None:
+    """
+    Plot blending weight map from transition mask.
+
+    Parameters
+    ----------
+    mask : ndarray
+        Transition mask (X, Z) with Y-indices
+    blending_range : int
+        Blending zone width in pixels
+    save_path : str or Path, optional
+        Path to save figure
+    slice_idx : int, optional
+        Z-slice for 1D profile, None uses middle
+    """
+    if slice_idx is None:
+        slice_idx = mask.shape[1] // 2
+
+    fig, axes = plt.subplots(1, 2, figsize=(12, 5), facecolor=STYLE["facecolor"])
+
+    # 2D transition plane visualization
+    _apply_dark_style(axes[0], fig)
+    im = axes[0].imshow(mask.T, cmap="viridis", aspect="auto")
+    axes[0].set_xlabel("X", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[0].set_ylabel("Z", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[0].set_title("Transition Plane (Y-index)", color=STYLE["text_color"],
+                      fontsize=STYLE["label_size"], fontweight="bold")
+    cbar = plt.colorbar(im, ax=axes[0])
+    cbar.ax.yaxis.set_tick_params(color=STYLE["text_color"])
+    cbar.ax.yaxis.set_ticklabels(cbar.ax.yaxis.get_ticklabels(), color=STYLE["text_color"])
+
+    # 1D profile at selected z
+    _apply_dark_style(axes[1], fig)
+    profile = mask[:, slice_idx]
+    x = np.arange(len(profile))
+    axes[1].plot(x, profile, color="#3498db", linewidth=2, label="Transition Y")
+    axes[1].fill_between(x, profile - blending_range, profile + blending_range,
+                         alpha=0.3, color="#3498db", label=f"Blend zone (±{blending_range})")
+    axes[1].set_xlabel("X", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[1].set_ylabel("Y (transition)", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[1].set_title(f"Profile at z={slice_idx}", color=STYLE["text_color"],
+                      fontsize=STYLE["label_size"], fontweight="bold")
+    axes[1].legend(facecolor=STYLE["facecolor"], edgecolor=STYLE["text_color"],
+                   labelcolor=STYLE["text_color"], fontsize=8)
+    axes[1].grid(True, alpha=STYLE["grid_alpha"], color=STYLE["grid_color"])
+
+    fig.suptitle("Blending Weights", color=STYLE["text_color"],
+                 fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_temporal_parameters(
+    timepoints: np.ndarray,
+    parameters: dict,
+    smoothed_parameters: Optional[dict] = None,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Temporal Parameters"
+) -> None:
+    """
+    Plot registration parameters over time.
+
+    Parameters
+    ----------
+    timepoints : ndarray
+        Time point indices
+    parameters : dict
+        Raw parameters (x_offset, y_offset, rotation, etc.)
+    smoothed_parameters : dict, optional
+        Smoothed parameters for comparison
+    save_path : str or Path, optional
+        Path to save figure
+    title : str, default='Temporal Parameters'
+        Figure title
+    """
+    fig, axes = plt.subplots(2, 2, figsize=(12, 8), facecolor=STYLE["facecolor"])
+
+    param_names = ["x_offset", "y_offset", "rotation", "intensity_factor"]
+    ylabels = ["X Offset (px)", "Y Offset (px)", "Rotation (deg)", "Intensity Factor"]
+    colors = ["#3498db", "#2ecc71", "#e74c3c", "#f39c12"]
+
+    for ax, param, ylabel, color in zip(axes.flat, param_names, ylabels, colors):
+        _apply_dark_style(ax, fig)
+
+        if param in parameters:
+            ax.plot(timepoints, parameters[param], "o-", color=color, alpha=0.6,
+                    markersize=3, linewidth=1, label="Raw")
+
+        if smoothed_parameters and param in smoothed_parameters:
+            ax.plot(timepoints, smoothed_parameters[param], "-", color=color,
+                    linewidth=2, label="Smoothed")
+
+        ax.set_xlabel("Timepoint", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+        ax.set_ylabel(ylabel, color=STYLE["text_color"], fontsize=STYLE["label_size"])
+        ax.grid(True, alpha=STYLE["grid_alpha"], color=STYLE["grid_color"])
+
+        if smoothed_parameters:
+            ax.legend(facecolor=STYLE["facecolor"], edgecolor=STYLE["text_color"],
+                      labelcolor=STYLE["text_color"], fontsize=8)
+
+    fig.suptitle(title, color=STYLE["text_color"], fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_correlation_heatmap(
+    correlations: np.ndarray,
+    timepoints: np.ndarray,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Registration Correlation"
+) -> None:
+    """
+    Plot registration correlation quality over time.
+
+    Parameters
+    ----------
+    correlations : ndarray
+        Correlation values per timepoint
+    timepoints : ndarray
+        Time point indices
+    save_path : str or Path, optional
+        Path to save figure
+    title : str, default='Registration Correlation'
+        Figure title
+    """
+    fig, axes = plt.subplots(1, 2, figsize=(12, 4), facecolor=STYLE["facecolor"])
+
+    # Line plot
+    _apply_dark_style(axes[0], fig)
+    axes[0].plot(timepoints, correlations, "o-", color="#3498db", markersize=4, linewidth=1.5)
+    axes[0].axhline(np.mean(correlations), color="#e74c3c", linestyle="--",
+                    linewidth=1.5, label=f"Mean: {np.mean(correlations):.4f}")
+    axes[0].set_xlabel("Timepoint", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[0].set_ylabel("Correlation", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[0].set_title("Correlation Over Time", color=STYLE["text_color"],
+                      fontsize=STYLE["label_size"], fontweight="bold")
+    axes[0].grid(True, alpha=STYLE["grid_alpha"], color=STYLE["grid_color"])
+    axes[0].legend(facecolor=STYLE["facecolor"], edgecolor=STYLE["text_color"],
+                   labelcolor=STYLE["text_color"], fontsize=8)
+
+    # Histogram
+    _apply_dark_style(axes[1], fig)
+    axes[1].hist(correlations, bins=30, color="#3498db", alpha=0.8, edgecolor="none")
+    axes[1].axvline(np.mean(correlations), color="#e74c3c", linestyle="--",
+                    linewidth=1.5, label=f"Mean: {np.mean(correlations):.4f}")
+    axes[1].set_xlabel("Correlation", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[1].set_ylabel("Count", color=STYLE["text_color"], fontsize=STYLE["label_size"])
+    axes[1].set_title("Correlation Distribution", color=STYLE["text_color"],
+                      fontsize=STYLE["label_size"], fontweight="bold")
+    axes[1].legend(facecolor=STYLE["facecolor"], edgecolor=STYLE["text_color"],
+                   labelcolor=STYLE["text_color"], fontsize=8)
+
+    fig.suptitle(title, color=STYLE["text_color"], fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def plot_volume_overview(
+    volume: np.ndarray,
+    save_path: Optional[Union[str, Path]] = None,
+    title: str = "Volume Overview",
+    n_slices: int = 9
+) -> None:
+    """
+    Plot grid of evenly spaced Z-slices through volume.
+
+    Parameters
+    ----------
+    volume : ndarray
+        3D volume (Z, Y, X)
+    save_path : str or Path, optional
+        Path to save figure
+    title : str, default='Volume Overview'
+        Figure title
+    n_slices : int, default=9
+        Number of slices to display (must be square-rootable)
+    """
+    n_rows = int(np.sqrt(n_slices))
+    n_cols = int(np.ceil(n_slices / n_rows))
+
+    Z = volume.shape[0]
+    slice_indices = np.linspace(0, Z - 1, n_slices, dtype=int)
+
+    fig, axes = plt.subplots(n_rows, n_cols, figsize=(3 * n_cols, 3 * n_rows),
+                             facecolor=STYLE["facecolor"])
+
+    vmin, vmax = np.percentile(volume, [1, 99])
+
+    for idx, (ax, z) in enumerate(zip(axes.flat, slice_indices)):
+        _apply_dark_style(ax)
+        ax.imshow(volume[z], cmap="gray", vmin=vmin, vmax=vmax)
+        ax.set_title(f"z={z}", color=STYLE["text_color"], fontsize=STYLE["font_size"])
+        ax.set_xticks([])
+        ax.set_yticks([])
+
+    # Hide extra axes
+    for ax in axes.flat[n_slices:]:
+        ax.axis("off")
+
+    fig.suptitle(title, color=STYLE["text_color"], fontsize=STYLE["title_size"], fontweight="bold")
+    plt.tight_layout()
+    _save_or_show(fig, save_path)
+
+
+def save_fusion_diagnostics(
+    output_dir: Union[str, Path],
+    ref_volume: np.ndarray,
+    moving_volume: np.ndarray,
+    transformed_volume: np.ndarray,
+    fused_volume: np.ndarray,
+    transform: dict,
+    correction: dict,
+    mask: np.ndarray,
+    blending_range: int,
+    prefix: str = ""
+) -> None:
+    """
+    Save complete set of fusion diagnostic images.
+
+    Parameters
+    ----------
+    output_dir : str or Path
+        Directory to save images
+    ref_volume : ndarray
+        Reference volume
+    moving_volume : ndarray
+        Original moving volume
+    transformed_volume : ndarray
+        Transformed moving volume
+    fused_volume : ndarray
+        Final fused result
+    transform : dict
+        Registration transform parameters
+    correction : dict
+        Intensity correction parameters
+    mask : ndarray
+        Blending transition mask
+    blending_range : int
+        Blending zone width
+    prefix : str, default=''
+        Prefix for filenames
+    """
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    pre = f"{prefix}_" if prefix else ""
+
+    # Registration
+    plot_registration_result(
+        ref_volume, moving_volume, transformed_volume, transform,
+        save_path=output_dir / f"{pre}registration.png"
+    )
+
+    # Intensity correction
+    corrected_volume = transformed_volume.copy()  # Apply correction inline if needed
+    plot_intensity_correction(
+        ref_volume, transformed_volume, corrected_volume, correction,
+        save_path=output_dir / f"{pre}intensity_correction.png"
+    )
+
+    # Fusion result
+    plot_fusion_result(
+        ref_volume, transformed_volume, fused_volume,
+        save_path=output_dir / f"{pre}fusion_result.png"
+    )
+
+    # Blending weights
+    plot_blending_weights(
+        mask, blending_range,
+        save_path=output_dir / f"{pre}blending_weights.png"
+    )
+
+    # Volume overview
+    plot_volume_overview(
+        fused_volume,
+        save_path=output_dir / f"{pre}fused_overview.png"
+    )
+
+    print(f"Saved fusion diagnostics to {output_dir}")