nv-segment-ct

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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
```
ct_volume
```
; outputs are
```
label_map
```
and
```
result_json
```
.

用于在CT NIfTI影像上运行NV-Segment-CT VISTA3D并记录标签映射证据。不用于临床解读。
严格按照文档说明使用该包装器；请勿用手写实现替换上游入口点。
清单输入输出：输入为
```
ct_volume
```
；输出为
```
label_map
```
和
```
result_json
```
。

Instructions

操作说明

Read
```
skill_manifest.yaml
```
before changing arguments, side effects, or validation gates.
Run
```
scripts/run_vista3d.py
```
through the documented command below; keep outputs under a caller-provided run directory.
If a host agent exposes
```
run_script
```
, use
```
run_script("scripts/run_vista3d.py", args=[...])
```
; otherwise run the Bash/Python command shown below.
Check the emitted JSON and paired verifier guidance before treating the run as evidence.

在修改参数、副作用或验证规则前，请先阅读
```
skill_manifest.yaml
```
。
通过以下文档记录的命令运行
```
scripts/run_vista3d.py
```
；将输出存储在调用方指定的运行目录下。
如果宿主Agent暴露
```
run_script
```
接口，请使用
```
run_script("scripts/run_vista3d.py", args=[...])
```
；否则运行下方所示的Bash/Python命令。
在将运行结果作为证据前，请检查生成的JSON文件及配套验证器指南。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/run_vista3d.py`	Primary entrypoint declared by skill_manifest.yaml.	`PATH_TO_CT.nii.gz [--output-dir OUT_DIR] [--label-prompts IDS]`

脚本	用途	参数
`scripts/run_vista3d.py`	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/
```
, may cache model assets under
```
~/.cache/huggingface/
```
, and may contact
```
https://huggingface.co
```
during first setup; the optional spleen fixture fetcher downloads MSD09 from
```
https://msd-for-monai.s3-us-west-2.amazonaws.com
```
.
Run commands from the repository root unless an existing section below says otherwise.

运行时要求：若清单中声明，则需GPU/CUDA；需安装
```
runtime.side_effects.pip_packages
```
中列出的Python包。
副作用：会将下载的bundle写入
```
skills/nv-segment-ct/bundle/
```
目录，可能会在
```
~/.cache/huggingface/
```
下缓存模型资产，首次设置时可能会连接
```
https://huggingface.co
```
；可选的脾脏样本获取器会从
```
https://msd-for-monai.s3-us-west-2.amazonaws.com
```
下载MSD09数据集。
除非下方已有说明，否则请从仓库根目录运行命令。

Limitations

局限性

This is a thin wrapper. Inference, preprocessing, and postprocessing are delegated entirely to the official
```
hugging_face_pipeline.HuggingFacePipelineHelper
```
in bundle/. Do not modify code under bundle/.
transformers must be a 4.x release; the HF model code uses pre-5.x idioms (e.g.
```
_tied_weights_keys
```
).
Device auto-detected (cuda if available, else cpu);
```
--device
```
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.

这是一个轻量包装器。推理、预处理和后处理完全委托给bundle/目录下官方的
```
hugging_face_pipeline.HuggingFacePipelineHelper
```
。请勿修改bundle/目录下的代码。
transformers必须为4.x版本；HF模型代码使用5.x之前的语法（例如
```
_tied_weights_keys
```
）。
设备会自动检测（若可用则用cuda，否则用cpu）；
```
--device
```
标志可覆盖自动检测结果。
输出可能符合 schema 规范但语义为空（例如标签提示与输入解剖结构不匹配）。完整性检查会确保每个请求的解剖结构至少有一个前景体素。
不可用于临床部署、临床解读、自主诊断或合规提交。

Troubleshooting

故障排查

Error	Cause	Fix
Missing dependency or import error	Runtime package drift from `skill_manifest.yaml` .	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

nvidia/NV-Segment-CT

helper. The wrapper does not reimplement VISTA3D inference.

错误	原因	修复方案
依赖缺失或导入错误	运行时包与 `skill_manifest.yaml` 不一致。	安装清单中声明的包，或使用文档记录的设置命令。
输出为空或不符合schema规范	输入路径错误、模态不支持或上游运行失败。	使用已知样本重新运行，并检查包装器JSON文件及标准错误输出。
验证规则失败	输出违反了已声明的工程约束。	保留失败的证据包，并根据规则提示修复输入或包装器代码。

