nv-generate-ct-rflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NV-Generate-CT (rflow-ct)

Purpose

用途

Used for generating synthetic CT volumes and masks with NV-Generate-CTMR rflow-ct. Not for production training data without review.
Use the wrapper exactly as documented; do not replace the upstream entrypoint with a handwritten implementation.
Do not write custom inference code for normal runs. The wrapper owns config staging, output paths, label mapping evidence, and validation.

Manifest I/O: inputs are

config_infer_override

; outputs are

synthetic_ct_volumes

and

result_json

用于通过NV-Generate-CTMR rflow-ct生成合成CT体和掩码。未经审核不得用于生产训练数据。
严格按照文档说明使用封装器；请勿用手写实现替换上游入口点。
正常运行时请勿编写自定义推理代码。封装器负责配置暂存、输出路径、标签映射验证和校验。

清单输入输出：输入为

config_infer_override

；输出为

synthetic_ct_volumes

和

result_json

。

Instructions

使用说明

Read
```
skill_manifest.yaml
```
before changing arguments, side effects, or validation gates.
Run
```
scripts/run_rflow_ct.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_rflow_ct.py", args=[...])
```
; otherwise run the Bash/Python command shown below.
Emit a single bash code block, and keep the
```
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt"
```
step in that same command — the runtime may be a fresh environment without
```
nibabel
```
/MONAI, so dropping the install fails with
```
ModuleNotFoundError
```
.
Do not add
```
rm
```
,
```
mkdir
```
, or any cleanup of
```
--output-dir
```
; the wrapper creates it. Use a fresh
```
--output-dir
```
instead of deleting one.
Check the emitted JSON and paired verifier guidance before treating the run as evidence.

在修改参数、副作用或校验规则前，请先阅读
```
skill_manifest.yaml
```
。
通过下方文档记录的命令运行
```
scripts/run_rflow_ct.py
```
；将输出保存在调用方提供的运行目录下。
如果主机Agent暴露
```
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文件及配套验证器指南。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/_anatomy.py`	Internal helper used by the primary entrypoint.	Imported only; do not call directly.
`scripts/_summary_card.py`	Internal helper used by the primary entrypoint.	Imported only; do not call directly.
`scripts/list_anatomies.py`	Helper command for catalog or anatomy lookup.	`[--region REGION] [--filter TEXT] [--controllable]`
`scripts/run_rflow_ct.py`	Primary entrypoint declared by skill_manifest.yaml.	`CONFIG_INFER.json --output-dir OUT_DIR [--random-seed N] [--version rflow-ct] [--yes]`
`scripts/run_ct_mask.py`	Advanced diagnostic helper for standalone raw MAISI mask generation.	`REQUEST.json --output-dir OUT_DIR [--random-seed N] [--preflight-only] [--yes]`
`scripts/run_ct_from_mask.py`	Advanced helper for CT image generation from a MAISI label mask.	`REQUEST.json --output-dir OUT_DIR [--random-seed N] [--yes]`
`scripts/run_ct_image.py`	Advanced helper for CT image-only generation without paired labels.	`MODEL_CONFIG.json --output-dir OUT_DIR [--version rflow-ct] [--random-seed N] [--yes]`

脚本	用途	参数
`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]`

Prerequisites

前置条件

Required environment variables:
```
NV_GENERATE_ROOT
```
.
Runtime requirements: GPU/CUDA when declared by the manifest; Python packages listed in
```
runtime.side_effects.pip_packages
```
.
Side effects: writes generated outputs under the caller's
```
--output-dir
```
, may cache model assets under
```
~/.cache/huggingface/
```
, and may contact
```
https://huggingface.co
```
or
```
https://github.com
```
during setup.
Run commands from the repository root unless an existing section below says otherwise.

必填环境变量：
```
NV_GENERATE_ROOT
```
。
运行时要求：清单声明时需GPU/CUDA；需安装
```
runtime.side_effects.pip_packages
```
中列出的Python包。
副作用：在调用方指定的
```
--output-dir
```
下写入生成的输出，可能在
```
~/.cache/huggingface/
```
下缓存模型资产，且在设置过程中可能访问
```
https://huggingface.co
```
或
```
https://github.com
```
。
除非下方已有章节说明，否则请从仓库根目录运行命令。

Limitations

局限性

This is a thin wrapper. Inference, sampling, and decoding are delegated entirely to NVIDIA-Medtech/NV-Generate-CTMR's
```
scripts.inference
```
. Do not modify code under $NV_GENERATE_ROOT.
rflow-ct requires CUDA and ≈ 16 GB VRAM minimum for the default 256³ output_size. Larger output_size (e.g. 512×512×768) needs an A100/H100.
Output volumes are synthetic. They are not safe to use as training data for production medtech models without an independent quality review.
Not for clinical deployment, clinical interpretation, autonomous diagnosis, regulatory submission.

