I4h Catheter Navigation

i4h Catheter Navigation Workflow

Purpose

Orient on the endovascular catheter navigation workflow before touching a specific stage: which CLI modes exist, how fluorosim / physics / digital-twin pieces fit together, and which per-stage skill to invoke next. This skill routes - it runs no pipeline stage itself.

Base Code

These steps drive the i4h-workflows base code (the workflows/catheter_navigation/ tree). To reuse an existing checkout, set I4H_WORKFLOWS to its path (no clone happens). Otherwise this resolves the current repo, or clones to ~/i4h-workflows - pick that default without prompting. Run every command below from the resolved root:

# Resolve the i4h-workflows base code (provides workflows/catheter_navigation/).
ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"
if [ ! -d "$ROOT/workflows/catheter_navigation" ]; then
  ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"
  [ -d "$ROOT/workflows/catheter_navigation" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"
fi
export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

Basics

• Mode registry (source of truth): workflows/catheter_navigation/metadata.json - lists ./i4h modes and their runtime commands.
• Human docs: workflows/catheter_navigation/README.md - data download, digital-twin build, viewport controls, troubleshooting.
• Each pipeline stage has its own skill. Compose them or use [[i4h-catheter-navigation-e2e]] for a full smoke run.
• No CT data is shipped; users bring their own NIfTI/DICOM (e.g. TotalSegmentator subset).

Supported Modes

Fallback when ./i4h modes catheter_navigation fails (setup incomplete):

| Mode | Purpose |

|---|---|

| preprocess_ct | CT -> attenuation volume (mu_volume.npy) + optional HU cache |

| segment_vessels | Arterial tree mask + centerline (vasculature digital twin) |

| render_drr | Single DRR frame (synthetic phantom if no cache) |

| interactive_viewport | Live fluoroscopy viewport with XPBD catheter physics |

Subprojects

| Directory | Purpose |

|---|---|

| workflows/catheter_navigation/scripts/simulation/fluorosim/examples/interactive_catheter_slang_viewport.py | Interactive viewport glue script (invoked by interactive_viewport mode) |

| workflows/catheter_navigation/scripts/simulation/fluorosim/rendering/ | Local DRR rendering helpers used by viewport fallback path |

| workflows/catheter_navigation/metadata.json | ./i4h mode registry and command wiring |

| Installed packages | fluorosim, vasculature_digital_twin, catheter_vasculature_solver provide renderer + digital twin + solver runtime |

| workflows/catheter_navigation/tests/ | CPU smoke tests (no GPU required) |

Run

Run the step below before answering. Each step is a separate bash call; variables persist in the local agent's tmux session.

Step 1 - list supported modes

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/catheter_navigation" ] || REPO_ROOT="$HOME/i4h-workflows"
"${REPO_ROOT}/i4h" modes catheter_navigation

If the command fails, use the Supported Modes fallback table above.

Skill Index

| Skill | Purpose |

|---|---|

| i4h-catheter-navigation-setup | Host/GPU preflight, PYTHONPATH, smoke-test verify |

| i4h-catheter-navigation-digital-twin | Download CT data, preprocess, segment vessels |

| i4h-catheter-navigation-render-drr | Render a single DRR frame |

| i4h-catheter-navigation-viewport | Launch interactive fluoroscopy + catheter sim |

| i4h-catheter-navigation-smoke | Run CPU unittest smoke suite |

| i4h-catheter-navigation-e2e | End-to-end smoke (setup -> digital twin -> render -> tests) |

Prerequisites

• NVIDIA GPU with CUDA >= 12.8 and Vulkan-capable driver for GPU modes (render, viewport).
• For any hands-on stage, run [[i4h-catheter-navigation-setup]] first.
• For patient-specific runs, run [[i4h-catheter-navigation-digital-twin]] before viewport or cache-based DRR.

Limitations

• Overview/routing only - each stage has its own skill; this one performs no preprocessing, rendering, or simulation.
• RL/IL training integration with Isaac Lab is not yet a first-class skill stage in v0.7; use the workflow README and fluorosim API for custom data generation.

Troubleshooting

• Error: mode not found - Cause: typo or ./i4h not run from repo root. Fix: cd to repo root and re-run Step 1; inspect workflows/catheter_navigation/metadata.json.
• Error: import errors for fluorosim / vasculature_digital_twin / catheter_vasculature_solver - Cause: dependencies not installed in active env. Fix: run [[i4h-catheter-navigation-setup]] and install README requirements.

Final Response

The response is incomplete unless it includes all three parts below, each separated by a blank line.

• Orientation - one short paragraph: fluorosim stack, digital twin, ./i4h modes.

• Supported modes - heading plus markdown table from Step 1 or the Supported Modes fallback table.

• Available skills - heading plus the full Skill Index table copied into the response.

Then recommend [[i4h-catheter-navigation-setup]] if setup is not done, and name one next stage skill matched to the user's goal.