i4h-catheter-navigation

name	i4h-catheter-navigation
version	0.7.0
description	Overview of `workflows/catheter_navigation/` (fluorosim DRR, XPBD physics, vasculature digital twin). Use when the user asks what the catheter navigation workflow is, what's supported, or where to start.
license	Apache-2.0
metadata	{"author":"Isaac for Healthcare Team <[e-mail]>","tags":["isaac-for-healthcare","i4h","catheter-navigation","fluoroscopy","overview"]}

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.

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

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

3. 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.