这是一个轻量封装器。推理、采样和解码完全委托给NVIDIA-Medtech/NV-Generate-CTMR的
```
scripts.inference
```
。请勿修改
```
$NV_GENERATE_ROOT
```
下的代码。
rflow-ct需要CUDA，且默认256³输出大小至少需要≈16 GB显存。更大的输出大小（如512×512×768）需要A100/H100显卡。
输出体是合成数据。未经独立质量审核，不得将其用作医疗科技生产模型的训练数据。
不得用于临床部署、临床解读、自主诊断或监管申报。

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-Medtech/NV-Generate-CTMR

rectified-flow synthesis pipeline. The wrapper does not reimplement diffusion, sampling, or autoencoder decoding — it shells out to the upstream

scripts.inference

entry point exactly as the project's README documents and inspects the produced image/mask pairs.

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

本工具封装了上游

NVIDIA-Medtech/NV-Generate-CTMR

的整流流合成流水线。封装器未重新实现扩散、采样或自动编码器解码——它完全按照项目README文档的说明调用上游

scripts.inference

入口点，并检查生成的图像/掩码对。

Preconditions

前置准备

Clone the upstream repo and point

NV_GENERATE_ROOT

at it (one-time):

bash

test -d "$HOME/nv-generate-ctmr/.git" || \
  git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git $HOME/nv-generate-ctmr
export NV_GENERATE_ROOT=$HOME/nv-generate-ctmr
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

Download the
```
rflow-ct
```
weights and the mask-candidate datasets into the clone (one-time, ≈ 5.5 GB):
bash
```
cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-ct --root_dir "./"
```
The mask candidates (
```
datasets/all_masks_flexible_size_and_spacing_4000
```
) condition the diffusion sampler; omitting them via
```
--model_only
```
will make the inference script fail with a missing-file error at startup. The anatomy-size condition file is also part of the full CT download and is needed for controllable mask generation.
NVIDIA GPU with ≥ 16 GB VRAM and CUDA. There is no CPU fallback.

For agent-generated user run commands, prefer the short wrapper command in Usage. Do not prepend clone or model-download setup steps when

NV_GENERATE_ROOT

or the repo-local upstream cache is already present. In a fresh Python environment, still include

pip install -r "$NV_GENERATE_ROOT/requirements.txt"

before the wrapper unless the active environment has already proven those imports are available; cached weights do not imply cached Python packages. Run the wrapper from the medical-AI-skills repo root. If setup requires

cd "$NV_GENERATE_ROOT"

, return to the Medical AI Skills repo before invoking

skills/nv-generate-ct-rflow/scripts/run_rflow_ct.py

克隆上游仓库并将

NV_GENERATE_ROOT

指向该仓库（仅需一次）：

bash

test -d "$HOME/nv-generate-ctmr/.git" || \
  git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git $HOME/nv-generate-ctmr
export NV_GENERATE_ROOT=$HOME/nv-generate-ctmr
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

将
```
rflow-ct
```
权重以及掩码候选数据集下载到克隆的仓库中（仅需一次，约5.5 GB）：
bash
```
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下载的一部分，是可控掩码生成所必需的。
配备≥16 GB显存和CUDA的NVIDIA GPU。无CPU fallback方案。

对于Agent生成的用户运行命令，优先使用用法说明中的简短封装器命令。当

NV_GENERATE_ROOT

或仓库本地上游缓存已存在时，请勿添加克隆或模型下载的设置步骤。在全新Python环境中，除非当前环境已确认相关导入可用，否则仍需在封装器命令前包含

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仓库。

Usage

使用示例

bash

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/nv-generate-ctmr}" && \
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

Replace

PATH_TO_CONFIG_INFER.json

with the user's actual request/config path. Do not copy the fixture path from this document unless the user explicitly asked to run that fixture. If the user says "the case request is at

runs/.../chest_lung_tumor_controllable.json

", that exact path is the first positional argument to

scripts/run_rflow_ct.py

The fixture argument is a

config_infer.json

override file: it can replace

num_output_samples

body_region

anatomy_list

controllable_anatomy_size

output_size

, and

spacing

. Pass

default

to use the upstream config verbatim. The wrapper stages the override into the upstream tree before running.

bash

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/nv-generate-ctmr}" && \
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

替换为用户实际的请求/配置路径。除非用户明确要求运行测试用例，否则请勿复制本文档中的测试用例路径。如果用户表示"病例请求位于

runs/.../chest_lung_tumor_controllable.json

"，则该精确路径即为

scripts/run_rflow_ct.py

的第一个位置参数。

测试用例参数是一个

config_infer.json

覆盖文件：它可以替换

num_output_samples

、

body_region

、

anatomy_list

、

controllable_anatomy_size

、

output_size

和

spacing

。传入

default

即可直接使用上游配置。封装器会在运行前将覆盖配置暂存到上游目录中。

Fixture catalog

测试用例目录

fixtures/

ships curated configs for common paired synthesis use cases: chest lung lobes, chest with controllable lung tumor, abdomen solid organs, abdomen with controllable hepatic tumor, head + cervical spine, pelvis. See

fixtures/README.md

for the full table.

fixtures/

目录包含针对常见配对合成场景的 curated 配置：胸部肺叶、带可控肺肿瘤的胸部、腹部实体器官、带可控肝肿瘤的腹部、头部+颈椎、骨盆。完整列表请查看

fixtures/README.md

。

Helper commands

辅助命令

bash

undefined

bash

undefined

Browse the 132-class label_dict grouped by body region.

按身体部位浏览包含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

Validate a fixture and preview cost without launching inference.

验证测试用例并预估成本，无需启动推理。

NV_GENERATE_ROOT=$HOME/nv-generate-ctmr
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


Advanced helpers stay inside this skill for debugging and less-common CT
generation modes. Use them only when the user explicitly asks for that mode:

```bash


