i4h Catheter Navigation - Setup

Purpose

Verify host and GPU requirements, confirm the ./i4h CLI sees the workflow, and run CPU smoke tests. Use when asked to set up catheter navigation or when hitting missing imports, GPU, or slangpy errors.

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:

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

• Catheter navigation registers via workflows/catheter_navigation/metadata.json and runs through ./i4h run catheter_navigation <mode>.
• Runtime is package-first: render_drr uses installed fluorosim (python -m fluorosim.examples.render_drr), while interactive_viewport is launched from the local workflow script path in metadata.json.
• Docker image: workflows/catheter_navigation/docker/Dockerfile (drop --local on ./i4h run to use it).
• GPU modes need slangpy, Warp, and CUDA; CPU smoke tests do not.

Preflight

command -v python3
command -v git
nvidia-smi
df -h .

Required: Linux x86_64 (Ubuntu 22.04/24.04 tested), NVIDIA GPU (CC >= 7.0), driver compatible with CUDA 12.8, >= 16 GB RAM, >= 20 GB disk.

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

Step 1 - resolve repo and export paths

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/catheter_navigation" ] || REPO_ROOT="$HOME/i4h-workflows"
WF_ROOT="${REPO_ROOT}/workflows/catheter_navigation"
SIM_ROOT="${WF_ROOT}/scripts/simulation"
export PYTHONPATH="${SIM_ROOT}:${PYTHONPATH:-}"
RUN_DIR="${WF_ROOT}/runs/setup_$(date +%Y%m%d_%H%M%S)"
mkdir -p "${RUN_DIR}/logs"
ln -sfn "${RUN_DIR}" "${WF_ROOT}/runs/.latest"

Step 2 - verify CLI registration

"${REPO_ROOT}/i4h" modes catheter_navigation 2>&1 | tee "${RUN_DIR}/logs/modes.log"

Step 3 - CPU smoke tests (no GPU)

python3 -m unittest workflows/catheter_navigation/tests/test_fluorosim_smoke.py \
  2>&1 | tee "${RUN_DIR}/logs/smoke.log"

Expected: Ran 7 tests ... OK. Parser error lines in stderr from negative test cases are expected.

Step 4 - optional GPU sanity (synthetic DRR)

Skip if no GPU or slangpy not installed.

"${REPO_ROOT}/i4h" run catheter_navigation render_drr --local \
  --run-args="--output ${RUN_DIR}/drr.png" \
  2>&1 | tee "${RUN_DIR}/logs/render_drr.log"

Verify

test -f "${RUN_DIR}/logs/smoke.log"
grep -q "OK" "${RUN_DIR}/logs/smoke.log"
python3 -c "import fluorosim; print('fluorosim', fluorosim.__file__)"

Prerequisites

• Repo checkout with workflows/catheter_navigation/ present.
• Python 3 with numpy; full GPU stack (slangpy, torch CUDA, warp) for render/viewport modes.

Limitations

• No dedicated setup.sh yet - this skill verifies and documents host requirements; use Docker when host deps are incomplete.
• Step 4 requires a GPU; Step 3 alone is sufficient for CI-style verification.

Troubleshooting

• Error: fluorosim import fails - Cause: PYTHONPATH not set. Fix: re-run Step 1; confirm SIM_ROOT exists.
• Error: ./i4h not found - Cause: not at repo root. Fix: cd "$REPO_ROOT" where ./i4h lives.
• Error: render_drr fails with slang/GPU - Cause: missing CUDA or slangpy. Fix: use Docker (./i4h run catheter_navigation render_drr without --local) or install deps per README.

Final Response

Report setup status, smoke-test result, optional DRR output path, and recommend the next skill ([[i4h-catheter-navigation-digital-twin]] for patient data, [[i4h-catheter-navigation-viewport]] for interactive demo).