fix(ui): prediction overlay invisible, race condition, thread safety (#23) (#23)

Primary fix: Prediction mask probability values (0.0-0.3) rendered nearly-white
in "Reds" colormap. Now binarized at 0.5 threshold for visible red overlay.

Additional fixes discovered during audit:
- Race condition: replaced global _previous_results_dir with gr.State
- compute_volume_ml: added threshold=0.5 for consistent binarization
- render_3panel_view: wired into UI with Tabs layout (Interactive 3D / Static Report)
- Matplotlib thread safety: refactored from pyplot to OO API (Figure())

All 136 tests pass. Lint and type checks clean.

docs/specs/23-slice-comparison-overlay-bug.md

@@ -0,0 +1,287 @@
+# Bug Investigation: Slice Comparison Prediction Overlay Not Visible
+
+**Issue**: Prediction overlay is invisible in slice comparison while ground truth overlay is visible
+
+**Date**: 2025-12-09
+**Branch**: `debug/slice-comparison-prediction-overlay`
+
+---
+
+## Observed Behavior
+
+In the Gradio UI "Slice Comparison" tab:
+- **DWI Input** (left panel): Shows grayscale brain scan ✓
+- **Prediction** (middle panel): Shows grayscale brain scan **without any visible overlay** ✗
+- **Ground Truth** (right panel): Shows grayscale brain scan **with green overlay** ✓
+
+## Expected Behavior
+
+The Prediction panel should show a **red overlay** on the predicted lesion area, similar to how Ground Truth shows a green overlay.
+
+---
+
+## Code Analysis
+
+### Visualization Code (`viewer.py:261-268`)
+
+```python
+# Prediction panel
+axes[1].imshow(d_slice, cmap="gray")
+axes[1].imshow(
+    np.ma.masked_where(p_slice == 0, p_slice),
+    cmap="Reds",
+    alpha=0.5,
+    vmin=0,
+    vmax=1,
+)
+```
+
+### Ground Truth Code (`viewer.py:273-280`)
+
+```python
+# Ground Truth panel
+axes[2].imshow(d_slice, cmap="gray")
+axes[2].imshow(
+    np.ma.masked_where(g_slice == 0, g_slice),
+    cmap="Greens",
+    alpha=0.5,
+    vmin=0,
+    vmax=1,
+)
+```
+
+The code is **structurally identical**. The only difference is:
+- Prediction: `cmap="Reds"`
+- Ground Truth: `cmap="Greens"`
+
+---
+
+## Hypothesis
+
+### Primary Hypothesis: Probability vs Binary Mask Values
+
+| Mask Type | Typical Values | Colormap Rendering | Visibility |
+|-----------|----------------|-------------------|------------|
+| Ground Truth | Binary (0 or 1) | 1.0 → **Dark Green** | High ✓ |
+| Prediction | Probabilities (0.0-0.3) | 0.1 → **Nearly White** | None ✗ |
+
+**Why this matters:**
+
+1. Matplotlib's **"Reds" colormap** goes from white (0) → red (1)
+2. With `vmin=0, vmax=1`:
+   - A value of `0.05` maps to 5% of the colormap = nearly white
+   - A value of `1.0` maps to 100% of the colormap = red
+3. With `alpha=0.5` over a grayscale background, nearly-white overlays are **invisible**
+
+**Evidence:**
+- DeepISLES SEALS model may output probability maps, not binary masks
+- The `compute_dice` function in `metrics.py` applies a `threshold=0.5` to binarize predictions
+- The visualization does **not** apply any thresholding before display
+
+### Alternative Hypotheses
+
+1. **Empty slice**: Prediction mask is all zeros at the selected slice (unlikely given the slice selection logic uses `get_slice_at_max_lesion(prediction_path)`)
+
+2. **Data type issue**: Float comparison `p_slice == 0` may fail for float32 arrays (unlikely - works for ground truth)
+
+3. **File path mismatch**: Wrong file being loaded as prediction (need to verify)
+
+---
+
+## Diagnostic Steps
+
+### 1. Check Prediction Mask Values
+
+```python
+import nibabel as nib
+import numpy as np
+
+# Load a prediction mask from a recent run
+pred = nib.load("/path/to/prediction.nii.gz").get_fdata()
+print(f"Shape: {pred.shape}")
+print(f"Dtype: {pred.dtype}")
+print(f"Min: {pred.min()}, Max: {pred.max()}")
+print(f"Unique values: {np.unique(pred)[:20]}")  # First 20 unique values
+print(f"Non-zero count: {np.count_nonzero(pred)}")
+print(f"Values > 0.5: {np.count_nonzero(pred > 0.5)}")
+```
+
+### 2. Check Ground Truth Mask Values
+
+```python
+gt = nib.load("/path/to/ground_truth.nii.gz").get_fdata()
+print(f"Shape: {gt.shape}")
+print(f"Dtype: {gt.dtype}")
+print(f"Min: {gt.min()}, Max: {gt.max()}")
+print(f"Unique values: {np.unique(gt)}")
+```
+
+### 3. Visual Comparison
+
+```python
+# Plot histogram of values
+import matplotlib.pyplot as plt
+fig, axes = plt.subplots(1, 2)
+axes[0].hist(pred[pred > 0].flatten(), bins=50)
+axes[0].set_title("Prediction non-zero values")
+axes[1].hist(gt[gt > 0].flatten(), bins=50)
+axes[1].set_title("Ground Truth non-zero values")
+plt.savefig("mask_histograms.png")
+```
+
+---
+
+## Proposed Fix
+
+### Option A: Binarize Prediction Before Display (Recommended)
+
+```python
+# In render_slice_comparison, before creating overlay:
+p_slice_binary = (p_slice > 0.5).astype(float)
+
+axes[1].imshow(
+    np.ma.masked_where(p_slice_binary == 0, p_slice_binary),
+    cmap="Reds",
+    alpha=0.5,
+    vmin=0,
+    vmax=1,
+)
+```
+
+**Pros:**
+- Consistent with how `compute_dice` treats predictions
+- Clear visualization of model decision boundary
+- Matches clinical interpretation (lesion vs not-lesion)
+
+**Cons:**
+- Loses probability information in visualization
+
+### Option B: Dynamic Normalization
+
+```python
+# Normalize to actual value range instead of fixed 0-1
+p_max = p_slice.max() if p_slice.max() > 0 else 1.0
+axes[1].imshow(
+    np.ma.masked_where(p_slice == 0, p_slice),
+    cmap="Reds",
+    alpha=0.5,
+    vmin=0,
+    vmax=p_max,
+)
+```
+
+**Pros:**
+- Shows probability information
+- Works regardless of value range
+
+**Cons:**
+- Inconsistent intensity across cases
+- Low-confidence predictions still appear bright (misleading)
+
+### Option C: Threshold-Based Masking
+
+```python
+# Only show values above a threshold
+threshold = 0.5
+axes[1].imshow(
+    np.ma.masked_where(p_slice < threshold, p_slice),
+    cmap="Reds",
+    alpha=0.5,
+    vmin=threshold,
+    vmax=1.0,
+)
+```
+
+**Pros:**
+- Only shows confident predictions
+- Good dynamic range for visible values
+
+**Cons:**
+- May hide uncertain but potentially relevant areas
+
+---
+
+## Recommendation
+
+**Implement Option A (Binarize)** because:
+
+1. It matches the clinical use case (segmentation → binary decision)
+2. It's consistent with `compute_dice` threshold behavior
+3. It provides clear, interpretable visualization
+4. The raw probability map can still be viewed in NiiVue if needed
+
+---
+
+## Dependencies
+
+| Package | Version | Relevant |
+|---------|---------|----------|
+| gradio | >=6.0.0 | Unlikely cause (renders matplotlib figure correctly) |
+| matplotlib | >=3.8.0 | Colormap behavior is standard |
+| numpy | >=1.26.0,<2.0.0 | Float comparison works correctly |
+| nibabel | >=5.2.0 | Loads data correctly |
+
+---
+
+## Resolution
+
+**Status**: FIXED (2025-12-09)
+**Branch**: `debug/slice-comparison-prediction-overlay`
+
+### Changes Made
+
+**Primary Fix (Issue #23):**
+
+1. **`viewer.py:270-275`**: Added binarization of prediction mask in `render_slice_comparison`:
+   ```python
+   # Binarize prediction at threshold 0.5 for visible overlay (Issue #23)
+   p_slice_binary = (p_slice > 0.5).astype(float)
+   ```
+
+2. **`viewer.py:156-164`**: Added binarization in `render_3panel_view` for consistency
+
+3. **`tests/conftest.py`**: Added `synthetic_probability_mask` and `synthetic_binary_mask` fixtures
+
+4. **`tests/ui/test_viewer.py`**: Added `TestRenderSliceComparisonProbabilityMask` test class
+
+**Additional Fixes (Found During Audit):**
+
+5. **Race Condition (P2)**: Replaced global `_previous_results_dir` with `gr.State` for per-session thread-safe cleanup tracking
+
+6. **Inconsistent Threshold in compute_volume_ml**: Added `threshold=0.5` parameter for consistent binarization
+
+7. **render_3panel_view Wired Into UI**:
+   - Added `gr.Tabs` layout with "Interactive 3D" and "Static Report" tabs
+   - `render_3panel_view` now displayed in "Static Report" alongside slice comparison
+   - Provides WebGL2 fallback via static matplotlib figures
+
+8. **Thread-Safe Matplotlib**: Refactored from `pyplot` API to Object-Oriented API (`Figure()`) for multi-user safety
+
+### Verification
+
+- All 136 tests pass
+- Lint (ruff) passes
+- Type check (mypy) passes
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `src/stroke_deepisles_demo/ui/viewer.py` | OO matplotlib API, binarization in both render functions |
+| `src/stroke_deepisles_demo/ui/app.py` | gr.State, render_3panel_view integration, volume_ml |
+| `src/stroke_deepisles_demo/ui/components.py` | Tabs layout (Interactive 3D / Static Report) |
+| `src/stroke_deepisles_demo/metrics.py` | threshold parameter for compute_volume_ml |
+| `tests/conftest.py` | New probability/binary mask fixtures |
+| `tests/ui/test_viewer.py` | Probability mask tests |
+| `tests/ui/test_app.py` | Updated for new return signature |
+
+## Next Steps
+
+1. [x] Run diagnostic script to confirm hypothesis
+2. [x] Implement fix (Option A - binarize)
+3. [x] Add test case for probability-valued masks
+4. [x] Wire render_3panel_view into UI with tabs
+5. [x] Fix race condition with gr.State
+6. [x] Make matplotlib thread-safe with OO API
+7. [ ] Verify fix in local Gradio app (manual testing recommended)
+8. [ ] Create PR and merge to main

src/stroke_deepisles_demo/metrics.py

@@ -91,6 +91,8 @@ def compute_dice(
 def compute_volume_ml(
     mask: Path | NDArray[np.floating[Any]],
     voxel_size_mm: tuple[float, float, float] | None = None,
+    *,
+    threshold: float = 0.5,
 ) -> float:
     """
     Compute lesion volume in milliliters.
@@ -98,9 +100,14 @@ def compute_volume_ml(
     Args:
         mask: Path to NIfTI file or numpy array
         voxel_size_mm: Voxel dimensions in mm (read from NIfTI if None)
+        threshold: Threshold for binarization (default 0.5 for consistency with compute_dice)
 
     Returns:
         Volume in milliliters (mL)
+
+    Note:
+        Uses the same default threshold (0.5) as compute_dice for consistency.
+        This ensures the volume measurement matches the clinical segmentation decision boundary.
     """
     if isinstance(mask, Path):
         data, loaded_zooms = load_nifti_as_array(mask)
@@ -110,7 +117,8 @@ def compute_volume_ml(
         # Default to 1mm isotropic if not provided for array
         voxel_dims = voxel_size_mm if voxel_size_mm is not None else (1.0, 1.0, 1.0)
 
-    volume_voxels = np.sum(data > 0)
+    # Binarize at threshold for consistent measurement with compute_dice
+    volume_voxels = np.sum(data > threshold)
     voxel_vol_mm3 = math.prod(voxel_dims)
 
     return float(volume_voxels * voxel_vol_mm3 / 1000.0)  # mm3 -> mL

src/stroke_deepisles_demo/ui/app.py

@@ -3,13 +3,15 @@
 from __future__ import annotations
 
 import shutil
-from typing import TYPE_CHECKING, Any
+from pathlib import Path
+from typing import Any
 
 import gradio as gr
 from matplotlib.figure import Figure  # noqa: TC002
 
 from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.data import list_case_ids
+from stroke_deepisles_demo.metrics import compute_volume_ml
 from stroke_deepisles_demo.pipeline import run_pipeline_on_case
 from stroke_deepisles_demo.ui.components import (
     create_case_selector,
@@ -20,17 +22,12 @@ from stroke_deepisles_demo.ui.viewer import (
     NIIVUE_UPDATE_JS,
     create_niivue_html,
     nifti_to_gradio_url,
+    render_3panel_view,
     render_slice_comparison,
 )
 
-if TYPE_CHECKING:
-    from pathlib import Path
-
 logger = get_logger(__name__)
 
-# Shared output directory for UI results (cleaned up between runs to prevent disk accumulation)
-_previous_results_dir: Path | None = None
-
 
 def initialize_case_selector() -> gr.Dropdown:
     """
@@ -57,9 +54,26 @@ def initialize_case_selector() -> gr.Dropdown:
         return gr.Dropdown(choices=[], info=f"Error loading data: {e!s}")
 
 
+def _cleanup_previous_results(previous_results_dir: str | None) -> None:
+    """Clean up previous results directory (per-session, thread-safe)."""
+    if previous_results_dir is None:
+        return
+    prev_path = Path(previous_results_dir)
+    if prev_path.exists():
+        try:
+            shutil.rmtree(prev_path)
+            logger.debug("Cleaned up previous results: %s", prev_path)
+        except OSError as e:
+            # Log but don't fail - cleanup is best-effort
+            logger.warning("Failed to cleanup %s: %s", prev_path, e)
+
+
 def run_segmentation(
-    case_id: str, fast_mode: bool, show_ground_truth: bool
-) -> tuple[str, Figure | None, dict[str, Any], str | None, str]:
+    case_id: str,
+    fast_mode: bool,
+    show_ground_truth: bool,
+    previous_results_dir: str | None,
+) -> tuple[str, Figure | None, Figure | None, dict[str, Any], str | None, str, str | None]:
     """
     Run segmentation and return results for display.
 
@@ -67,30 +81,26 @@ def run_segmentation(
         case_id: Selected case identifier
         fast_mode: Whether to use fast mode (SEALS)
         show_ground_truth: Whether to show ground truth in plots
+        previous_results_dir: Path to previous results (from gr.State, for cleanup)
 
     Returns:
-        Tuple of (niivue_html, slice_fig, metrics_dict, download_path, status_msg)
+        Tuple of (niivue_html, slice_fig, ortho_fig, metrics_dict, download_path, status_msg, new_results_dir)
+        The new_results_dir is returned to update the gr.State for next cleanup.
     """
     if not case_id:
         return (
             "",
             None,
+            None,
             {},
             None,
             "Please select a case first.",
+            previous_results_dir,  # Keep existing state
         )
 
     try:
-        global _previous_results_dir
-
-        # Clean up previous results to prevent disk accumulation on HF Spaces
-        if _previous_results_dir is not None and _previous_results_dir.exists():
-            try:
-                shutil.rmtree(_previous_results_dir)
-                logger.debug("Cleaned up previous results: %s", _previous_results_dir)
-            except OSError as e:
-                # Log but don't fail - cleanup is best-effort
-                logger.warning("Failed to cleanup %s: %s", _previous_results_dir, e)
+        # Clean up previous results (per-session, thread-safe via gr.State)
+        _cleanup_previous_results(previous_results_dir)
 
         logger.info("Running segmentation for %s", case_id)
         result = run_pipeline_on_case(
@@ -100,9 +110,6 @@ def run_segmentation(
             cleanup_staging=True,
         )
 
-        # Track results_dir for cleanup on next run
-        _previous_results_dir = result.results_dir
-
         # 1. NiiVue Visualization
         # Use Gradio's file serving (Issue #19 optimization)
         # This eliminates ~65MB base64 payloads, improving load times and browser memory
@@ -122,8 +129,10 @@ def run_segmentation(
             height=500,
         )
 
-        # 2. Slice Comparison (Static Plot)
+        # 2. Static Visualizations (Matplotlib)
         gt_path = result.ground_truth if show_ground_truth else None
+
+        # 2a. Slice Comparison
         slice_fig = render_slice_comparison(
             dwi_path=dwi_path,
             prediction_path=result.prediction_mask,
@@ -131,10 +140,24 @@ def run_segmentation(
             orientation="axial",
         )
 
-        # 3. Metrics
+        # 2b. Orthogonal 3-Panel View
+        ortho_fig = render_3panel_view(
+            nifti_path=dwi_path,
+            mask_path=result.prediction_mask,
+            mask_alpha=0.5,
+        )
+
+        # 3. Metrics (including volume with consistent 0.5 threshold)
+        volume_ml: float | None = None
+        try:
+            volume_ml = round(compute_volume_ml(result.prediction_mask, threshold=0.5), 2)
+        except Exception:
+            logger.warning("Failed to compute volume for %s", case_id, exc_info=True)
+
         metrics = {
             "case_id": result.case_id,
             "dice_score": result.dice_score,
+            "volume_ml": volume_ml,
             "elapsed_seconds": round(result.elapsed_seconds, 2),
             "model": "SEALS (Fast)" if fast_mode else "Ensemble",
         }
@@ -148,11 +171,20 @@ def run_segmentation(
             else "Success!"
         )
 
-        return niivue_html, slice_fig, metrics, download_path, status_msg
+        # Return new results_dir to update gr.State for next cleanup
+        return (
+            niivue_html,
+            slice_fig,
+            ortho_fig,
+            metrics,
+            download_path,
+            status_msg,
+            str(result.results_dir),
+        )
 
     except Exception as e:
         logger.exception("Error running segmentation")
-        return "", None, {}, None, f"Error: {e!s}"
+        return "", None, None, {}, None, f"Error: {e!s}", previous_results_dir
 
 
 def create_app() -> gr.Blocks:
@@ -165,6 +197,10 @@ def create_app() -> gr.Blocks:
     with gr.Blocks(
         title="Stroke Lesion Segmentation Demo",
     ) as demo:
+        # Per-session state for cleanup tracking (fixes race condition in multi-user env)
+        # This replaces the previous global _previous_results_dir variable
+        previous_results_state = gr.State(value=None)
+
         # Header
         gr.Markdown("""
         # Stroke Lesion Segmentation Demo
@@ -197,13 +233,16 @@ def create_app() -> gr.Blocks:
                 case_selector,
                 settings["fast_mode"],
                 settings["show_ground_truth"],
+                previous_results_state,  # Pass per-session state for cleanup
             ],
             outputs=[
                 results["niivue_viewer"],
                 results["slice_plot"],
+                results["ortho_plot"],
                 results["metrics"],
                 results["download"],
                 status,
+                previous_results_state,  # Update state with new results_dir
             ],
         ).then(
             fn=None,  # Explicitly None to run JS only

src/stroke_deepisles_demo/ui/components.py

@@ -39,17 +39,21 @@ def create_results_display() -> dict[str, gr.components.Component]:
     """
     # Using gr.Group to group them visually
     with gr.Group():
-        # NiiVue visualization uses HTML with js_on_load for JavaScript execution
-        # Note: Gradio strips <script> tags from HTML value for security,
-        # so we must use js_on_load to run our NiiVue initialization code.
-        # The HTML value contains data-* attributes with volume URLs.
-        niivue_viewer = gr.HTML(
-            label="Interactive 3D Viewer",
-            js_on_load=NIIVUE_ON_LOAD_JS,
-        )
-
-        # Slice comparisons (Matplotlib)
-        slice_plot = gr.Plot(label="Slice Comparison")
+        with gr.Tabs():
+            with gr.Tab("Interactive 3D"):
+                # NiiVue visualization uses HTML with js_on_load for JavaScript execution
+                # Note: Gradio strips <script> tags from HTML value for security,
+                # so we must use js_on_load to run our NiiVue initialization code.
+                # The HTML value contains data-* attributes with volume URLs.
+                niivue_viewer = gr.HTML(
+                    label="Interactive 3D Viewer",
+                    js_on_load=NIIVUE_ON_LOAD_JS,
+                )
+
+            with gr.Tab("Static Report"):
+                # Slice comparisons (Matplotlib)
+                slice_plot = gr.Plot(label="Slice Comparison (Validation)")
+                ortho_plot = gr.Plot(label="Orthogonal Views (Anatomy)")
 
         metrics = gr.JSON(label="Metrics")
         download = gr.File(label="Download Prediction")
@@ -57,6 +61,7 @@ def create_results_display() -> dict[str, gr.components.Component]:
     return {
         "niivue_viewer": niivue_viewer,
         "slice_plot": slice_plot,
+        "ortho_plot": ortho_plot,
         "metrics": metrics,
         "download": download,
     }

src/stroke_deepisles_demo/ui/viewer.py

@@ -16,15 +16,14 @@ import json
 import uuid
 from typing import TYPE_CHECKING
 
-import matplotlib.pyplot as plt
 import numpy as np
+from matplotlib.figure import Figure
 
 from stroke_deepisles_demo.metrics import load_nifti_as_array
 
 if TYPE_CHECKING:
     from pathlib import Path
 
-    from matplotlib.figure import Figure
 
 # NiiVue version - updated to latest stable (Dec 2025)
 NIIVUE_VERSION = "0.65.0"
@@ -141,9 +140,10 @@ def render_3panel_view(
         center = coords.mean(axis=0).astype(int)
         mid_x, mid_y, mid_z = center[0], center[1], center[2]
 
-    # Create figure
-    fig, axes = plt.subplots(1, 3, figsize=(15, 5))
+    # Create figure using OO API for thread safety
+    fig = Figure(figsize=(15, 5))
     fig.patch.set_facecolor("black")
+    axes = fig.subplots(1, 3)
 
     # Axial (XY plane, Z fixed) - often needs rotation 90 deg
     # NIfTI data[x, y, z]. To display standard axial:
@@ -153,8 +153,10 @@ def render_3panel_view(
     axes[0].set_title(f"Axial (z={mid_z})", color="white")
     if mask_data is not None:
         m_slice = np.rot90(mask_data[:, :, mid_z])
+        # Binarize at 0.5 threshold for visible overlay (consistent with compute_dice)
+        m_slice_binary = (m_slice > 0.5).astype(float)
         axes[0].imshow(
-            np.ma.masked_where(m_slice == 0, m_slice),  # type: ignore[no-untyped-call]
+            np.ma.masked_where(m_slice_binary == 0, m_slice_binary),  # type: ignore[no-untyped-call]
             cmap="Reds",
             alpha=mask_alpha,
             vmin=0,
@@ -167,8 +169,10 @@ def render_3panel_view(
     axes[1].set_title(f"Coronal (y={mid_y})", color="white")
     if mask_data is not None:
         m_slice = np.rot90(mask_data[:, mid_y, :])
+        # Binarize at 0.5 threshold for visible overlay (consistent with compute_dice)
+        m_slice_binary = (m_slice > 0.5).astype(float)
         axes[1].imshow(
-            np.ma.masked_where(m_slice == 0, m_slice),  # type: ignore[no-untyped-call]
+            np.ma.masked_where(m_slice_binary == 0, m_slice_binary),  # type: ignore[no-untyped-call]
             cmap="Reds",
             alpha=mask_alpha,
             vmin=0,
@@ -181,8 +185,10 @@ def render_3panel_view(
     axes[2].set_title(f"Sagittal (x={mid_x})", color="white")
     if mask_data is not None:
         m_slice = np.rot90(mask_data[mid_x, :, :])
+        # Binarize at 0.5 threshold for visible overlay (consistent with compute_dice)
+        m_slice_binary = (m_slice > 0.5).astype(float)
         axes[2].imshow(
-            np.ma.masked_where(m_slice == 0, m_slice),  # type: ignore[no-untyped-call]
+            np.ma.masked_where(m_slice_binary == 0, m_slice_binary),  # type: ignore[no-untyped-call]
             cmap="Reds",
             alpha=mask_alpha,
             vmin=0,
@@ -192,7 +198,7 @@ def render_3panel_view(
     for ax in axes:
         ax.axis("off")
 
-    plt.tight_layout()
+    fig.tight_layout()
     return fig
 
 
@@ -248,8 +254,11 @@ def render_slice_comparison(
 
     # Plotting
     num_plots = 3 if gt_data is not None else 2
-    fig, axes = plt.subplots(1, num_plots, figsize=(5 * num_plots, 5))
+    # Create figure using OO API for thread safety
+    fig = Figure(figsize=(5 * num_plots, 5))
     fig.patch.set_facecolor("black")
+    axes = fig.subplots(1, num_plots)
+
     if num_plots == 2:
         axes = np.array(axes)  # handle single case if needed, but subplots(1,2) returns array
 
@@ -258,9 +267,14 @@ def render_slice_comparison(
     axes[0].set_title("DWI Input", color="white")
 
     # 2. Prediction
+    # Binarize prediction at threshold 0.5 for visible overlay (Issue #23)
+    # Model output may contain probability values (0.0-1.0) which render as
+    # nearly-white in the "Reds" colormap. Binarizing ensures consistent
+    # visualization matching how compute_dice() evaluates predictions.
+    p_slice_binary = (p_slice > 0.5).astype(float)
     axes[1].imshow(d_slice, cmap="gray")
     axes[1].imshow(
-        np.ma.masked_where(p_slice == 0, p_slice),  # type: ignore[no-untyped-call]
+        np.ma.masked_where(p_slice_binary == 0, p_slice_binary),  # type: ignore[no-untyped-call]
         cmap="Reds",
         alpha=0.5,
         vmin=0,
@@ -283,7 +297,7 @@ def render_slice_comparison(
     for ax in axes:
         ax.axis("off")
 
-    plt.tight_layout()
+    fig.tight_layout()
     return fig
 
 

tests/conftest.py

@@ -61,6 +61,47 @@ def synthetic_case_files(temp_dir: Path) -> CaseFiles:
     )
 
 
+@pytest.fixture
+def synthetic_probability_mask(temp_dir: Path) -> Path:
+    """
+    Create a synthetic probability mask (float values 0.0-1.0).
+
+    This simulates model output that may contain probability values
+    rather than binary 0/1 masks. Used to test visualization handling
+    of probability-valued segmentation masks.
+
+    The mask has values ONLY at slice 5 to ensure get_slice_at_max_lesion selects it:
+    - Outer region with low probability (0.3) - below 0.5 threshold
+    - Inner region with high probability (0.8) - above 0.5 threshold
+
+    See: docs/specs/23-slice-comparison-overlay-bug.md
+    """
+    mask_data = np.zeros((10, 10, 10), dtype=np.float32)
+
+    # Only populate slice 5 to ensure it's selected as max lesion slice
+    # Outer region: low confidence (below 0.5 threshold)
+    mask_data[2:8, 2:8, 5] = 0.3
+    # Inner region: high confidence (above 0.5 threshold) - this should be visible
+    mask_data[3:7, 3:7, 5] = 0.8
+
+    img = nib.Nifti1Image(mask_data, affine=np.eye(4))  # type: ignore
+    path = temp_dir / "probability_mask.nii.gz"
+    nib.save(img, path)  # type: ignore
+    return path
+
+
+@pytest.fixture
+def synthetic_binary_mask(temp_dir: Path) -> Path:
+    """Create a synthetic binary mask (0 or 1 values only)."""
+    mask_data = np.zeros((10, 10, 10), dtype=np.uint8)
+    mask_data[3:7, 3:7, 4:6] = 1  # Binary lesion region
+
+    img = nib.Nifti1Image(mask_data, affine=np.eye(4))  # type: ignore
+    path = temp_dir / "binary_mask.nii.gz"
+    nib.save(img, path)  # type: ignore
+    return path
+
+
 @pytest.fixture
 def synthetic_isles_dir(temp_dir: Path) -> Path:
     """

tests/ui/test_app.py

@@ -67,12 +67,18 @@ def test_run_segmentation_logic() -> None:
         ),
         patch("stroke_deepisles_demo.ui.app.create_niivue_html", return_value="<div></div>"),
         patch("stroke_deepisles_demo.ui.app.render_slice_comparison", return_value=MagicMock()),
+        patch("stroke_deepisles_demo.ui.app.render_3panel_view", return_value=MagicMock()),
+        patch("stroke_deepisles_demo.ui.app.compute_volume_ml", return_value=15.5),
     ):
-        html, _fig, metrics, _dl_path, status = run_segmentation(
-            "sub-001", fast_mode=True, show_ground_truth=True
+        html, _fig, _ortho, metrics, _dl_path, status, _new_results_dir = run_segmentation(
+            "sub-001",
+            fast_mode=True,
+            show_ground_truth=True,
+            previous_results_dir=None,  # No previous results in test
         )
 
         assert html == "<div></div>"
         assert metrics["case_id"] == "sub-001"
         assert metrics["dice_score"] == 0.85
+        assert "volume_ml" in metrics  # New metric added
         assert "Success" in status

tests/ui/test_viewer.py

@@ -152,6 +152,97 @@ class TestNiftiToGradioUrl:
         assert ";base64," not in url
 
 
+class TestRenderSliceComparisonProbabilityMask:
+    """Tests for render_slice_comparison with probability masks (Issue #23).
+
+    This test class verifies that probability-valued prediction masks
+    are rendered visibly. The bug occurs when:
+    - Ground truth is binary (0 or 1) → renders as visible green
+    - Prediction is probability (0.1-0.5) → renders as nearly-invisible white
+
+    See: docs/specs/23-slice-comparison-overlay-bug.md
+    """
+
+    def test_probability_mask_has_visible_overlay(
+        self,
+        synthetic_nifti_3d: Path,
+        synthetic_probability_mask: Path,
+    ) -> None:
+        """
+        Probability mask should produce visible overlay in rendering.
+
+        This test exposes the bug where low probability values (e.g., 0.3)
+        render as nearly-white in the "Reds" colormap and are invisible.
+        """
+        fig = render_slice_comparison(
+            synthetic_nifti_3d,
+            synthetic_probability_mask,  # Probability values 0.3, 0.7
+            ground_truth_path=None,
+        )
+
+        # Get the prediction axis (index 1)
+        ax = fig.axes[1]
+
+        # The axis should have at least 2 images (DWI background + overlay)
+        images = ax.get_images()
+        assert len(images) >= 2, "Prediction panel should have overlay image"
+
+        # The overlay should have non-zero alpha (visible)
+        overlay = images[1]
+        alpha = overlay.get_alpha()
+        assert alpha is None or alpha > 0  # None means default alpha (1.0)
+
+        plt.close(fig)
+
+    def test_binary_vs_probability_mask_comparison(
+        self,
+        synthetic_nifti_3d: Path,
+        synthetic_binary_mask: Path,
+        synthetic_probability_mask: Path,
+    ) -> None:
+        """
+        Both binary and probability masks should render visible overlays.
+
+        This is the core test for Issue #23. If the probability mask renders
+        invisibly while the binary mask renders visibly, the bug is confirmed.
+        """
+        # Render with binary mask (expected to work)
+        fig_binary = render_slice_comparison(
+            synthetic_nifti_3d,
+            synthetic_binary_mask,
+            ground_truth_path=None,
+        )
+
+        # Render with probability mask (may be invisible - the bug)
+        fig_prob = render_slice_comparison(
+            synthetic_nifti_3d,
+            synthetic_probability_mask,
+            ground_truth_path=None,
+        )
+
+        # Get overlay data from both
+        binary_overlay = fig_binary.axes[1].get_images()[1].get_array()
+        prob_overlay = fig_prob.axes[1].get_images()[1].get_array()
+
+        # Both should have non-masked (visible) pixels
+        binary_visible = (
+            not binary_overlay.mask.all()  # type: ignore[union-attr]
+            if hasattr(binary_overlay, "mask")
+            else True
+        )
+        prob_visible = (
+            not prob_overlay.mask.all()  # type: ignore[union-attr]
+            if hasattr(prob_overlay, "mask")
+            else True
+        )
+
+        assert binary_visible, "Binary mask overlay should have visible pixels"
+        assert prob_visible, "Probability mask overlay should have visible pixels"
+
+        plt.close(fig_binary)
+        plt.close(fig_prob)
+
+
 class TestCreateNiivueHtml:
     """Tests for create_niivue_html."""