Vessel3d Frangi Bugfix

vessel3d-frangi-bugfix - Research Notes

Experiment Overview

Context

The vessel3d module was added Feb 16, 2026 and attempted on one project with 5 SLURM runs — all failed due to different issues. Investigation revealed three distinct failure modes and one critical algorithmic bug.

SLURM Run Failure Analysis

Run 2 proved the Cardano fix works. The remaining issues were the Ra formula bug and small-GPU safety.

Verified Fixes

1. Frangi Ra Formula (Critical)

The Ra ratio discriminates tubes from plates. With eigenvalues sorted |λ₁| ≤ |λ₂| ≤ |λ₃|:

Wrong (vessel3d.py:552):

Ra = abs_l1 / (abs_l2 + eps)   # |λ₁|/|λ₂| — near 0 for tubes!

Correct (Frangi 1998, eq. 11; scikit-image reference):

Ra = abs_l2 / (abs_l3 + eps)   # |λ₂|/|λ₃| — near 1 for tubes

Impact: With the bug, the (1 - exp(-Ra²/2α²)) term evaluated to ~0 for tubes (since Ra ≈ 0), killing the vesselness response. The pipeline still partially worked because real data has nonzero λ₁ and Otsu threshold adapts, but small/faint vessels were missed.

Verification: Synthetic tube test — Ra at tube center = 0.91 (correct) vs ~0.02 (buggy). Plate Ra = 0.05 (correctly low in both versions).

2. scikit-image 0.26 Deprecations

3. GPU VRAM Guard

Added to _hessian_eigenvalues_3d():

estimated_vram = volume.nbytes * 15  # Peak: 6 Hessian + input + 8 working arrays
free_vram = cp.cuda.Device(device_id).mem_info[0]
if estimated_vram > free_vram:
    logger.warning(f"GPU VRAM insufficient, falling back to CPU")
    use_gpu = False

SLURM job script also queries nvidia-smi and forces device='cpu' if VRAM < 40 GB.

Failed Attempts (Critical)

Verified: Sensitivity Presets and Multi-Channel (Feb 22, 2026)

4. Preset Override Pattern

Preset-overridable params (sigmas, alpha, beta, min_size, denoise_sigma) default to None in segment_vessels_3d(). Resolution chain: explicit value > preset > hardcoded default.

Why None defaults: The original design used hardcoded defaults (alpha=0.5) and compared against them to detect "caller used default." This failed when SLURM scripts passed values explicitly (e.g., alpha=VESSEL_ALPHA where VESSEL_ALPHA=0.5). The function couldn't distinguish "caller passed 0.5" from "caller didn't specify."

SLURM integration: Build a seg_kwargs dict, only including params whose env vars exist (if 'VESSEL_ALPHA' in os.environ). Unset vars → param stays None → preset fills it.

5. Marker Discovery

discover_vessel_markers(channel_names) finds vessel markers ranked by priority:

Excludes: DAPI, Blank, Empty, Autofluorescence, generic "Actin" (too ambiguous).

6. Multi-Channel Combination

segment_vessels_multichannel({"CD31": vol1, "SMA": vol2}, ...): Runs Frangi independently per channel (avoids inter-cycle misalignment), then combines binary masks via combine_vessel_masks() (union or intersection). Skeletonizes and analyzes the combined result. Stores individual masks in result.per_channel_masks.

CC3-C Rerun Results (high_sensitivity)

Final Parameters

Presets (VESSEL_PRESETS):

VRAM guard: 15x volume bytes minimum for GPU path.

Thin-slab note: Datasets are 10 z-planes (15 um depth). Topology features (tortuosity, branching angle) are unreliable. Cross-section radii and cleaner masks are the main 3D value.

Test assertions that verify the fix:

• Tube center Ra > 0.5 (typically ~0.9)
• Plate center Ra < 0.5 (typically ~0.05)
• Ra term for tube > Ra term for plate at same center voxel
• Eigenvalues sorted: |l1| <= |l2| <= |l3| everywhere
• alpha=0.1 mask >= alpha=0.9 mask (sensitivity forwarding works)
• Preset fills None params, explicit values override preset

Failed Attempts (Critical)

Key Insights

• Always verify Frangi formula against the original paper (Frangi et al., 1998, MICCAI). The Ra/Rb ratios are easy to mix up because different implementations use different eigenvalue orderings
• scikit-image 0.26 is aggressive about deprecations — binary_closing, binary_opening, binary_dilation, binary_erosion all deprecated in favor of generic closing, opening, dilation, erosion
• GPU VRAM estimation: 15x volume size is a good heuristic for the Cardano eigenvalue path (6 Hessian arrays + input copy + 8 working arrays during computation and sorting)
• Small synthetic volume tests: Boundary effects dominate on 32³ volumes. Test eigenvalue ratios at known structure centers rather than aggregate statistics
• Preset override pattern: Use None defaults for any param a preset should control. The if 'ENV_VAR' in os.environ pattern in SLURM scripts cleanly separates "explicitly set" from "use default"
• Multi-channel vessel segmentation: Run Frangi independently per channel, combine binary masks. Don't combine raw volumes — inter-cycle misalignment corrupts Hessian analysis
• Thin-slab data: ~10 z-planes gives value for cross-section radii and cleaner 3D masks, but topology metrics (tortuosity, branching angle) are not meaningful

References

• Frangi, A.F. et al. (1998). "Multiscale vessel enhancement filtering." MICCAI, LNCS 1496, pp. 130-137.
• scikit-image 0.26 changelog: https://scikit-image.org/docs/stable/release_notes/release_0.26.html
• src/kintsugi/vessel3d.py — Presets, marker discovery, multichannel, preset override pattern
• tests/test_vessel3d.py — 34 tests validating all fixes and new features