高级辅助工具用于调试和较不常见的CT生成模式，仅当用户明确要求该模式时才使用：

```bash

Raw MAISI mask diagnostic, useful for checking lung tumor -> label 23.

原始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

CT image from an existing MAISI label mask with body label 200.

从现有MAISI标签掩码（身体标签200）生成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 image-only generation without paired labels.

仅生成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


The wrapper runs preflight on every invocation (regardless of
`--preflight-only`): config-schema bounds, anatomy names matched
against the upstream label_dict, body_region in the supported set,
controllable_anatomy_size constraints, upstream CT output-size/spacing
contracts, body-region-aware x/y FOV minimums, dataset presence under
`$NV_GENERATE_ROOT/datasets/`, CUDA available, and an estimated peak VRAM /
wall-time. Runs estimated to exceed 5 min wall-time or 30 GB VRAM peak require
`--yes` to proceed.

Each invocation runs `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`. Output evidence records the upstream git commit, model
checkpoint hashes, the rendered config, per-sample image/mask geometry, mask
label set, image HU range summary, and per-class voxel volumes.

When `controllable_anatomy_size` is non-empty, upstream ignores the broader
`anatomy_list` for the saved paired label map and filters labels to the
controllable anatomy names. The saved paired label values are local `1..N`
ordinals, not raw MAISI label IDs. Read `output.output_label_mapping` in
`result_json` to map saved output labels back to source labels; for example,
output label `1` can represent MAISI label `23` (`lung tumor`).
For curated lung-tumor examples, prefer a controllable size around `0.5` or
larger; smaller requests such as `0.2` can produce absent or extremely small
label-23 components for some seeds.

For FOV and setup details, see `references/fov-and-downloads.md`. For
advanced helper label-space details, see
`references/ct-mask-label-space.md` and `references/ct-from-mask-format.md`.

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匹配、身体部位在支持范围内、可控解剖结构大小约束、上游CT输出大小/间距约定、身体部位相关的x/y视野最小值、`$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提交记录、模型检查点哈希、渲染后的配置、每个样本的图像/掩码几何信息、掩码标签集、图像HU范围汇总以及每个类别的体素体积。

当`controllable_anatomy_size`非空时，上游会忽略保存的配对标签映射中更宽泛的`anatomy_list`，并将标签过滤为可控解剖结构名称。保存的配对标签值是本地的`1..N`序数，而非原始MAISI标签ID。请查看`result_json`中的`output.output_label_mapping`，将保存的输出标签映射回源标签；例如，输出标签`1`可以代表MAISI标签`23`（`lung tumor`）。对于curated的肺肿瘤示例，可控大小建议设置为`0.5`或更大；较小的设置（如`0.2`）可能会导致某些随机种子下标签23对应的组件缺失或极小。

关于视野和设置的详细信息，请查看`references/fov-and-downloads.md`。关于高级辅助工具标签空间的详细信息，请查看`references/ct-mask-label-space.md`和`references/ct-from-mask-format.md`。

Visual sample card

可视化样本卡片

Alongside the NIfTI pairs, the wrapper writes

summary.html

to the output directory: a per-sample mid-slice triptych (axial / coronal / sagittal) with label overlay, plus a table of the rendered config and verifier-facing aggregates. Lets you eyeball the result without firing up 3D Slicer. Pass

--no-summary-card

to skip.

Anatomy plausibility (label-set sanity, voxel HU range as CT, image/mask geometry match, declared output labels present, lung-lobe HU floor) is checked by

verifiers/ct_synthesis_quality_v1

Not for clinical interpretation, training data for production deployment, or any non-synthetic-research use.

除了NIfTI对之外，封装器还会在输出目录中写入

summary.html

：每个样本的中切片三联图（轴位/冠状位/矢状位）并叠加标签，以及渲染后的配置和面向验证器的汇总表格。无需启动3D Slicer即可直观查看结果。添加

--no-summary-card

参数可跳过生成该文件。

解剖结构合理性（标签集完整性、CT图像的体素HU范围、图像/掩码几何匹配、已声明的输出标签存在性、肺叶HU下限）由

verifiers/ct_synthesis_quality_v1

进行检查。

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