Name: nv-generate-ct-rflowSkill
Rating: 5 (1 reviews)
Author: nv-generate-ct-rflow


名称	nv-generate-ct-rflow
描述	使用NV-Generate-CTMR rflow-ct生成合成CT体积和掩码。未经审查不得用于生产训练数据。
开源协议	Apache-2.0 allowed-tools: Bash metadata:
作者	NVIDIA MedTech Team tags: - MedTech - CT - generation

NV-Generate-CT (rflow-ct)

目的

使用NV-Generate-CTMR rflow-ct生成合成CT体积和掩码。未经审查不得用于生产训练数据。
完全按照文档使用包装器；不要用自行编写的实现替换上游入口点。
常规运行不要编写自定义推理代码。包装器负责配置暂存、输出路径、标签映射证据和验证。
Manifest I/O：输入为 config_infer_override；输出为 synthetic_ct_volumes 和 result_json。

说明

在更改参数、副作用或验证门之前，先阅读 skill_manifest.yaml。
通过下面的记录命令运行 scripts/run_rflow_ct.py；将输出保持在调用方提供的运行目录下。
如果主机代理暴露了 run_script，请使用 run_script("scripts/run_rflow_ct.py", args=[...]); 否则运行下面显示的Bash/Python命令。
输出一个Bash代码块，并在同一命令中保留 python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" 步骤——运行时可能是一个没有nibabel/MONAI的全新环境，因此去掉安装步骤会出现ModuleNotFoundError。
不要添加 rm、mkdir 或任何清理 --output-dir 的操作；包装器会创建它。请改用全新的 --output-dir，而不是删除旧目录。
在将运行作为证据之前，请检查生成的JSON和配对的验证器指导。

可用的脚本

脚本	目的	参数
`scripts/_anatomy.py`	主入口点使用的内部辅助程序。	仅供导入；不要直接调用。
`scripts/_summary_card.py`	主入口点使用的内部辅助程序。	仅供导入；不要直接调用。
`scripts/list_anatomies.py`	用于目录或解剖结构查询的辅助命令。	`[--region REGION] [--filter TEXT] [--controllable]`
`scripts/run_rflow_ct.py`	skill_manifest.yaml声明的主入口点。	`CONFIG_INFER.json --output-dir OUT_DIR [--random-seed N] [--version rflow-ct] [--yes]`
`scripts/run_ct_mask.py`	独立原始MAISI掩码生成的高级诊断辅助程序。	`REQUEST.json --output-dir OUT_DIR [--random-seed N] [--preflight-only] [--yes]`
`scripts/run_ct_from_mask.py`	根据MAISI标签掩码生成CT图像的高级辅助程序。	`REQUEST.json --output-dir OUT_DIR [--random-seed N] [--yes]`
`scripts/run_ct_image.py`	不带配对标签的仅CT图像生成的高级辅助程序。	`MODEL_CONFIG.json --output-dir OUT_DIR [--version rflow-ct] [--random-seed N] [--yes]`

前提条件

所需环境变量：NV_GENERATE_ROOT。
运行时要求：清单声明时需要的GPU/CUDA；runtime.side_effects.pip_packages中列出的Python包。
副作用：在调用方的--output-dir下写入生成输出，可能在~/.cache/huggingface/下缓存模型资源，并可能在设置期间联系https://huggingface.co或https://github.com。
从存储库根目录运行命令，除非下面现有章节另有说明。

局限性

这是一个轻量级包装器。推理、采样和解码完全委托给NVIDIA-Medtech/NV-Generate-CTMR的scripts.inference。不要修改$NV_GENERATE_ROOT下的代码。
rflow-ct需要CUDA，默认256³输出大小最低约16 GB VRAM。更大的输出大小（如512×512×768）需要A100/H100。
输出体积是合成的。未经独立质量审查，不能安全用作生产医疗技术模型的训练数据。
不用于临床部署、临床解释、自主诊断、监管提交。

故障排除

错误	原因	修复
缺少依赖项或导入错误	与`skill_manifest.yaml`相比运行时包漂移。	安装清单中声明的包或使用文档记录的设置命令。
输出为空或schema无效	输入路径错误、不支持的模态或上游故障。	使用已知fixture重新运行并检查包装器JSON及stderr。
验证门失败	输出违反了声明的工程不变量。	保留失败的证据包并使用门消息修复输入或包装器代码。

包装上游NVIDIA-Medtech/NV-Generate-CTMR rectified-flow合成流水线。包装器不重新实现扩散、采样或自动编码器解码——它完全按照项目README文档的方式shell到上游scripts.inference入口点，并检查生成的图像/掩码对。

前置条件

如果NV_GENERATE_ROOT已命名本地检出，包装器会使用它并在结果中记录当前commit。否则，创建推荐的固定默认检出（一次性）：

if [ -z "${NV_GENERATE_ROOT:-}" ]; then
  export NV_GENERATE_COMMIT=61c4ec709b84cad468852243c48e250bec732074
  export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7"
  if [ ! -d "$NV_GENERATE_ROOT/.git" ]; then
    git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git "$NV_GENERATE_ROOT"
    git -C "$NV_GENERATE_ROOT" checkout --detach "$NV_GENERATE_COMMIT"
  fi
fi
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt"

