Back to Details

nv-segment-ctmr

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

NV-Segment-CTMR

NV-Segment-CTMR

Purpose

用途

  • Used for running NV-Segment-CTMR on CT or MRI 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_or_mr_volume
    ; outputs are 
    label_map
    and 
    result_json
    .
  • 用于在CT或MRI NIfTI影像上运行NV-Segment-CTMR并记录标签映射证据。不用于临床解读。
  • 严格按照文档说明使用该封装程序；请勿用手写实现替换上游入口点。
  • 清单输入输出：输入为
    ct_or_mr_volume
    ；输出为
    label_map
    和
    result_json
    。

Instructions

使用说明

  • Read 
    skill_manifest.yaml
    before changing arguments, side effects, or validation gates.
  • Run 
    scripts/run_ctmr.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_ctmr.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_ctmr.py
    ；将输出存储在调用者指定的运行目录下。
  • 如果宿主Agent暴露
    run_script
    接口，请使用
    run_script("scripts/run_ctmr.py", args=[...])
    ；否则运行下方所示的Bash/Python命令。
  • 在将运行结果视为有效证据之前，请检查生成的JSON文件及配套的验证器指南。

Available Scripts

可用脚本

ScriptPurposeArguments
scripts/run_ctmr.py
Primary entrypoint declared by skill_manifest.yaml.
PATH_TO_IMAGE.nii.gz --output-dir OUT_DIR --modality CT_BODY [--label-prompts IDS]
脚本用途参数
scripts/run_ctmr.py
skill_manifest.yaml
中声明的主入口点。
PATH_TO_IMAGE.nii.gz --output-dir OUT_DIR --modality CT_BODY [--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 segmentation outputs under the caller's 
    --output-dir
    , may cache model assets under 
    ~/.cache/huggingface/
    , and may contact 
    https://github.com
    or 
    https://huggingface.co
    during setup.
  • Run commands from the repository root unless an existing section below says otherwise.
  • 运行时要求：当清单中声明时，需GPU/CUDA；需安装
    runtime.side_effects.pip_packages
    中列出的Python包。
  • 副作用：会在调用者指定的
    --output-dir
    下写入分割输出，可能会在
    ~/.cache/huggingface/
    下缓存模型资产，且在设置过程中可能会连接
    https://github.com
    或
    https://huggingface.co
    。
  • 除非下方现有章节另有说明，否则请从仓库根目录运行命令。

Limitations

局限性

  • This is a thin wrapper. Inference, preprocessing, and postprocessing are delegated entirely to the upstream MONAI bundle under $NV_SEGMENT_CTMR_ROOT or the repo-local fallback at .workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR.
  • The default wrapper path runs automatic "segment everything" inference for CT_BODY, MRI_BODY, or MRI_BRAIN. MRI_BRAIN inputs must already follow the upstream brain preprocessing requirements.
  • Label names are loaded from upstream configs when available. If a label dictionary is absent, the wrapper still records label IDs and marks only negative IDs as invalid.
  • No clinical, diagnostic, regulatory, or treatment-planning claims.
  • Not for clinical deployment, clinical interpretation, autonomous diagnosis, regulatory submission.
  • 这是一个轻量封装程序。推理、预处理和后处理完全委托给位于$NV_SEGMENT_CTMR_ROOT的上游MONAI bundle，或仓库本地的备用路径.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR。
  • 默认封装路径会针对CT_BODY、MRI_BODY或MRI_BRAIN自动执行“全分割”推理。MRI_BRAIN输入必须已符合上游脑部预处理要求。
  • 标签名称会在可用时从上游配置加载。如果缺少标签字典，封装程序仍会记录标签ID，并仅将负ID标记为无效。
  • 不提供临床、诊断、监管或治疗规划相关声明。
  • 不用于临床部署、临床解读、自主诊断或监管申报。

Troubleshooting

故障排除

ErrorCauseFix
Missing dependency or import errorRuntime package drift from 
skill_manifest.yaml
.		Install the packages declared in the manifest or use the documented setup command.
Empty or schema-invalid outputWrong input path, unsupported modality, or upstream failure.Re-run with a known fixture and inspect the wrapper JSON plus stderr.
Validation gate failureOutput 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-Medtech/NV-Segment-CTMR
 CT/MRI segmentation bundle. The wrapper does not reimplement VISTA3D inference. It shells out to the documented 
python -m monai.bundle run
entry point, then inspects the produced NIfTI label map.
错误原因修复方法
依赖缺失或导入错误运行时包与
skill_manifest.yaml
存在差异。		安装清单中声明的包，或使用文档记录的设置命令。
输出为空或不符合模式规范输入路径错误、模态不支持或上游执行失败。使用已知的测试用例重新运行，并检查封装程序的JSON输出及标准错误信息。
验证门执行失败输出违反了已声明的工程约束。保留失败的证据包，并使用验证门提示信息修复输入或封装程序代码。
该程序封装了上游的
NVIDIA-Medtech/NV-Segment-CTMR
 CT/MRI分割bundle。封装程序未重新实现VISTA3D推理，而是调用文档记录的
python -m monai.bundle run
入口点，然后检查生成的NIfTI标签映射。

Exact Runnable Surface

可运行命令规范

For CT body segmentation user runs and benchmark answers, use this fresh-environment-safe repo-root command shape exactly:
bash
export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz --modality CT_BODY --output-dir OUT_DIR
Do not invent 
python -m nv_segment_ctmr
, 
infer.py
, or 
Medical AI Skills run
commands. 
PATH_TO_IMAGE.nii.gz
must be the user's supplied input path. For benchmark/user run answers, the bash block is invalid if it includes 
mkdir -p .workbench_data/upstreams
, 
git clone
, 
mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"
, 
hf download
, 
mv "$NV_SEGMENT_CTMR_ROOT/...
, or any other command that creates, downloads into, or moves files inside the shared upstream checkout.
对于CT体部分割的用户运行和基准测试，需严格使用以下适用于全新环境的仓库根目录命令格式：
bash
export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz --modality CT_BODY --output-dir OUT_DIR
请勿自行创建
python -m nv_segment_ctmr
、
infer.py
或
Medical AI Skills run
等命令。
PATH_TO_IMAGE.nii.gz
必须是用户提供的输入路径。对于基准测试/用户运行结果，如果bash命令块包含
mkdir -p .workbench_data/upstreams
、
git clone
、
mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"
、
hf download
、
mv "$NV_SEGMENT_CTMR_ROOT/..."
或任何其他在共享上游检出目录内创建、下载或移动文件的命令，则该命令块无效。

Preconditions

初始化设置

One-time maintainer setup only; do not include these commands in user answers or benchmark commands. The benchmark environment already provides the repo-local upstream cache and model files.
Clone and install the upstream bundle once. In this Medical AI Skills checkout, prefer the repo-local cache path when it exists:
bash
mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Segment-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git \
    .workbench_data/upstreams/NV-Segment-CTMR
export NV_SEGMENT_CTMR_ROOT=.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python -c "import monai, nibabel, numpy"

mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  hf download nvidia/NV-Segment-CTMR --local-dir "$NV_SEGMENT_CTMR_ROOT/models/"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  mv "$NV_SEGMENT_CTMR_ROOT/models/vista3d_pretrained_model/model.pt" \
    "$NV_SEGMENT_CTMR_ROOT/models/model.pt"
The wrapper also searches 
.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR
if 
NV_SEGMENT_CTMR_ROOT
is unset or points at a stale clone.
For agent-generated user run commands, use the command in Usage. Do not copy the one-time Preconditions block into the answer: do not create or write under 
$NV_SEGMENT_CTMR_ROOT
, do not run 
hf download
, and do not move files in the shared upstream checkout during a benchmark or user run. Do not prepend 
pip install -r "$NV_SEGMENT_CTMR_ROOT/requirements.txt"
in a Python 3.12 environment; the upstream requirements pin NumPy 1.24.4, which does not build cleanly there. In a fresh Python environment, install the minimal compatible runtime shown above (
monai>=1.5,<1.6
, 
numpy<2
, 
nibabel
, 
scipy
, 
typer
, 
PyYAML
, 
fire
, 
huggingface_hub
, 
pytorch-ignite
, 
einops
) before the wrapper. Cached models do not imply cached Python packages.
Runtime needs an NVIDIA GPU with CUDA. The upstream bundle may import on CPU-only hosts, but this skill is declared as CUDA-required because the published workflow is a 3D CT/MRI foundation model inference path.
仅需一次性维护者设置；请勿将这些命令包含在用户答案或基准测试命令中。基准测试环境已提供仓库本地的上游缓存和模型文件。
克隆并安装上游bundle一次。在该Medical AI Skills检出目录中，当仓库本地缓存路径存在时，优先使用该路径：
bash
mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Segment-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Segment-CTMR.git \
    .workbench_data/upstreams/NV-Segment-CTMR
export NV_SEGMENT_CTMR_ROOT=.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python -c "import monai, nibabel, numpy"

mkdir -p "$NV_SEGMENT_CTMR_ROOT/models"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  hf download nvidia/NV-Segment-CTMR --local-dir "$NV_SEGMENT_CTMR_ROOT/models/"
test -e "$NV_SEGMENT_CTMR_ROOT/models/model.pt" || \
  mv "$NV_SEGMENT_CTMR_ROOT/models/vista3d_pretrained_model/model.pt" \
    "$NV_SEGMENT_CTMR_ROOT/models/model.pt"
如果
NV_SEGMENT_CTMR_ROOT
未设置或指向已过期的克隆版本，封装程序也会搜索
.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR
路径。
对于Agent生成的用户运行命令，请使用“使用方法”中的命令。请勿将一次性的“初始化设置”块复制到答案中：在基准测试或用户运行期间，请勿在
$NV_SEGMENT_CTMR_ROOT
下创建或写入内容，请勿运行
hf download
，也请勿在共享上游检出目录内移动文件。在Python 3.12环境中，请勿添加
pip install -r "$NV_SEGMENT_CTMR_ROOT/requirements.txt"
命令；上游依赖要求固定NumPy 1.24.4，该版本在Python 3.12环境中无法正常构建。在全新Python环境中，请先安装上述列出的最小兼容运行时包（
monai>=1.5,<1.6
、
numpy<2
、
nibabel
、
scipy
、
typer
、
PyYAML
、
fire
、
huggingface_hub
、
pytorch-ignite
、
einops
），再运行封装程序。缓存的模型并不意味着缓存了Python包。
运行时需要配备CUDA的NVIDIA GPU。上游bundle可能可在仅CPU的主机上导入，但该技能被声明为需要CUDA，因为已发布的工作流是3D CT/MRI基础模型推理路径。

Usage

使用方法

From Medical AI Skills repo root:
bash
export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz \
  --modality CT_BODY \
  --output-dir runs/nv_segment_ctmr_demo
Replace 
PATH_TO_IMAGE.nii.gz
with the user's actual input path. Do not copy the example fixture path into a user run. If the user provides an explicit input path under 
runs/
, that path must be the first positional argument to 
scripts/run_ctmr.py
.
Supported automatic segmentation modalities are 
CT_BODY
, 
MRI_BODY
, and 
MRI_BRAIN
. For 
MRI_BRAIN
, the upstream README requires brain-specific preprocessing before bundle inference; pass an already preprocessed image to this wrapper.
Pass 
--label-prompts "3,14"
to request specific upstream class IDs instead of only the modality-level "segment everything" set. The evidence output records input geometry, output mask path, observed label IDs, unexpected labels, per-class voxel counts, per-class physical volumes from the mask header spacing, runtime, upstream command, model inventory, and geometry checks.
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 and optional per-class Dice/IoU against the recorded ground truth can be checked by 
verifiers/ct_segmentation_quality_v1
for CT-body outputs.
Not for clinical interpretation, production deployment, autonomous diagnosis, or regulatory submission.
从Medical AI Skills仓库根目录运行：
bash
export NV_SEGMENT_CTMR_ROOT="${NV_SEGMENT_CTMR_ROOT:-.workbench_data/upstreams/NV-Segment-CTMR/NV-Segment-CTMR}" && \
python -m pip install "monai>=1.5,<1.6" "numpy<2" nibabel scipy typer PyYAML fire huggingface_hub pytorch-ignite einops && \
python skills/nv-segment-ctmr/scripts/run_ctmr.py PATH_TO_IMAGE.nii.gz \
  --modality CT_BODY \
  --output-dir runs/nv_segment_ctmr_demo
将
PATH_TO_IMAGE.nii.gz
替换为用户实际的输入路径。请勿将示例测试用例路径复制到用户运行命令中。如果用户提供
runs/
下的明确输入路径，该路径必须作为
scripts/run_ctmr.py
的第一个位置参数。
支持的自动分割模态包括
CT_BODY
、
MRI_BODY
和
MRI_BRAIN
。对于
MRI_BRAIN
，上游README要求在bundle推理前进行脑部特定预处理；请将已预处理的图像传入该封装程序。
传递
--label-prompts "3,14"
以请求特定的上游类别ID，而不仅仅是模态级别的“全分割”集合。证据输出会记录输入几何信息、输出掩码路径、观测到的标签ID、意外标签、每类体素计数、来自掩码头间距的每类物理体积、运行时间、上游命令、模型清单和几何检查结果。
传递
--ground-truth PATH
以在
input.ground_truth_path
下记录参考标签映射路径。该技能不计算Dice系数；这是配套验证器的工作。
对于CT体部输出，可通过
verifiers/ct_segmentation_quality_v1
检查解剖结构合理性及可选的每类Dice/IoU（与记录的真实标签对比）。
不用于临床解读、生产部署、自主诊断或监管申报。