该包装器基于上游

nvidia/NV-Segment-CT

助手实现。包装器未重新实现VISTA3D推理逻辑。

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

infer.py

Medical AI Skills run

python -m nv_segment_ct

, or anatomy-name-only flags. For spleen, liver, right kidney, and left kidney, the required VISTA3D label IDs are exactly

1,3,5,14

对于CT分割用户运行，请严格使用以下仓库根目录下的包装器路径：

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

请勿自行编写

infer.py

、

Medical AI Skills run

、

python -m nv_segment_ct

或仅包含解剖名称的标志。对于脾脏、肝脏、右肾和左肾，所需的VISTA3D标签ID必须为

1,3,5,14

。

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

requirements.txt

Two one-time downloads (the documented command does the first one; the fixture fetch is a separate step you run when bootstrapping):

bash

undefined

该Skill假设Python 3.12环境中未预装任何运行时依赖 —— 其文档记录的命令会安装所有所需依赖。固定的依赖列表位于

requirements.txt

。

需要进行两次一次性下载（文档记录的命令会完成第一次下载；样本获取是引导时需单独运行的步骤）：

bash

undefined

Spleen example fixture from Decathlon MSD09 (~1.5 GB tar, ~11 MB

来自Decathlon MSD09的脾脏示例样本（约1.5GB压缩包，解压后约11MB样本存储在skills/nv-segment-ct/fixtures/spleen_03.nii.gz）：

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.

python skills/nv-segment-ct/fixtures/fetch_spleen_fixture.py


两次下载（下方的bundle和样本）均已加入git忽略（Medical AI Skills政策：git中不存储医疗数据或模型权重）。获取脚本具有幂等性，会将压缩包缓存到`.workbench_data/datasets/`目录下，因此重复运行不会产生任何操作。

运行时需要带CUDA的NVIDIA GPU。支持CPU fallback但速度较慢。

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

--label-prompts

value is exactly

"1,3,5,14"

. 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

pip install

step is load-bearing: do not assume monai/torch/etc. are already in the active environment. The

huggingface-cli download

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

label-prompts

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

--ground-truth PATH

to record a reference label-map path under

input.ground_truth_path

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

从Medical AI Skills仓库根目录，通过单个命令运行所有步骤，以便该Skill在全新的Python 3.12虚拟环境中完成自引导：

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

当用户指定解剖结构时，请先将其转换为VISTA3D类别ID再运行。对于常见的腹部CT请求：

解剖结构	VISTA3D类别ID
肝脏	1
脾脏	3
右肾	5
左肾	14

若请求为“分割脾脏、肝脏、右肾和左肾”，则

--label-prompts

参数的值必须为

"1,3,5,14"

。请勿替换为其他标签字典中的肾脏ID；包装器会验证请求的标签集，如果生成的掩码包含请求集之外的标签，会将该次运行标记为无效。

pip install

步骤至关重要：请勿假设monai/torch等已存在于当前环境中。

huggingface-cli download

步骤也是协议的一部分 —— 它会将约832MB的模型bundle下载到

skills/nv-segment-ct/bundle/

目录下（首次运行后会缓存；后续调用不会产生任何操作）。

label-prompts

为VISTA3D类别ID。证据输出会记录输入几何信息、输出掩码路径、观测到的标签ID、意外标签、每类体素数量、根据输出掩码头间距计算的每类物理体积、运行时间、模型标识，以及基于固定代码的人工产物检查（如掩码形状、仿射匹配、标签集、前景体素数量、类别体积范围）。

传入

--ground-truth PATH

参数可在

input.ground_truth_path

下记录参考标签映射路径。该Skill不计算Dice系数；此项工作由配套验证器完成。

解剖结构合理性（每类体积范围、碎片化程度、双侧对称性、肝脏体积大于脾脏）以及可选的与记录的真实标签的每类Dice/IoU检查，由

verifiers/ct_segmentation_quality_v1

完成。

不可用于临床解读、生产部署或非CT模态。