将rflow-ct权重和掩码候选数据集下载到克隆中（一次性，约5.5 GB）：
```
cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-ct --root_dir "./"
```
掩码候选（datasets/all_masks_flexible_size_and_spacing_4000）对扩散采样器进行条件约束；通过--model_only省略它们将使推理脚本在启动时因缺少文件而失败。解剖尺寸条件文件也是完整CT下载的一部分，可控掩码生成需要它。
NVIDIA GPU，≥16 GB显存和CUDA。没有CPU回退。

对于代理生成的用户运行命令，优先使用Usage中的简短包装命令。当NV_GENERATE_ROOT或本地上游缓存已存在时，不要重复克隆或模型下载设置步骤。在全新的Python环境中，仍然要在包装器之前包含python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt"，除非活动环境已证明这些导入可用；缓存权重并不表示缓存Python包。从medical-AI-skills仓库根目录运行包装器。如果设置需要cd "$NV_GENERATE_ROOT"，在调用skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py之前返回Medical AI Skills仓库。

用法

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
  PATH_TO_CONFIG_INFER.json \
  --output-dir runs/nv_generate_ct_rflow_demo \
  --random-seed 0 \
  --version rflow-ct

将PATH_TO_CONFIG_INFER.json替换为用户实际的请求/配置路径。除非用户明确要求运行该fixture，否则不要复制本文档中的fixture路径。如果用户说“case request at runs/.../chest_lung_tumor_controllable.json”，那么该确切路径就是scripts/run_rflow_ct.py的第一个位置参数。

Fixture参数是一个config_infer.json覆盖文件：它可以替换num_output_samples、body_region、anatomy_list、controllable_anatomy_size、output_size和spacing。传入default则按原样使用上游配置。包装器在运行前将覆盖内容暂存到上游树中。

Fixture目录

fixtures/提供针对常见配对合成用例的精选配置：胸部肺叶、胸部可控肺肿瘤、腹部实质器官、腹部可控肝脏肿瘤、头部+颈椎、骨盆。完整表请参见fixtures/README.md。

辅助命令

# 浏览按身体区域分组的132类label_dict。
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --region chest
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --controllable
python skills/nv-generate-ct-rflow/scripts/list_anatomies.py --filter tumor

# 验证fixture并预览费用，无需启动推理。
NV_GENERATE_ROOT=$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-61c4ec7 \
  python skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py \
    skills/nv-generate-ct-rflow/fixtures/abdomen_liver_spleen.json \
    --output-dir runs/preview --preflight-only

高级辅助程序保持在此skill内部，用于调试和较少见的CT生成模式。仅在用户明确要求该模式时使用它们：

# 原始MAISI掩码诊断，适用于检查肺肿瘤 -> 标签23。
python skills/nv-generate-ct-rflow/scripts/run_ct_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_mask_lung_tumor.json \
  --output-dir runs/ct_mask_debug --preflight-only

# 从具有身体标签200的现有MAISI标签掩码生成CT图像。
python skills/nv-generate-ct-rflow/scripts/run_ct_from_mask.py \
  skills/nv-generate-ct-rflow/fixtures/ct_from_mask_request_example.json \
  --output-dir runs/ct_from_mask_demo

# 不生成配对标签的仅CT图像生成。
python skills/nv-generate-ct-rflow/scripts/run_ct_image.py \
  skills/nv-generate-ct-rflow/fixtures/ct_image_only_default.json \
  --output-dir runs/ct_image_only_demo --version rflow-ct

无论是否指定--preflight-only，包装器都会在每次调用时运行预检：配置schema界限、对照上游label_dict匹配解剖名称、body_region在支持的集合中、可控解剖尺寸约束、上游CT输出尺寸/间距约定、按身体区域的x/y FOV最小值、$NV_GENERATE_ROOT/datasets/下数据集是否存在、CUDA是否可用，以及估计峰值显存/墙钟时间。估计超过5分钟墙钟时间或30 GB显存峰值的运行需要--yes才能继续。

每次调用运行 python -m scripts.inference -t configs/config_network_rflow.json -i configs/config_infer.json -e configs/environment_rflow-ct.json --random-seed <s> --version rflow-ct。输出证据记录上游git commit、模型检查点哈希、渲染配置、每个样本的图像/掩码几何、掩码标签集、图像HU范围摘要和每个类别的体素体积。

当controllable_anatomy_size非空时，上游会忽略更广泛的anatomy_list来保存配对的标签图，并将标签过滤到可控解剖名称。保存的配对标签值是本地1..N序号，而不是原始MAISI标签ID。阅读result_json中的output.output_label_mapping，将保存的输出标签映射回源标签；例如，输出标签1可以表示MAISI标签23（肺肿瘤）。对于精选的肺肿瘤示例，优先选择约0.5或更大的可控大小；诸如0.2的较小请求对于某些种子可能产生缺失或极小的label-23分量。

有关FOV和设置细节，请参见references/fov-and-downloads.md。有关高级辅助标签空间细节，请参见references/ct-mask-label-space.md和references/ct-from-mask-format.md。

可视化样本卡片

除NIfTI对之外，包装器还会在输出目录中写入summary.html：每样本中间切片三联画（轴向/冠状/矢状）并带标签叠加，以及渲染配置和面向验证器的聚合表。无需打开3D Slicer即可目测结果。传入--no-summary-card跳过。

解剖合理性（标签集合理性、作为CT的体素HU范围、图像/掩码几何匹配、声明的输出标签存在、肺叶HU下限）由verifiers/ct_synthesis_quality_v1检查。

不用于临床解释、生产部署的训练数据或任何非合成研究用途。