/i4h-catheter-navigation-setup

name: i4h-catheter-navigation-setup
version: "0.7.0"
description: Verify host/GPU requirements and PYTHONPATH for the catheter navigation workflow. Use when asked to set up, install, or bootstrap catheter_navigation, or when hitting import/GPU/slangpy errors.
license: Apache-2.0
metadata:
  author: "Isaac for Healthcare Team <isaac-for-healthcare-support@nvidia.com>"
  tags:
    - isaac-for-healthcare
    - i4h
    - catheter-navigation
    - setup
    - installation

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