NV-Segment-CT
Purpose
- Used for running NV-Segment-CT VISTA3D on CT NIfTI volumes and recording label-map evidence. Not for clinical interpretation.
- Use the wrapper exactly as documented; do not replace the upstream entrypoint with a handwritten implementation.
- Manifest I/O: inputs are ; outputs are and .
Instructions
- Read before changing arguments, side effects, or validation gates.
- Run through the documented command below; keep outputs under a caller-provided run directory.
- If a host agent exposes , use
run_script("scripts/run_vista3d.py", args=[...])
- Check the emitted JSON and paired verifier guidance before treating the run as evidence.
Available Scripts
| Script | Purpose | Arguments |
|---|
| Primary entrypoint declared by skill_manifest.yaml. | PATH_TO_CT.nii.gz [--output-dir OUT_DIR] [--label-prompts IDS]
|
Prerequisites
- Runtime requirements: GPU/CUDA when declared by the manifest; Python packages listed in
runtime.side_effects.pip_packages
- Side effects: writes the downloaded bundle under
skills/nv-segment-ct/bundle/
https://msd-for-monai.s3-us-west-2.amazonaws.com
- Run commands from the repository root unless an existing section below says otherwise.
Limitations
- This is a thin wrapper. Inference, preprocessing, and postprocessing are delegated entirely to the official
hugging_face_pipeline.HuggingFacePipelineHelper
- transformers must be a 4.x release; the HF model code uses pre-5.x idioms (e.g. ).
- Device auto-detected (cuda if available, else cpu); flag overrides.
- Output may be schema-valid but semantically empty (e.g. label prompts that do not match the input anatomy). Sanity gates assert at least one foreground voxel per requested anatomy.
- Not for clinical deployment, clinical interpretation, autonomous diagnosis, regulatory submission.
Troubleshooting
| Error | Cause | Fix |
|---|
| Missing dependency or import error | Runtime package drift from . | Install the packages declared in the manifest or use the documented setup command. |
| Empty or schema-invalid output | Wrong input path, unsupported modality, or upstream failure. | Re-run with a known fixture and inspect the wrapper JSON plus stderr. |
| Validation gate failure | Output violated a declared engineering invariant. | Keep the failed evidence pack and use the gate message to repair inputs or wrapper code. |
Wraps the upstream
helper. The wrapper does not
reimplement VISTA3D inference.
Exact Runnable Surface
For CT segmentation user runs, use this repo-root wrapper path exactly:
bash
python skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz --label-prompts "1,3,5,14" --output-dir OUT_DIR
Do not invent
,
,
, or anatomy-name-only flags. For spleen, liver, right kidney, and left kidney, the required VISTA3D label IDs are exactly
.
Preconditions
The skill assumes a Python 3.12 environment with
no pre-installed
runtime deps — its documented command installs everything it needs.
Pinned dep list is at
.
Two one-time downloads (the documented command does the first one; the
fixture fetch is a separate step you run when bootstrapping):
bash
# Spleen example fixture from Decathlon MSD09 (~1.5 GB tar, ~11 MB
# fixture extracted into skills/nv-segment-ct/fixtures/spleen_03.nii.gz):
python skills/nv-segment-ct/fixtures/fetch_spleen_fixture.py
Both downloads (the bundle below, and the fixture) are gitignored
(Medical AI Skills policy: no medical data or model weights in git). The fetch
script is idempotent and caches the tar under
.workbench_data/datasets/
so re-runs are no-ops.
Runtime needs an NVIDIA GPU with CUDA. CPU fallback is supported but slow.
Usage
From Medical AI Skills repo root, run all steps in a single command so the
skill is self-bootstrapping against a fresh Python 3.12 venv:
bash
pip install -r skills/nv-segment-ct/requirements.txt && \
huggingface-cli download nvidia/NV-Segment-CT \
--local-dir skills/nv-segment-ct/bundle/ && \
python skills/nv-segment-ct/scripts/run_vista3d.py PATH_TO_CT.nii.gz \
--label-prompts "1,3,5,14" \
--output-dir vista3d_outputs
When the user names anatomies, translate them to VISTA3D class IDs before
running. For the common abdominal CT request:
| Anatomy | VISTA3D class ID |
|---|
| liver | 1 |
| spleen | 3 |
| right kidney | 5 |
| left kidney | 14 |
For "segment the spleen, liver, right kidney, and left kidney", the correct
value is exactly
. Do not substitute kidney
IDs from another label dictionary; the wrapper validates the requested label
set and will mark the run invalid if the emitted mask contains labels outside
the requested set.
The
step is load-bearing: do not assume monai/torch/etc.
are already in the active environment. The
step is also part of the contract — it pulls the ~832 MB model bundle
into
skills/nv-segment-ct/bundle/
(cached after first run; subsequent
calls are no-ops).
are VISTA3D class IDs. The evidence output records input
geometry, output mask path, observed label IDs, unexpected labels,
per-class voxel counts, per-class physical volumes computed from the output
mask header spacing, runtime, model identity, and fixed code-derived artifact
checks such as mask shape, affine match, label set, foreground count, and
class-volume bounds.
Pass
to record a reference label-map path under
. The skill does not compute Dice; that is the
paired verifier's job.
Anatomy plausibility (per-class volume bounds, fragmentation, bilateral
symmetry, liver larger than spleen) and optional per-class Dice/IoU against
the recorded ground truth are checked by
verifiers/ct_segmentation_quality_v1
.
Not for clinical interpretation, production deployment, or non-CT modalities.