nv-generate-mr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NV-Generate-MR

Purpose

用途

Used for generating synthetic body MRI volumes with NV-Generate-CTMR rflow-mr. Not for paired masks or production training data.
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, and validation.

Manifest I/O: inputs are

model_config_override

; outputs are

synthetic_mr_volumes

and

result_json

用于借助NV-Generate-CTMR rflow-mr生成合成身体MRI影像体积。不适用于配对掩码或生产训练数据。
严格按照文档说明使用包装器；请勿用手写实现替换上游入口点。
常规运行时请勿编写自定义推理代码。包装器负责配置暂存、输出路径和验证工作。

清单输入输出：输入为

model_config_override

；输出为

synthetic_mr_volumes

和

result_json

。

Instructions

使用说明

Read
```
skill_manifest.yaml
```
before changing arguments, side effects, or validation gates.
Run
```
scripts/run_mr.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_mr.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_mr.py
```
；将输出保存在调用者提供的运行目录下。
如果宿主Agent暴露
```
run_script
```
接口，请使用
```
run_script("scripts/run_mr.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/run_mr.py`	Primary entrypoint declared by skill_manifest.yaml.	`MODEL_CONFIG.json --output-dir OUT_DIR --modality mri_t1 [--random-seed N] [--yes]`

脚本	用途	参数
`scripts/run_mr.py`	`skill_manifest.yaml` 中声明的主要入口点。	`MODEL_CONFIG.json --output-dir OUT_DIR --modality mri_t1 [--random-seed N] [--yes]`

Prerequisites

前置条件

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.

运行时要求：清单声明需要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.diff_model_infer
```
. Do not modify code under $NV_GENERATE_ROOT or the repo-local fallback at .workbench_data/upstreams/NV-Generate-CTMR.
rflow-mr generates image-only synthetic MRI volumes. It does not emit paired segmentation masks.
The upstream README recommends
```
rflow-mr-brain
```
instead for brain MRI synthesis; use
```
skills/nv-generate-mr-brain
```
for that path.
NV-Generate-MR weights are listed by upstream as NVIDIA Non-Commercial. Do not use outputs as production training data without legal and quality review.
Not for clinical deployment, clinical interpretation, autonomous diagnosis, regulatory submission.

这是一个轻量包装器。推理、采样和解码操作完全委托给NVIDIA-Medtech/NV-Generate-CTMR的
```
scripts.diff_model_infer
```
。请勿修改$NV_GENERATE_ROOT下的代码或本地仓库缓存路径.workbench_data/upstreams/NV-Generate-CTMR中的代码。
rflow-mr仅生成纯影像的合成MRI体积，不会输出配对的分割掩码。
上游README文档推荐使用
```
rflow-mr-brain
```
进行脑部MRI合成；请通过
```
skills/nv-generate-mr-brain
```
路径使用该工具。
NV-Generate-MR权重被上游标记为NVIDIA非商用。未经法律和质量审核，请勿将输出用作生产训练数据。
不适用于临床部署、临床解读、自动诊断或监管申报。

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

MR image-only generation workflow. The wrapper does not reimplement diffusion sampling or autoencoder decoding. It stages config overrides, runs the documented

python -m scripts.diff_model_infer

command for

rflow-mr

, then summarizes the generated NIfTI volume.

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

本工具封装了上游

NVIDIA-Medtech/NV-Generate-CTMR

的纯MRI影像生成工作流。包装器未重新实现扩散采样或自动编码器解码逻辑，仅负责配置覆盖的暂存、运行

rflow-mr

对应的文档命令

python -m scripts.diff_model_infer

，然后汇总生成的NIfTI体积信息。

Exact Runnable Surface

可运行的精确命令

For user run commands in a fresh benchmark environment, use this setup plus repo-root wrapper command exactly:

bash

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py PATH_TO_MR_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 0

Do not invent

generate.sh

infer.py

Medical AI Skills run

, or

python -m nv_generate_mr

commands.

PATH_TO_MR_CONFIG.json

must be the user's supplied request path.

在全新的基准测试环境中运行用户命令时，请严格使用以下设置命令加上仓库根目录的包装器命令：

bash

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py PATH_TO_MR_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 0

请勿自行创建

generate.sh

、

infer.py

、

Medical AI Skills run

或

python -m nv_generate_mr

等命令。

PATH_TO_MR_CONFIG.json

必须是用户提供的请求路径。

Preconditions

前置准备

Clone and install the upstream repo 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-Generate-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git \
    .workbench_data/upstreams/NV-Generate-CTMR
export NV_GENERATE_ROOT=.workbench_data/upstreams/NV-Generate-CTMR
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

Download the MR weights:

bash

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr --root_dir ./ --model_only

Runtime needs an NVIDIA GPU with at least 16 GB VRAM. There is no CPU fallback in the upstream path.

The wrapper also searches

.workbench_data/upstreams/NV-Generate-CTMR

NV_GENERATE_ROOT

is unset or points at a stale clone.

For agent-generated user run commands, use the command in Usage. Do not prepend clone or model-download setup steps when the repo-local upstream cache already exists. 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. If setup requires

cd "$NV_GENERATE_ROOT"

, return to the Medical AI Skills repo before invoking

skills/nv-generate-mr/scripts/run_mr.py

克隆并安装上游仓库一次。在本Medical AI Skills检出目录中，优先使用本地仓库缓存路径（如果存在）：

bash

mkdir -p .workbench_data/upstreams
test -d .workbench_data/upstreams/NV-Generate-CTMR/.git || \
  git clone https://github.com/NVIDIA-Medtech/NV-Generate-CTMR.git \
    .workbench_data/upstreams/NV-Generate-CTMR
export NV_GENERATE_ROOT=.workbench_data/upstreams/NV-Generate-CTMR
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

下载MR权重：

bash

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr --root_dir ./ --model_only

运行时需要至少16GB显存的NVIDIA GPU。上游路径不支持CPU fallback。

如果

NV_GENERATE_ROOT

未设置或指向过时的克隆版本，包装器也会搜索

.workbench_data/upstreams/NV-Generate-CTMR

路径。

对于Agent生成的用户运行命令，请使用“用法”部分中的命令。当本地仓库的上游缓存已存在时，请勿添加克隆或模型下载的设置步骤。在全新的Python环境中，除非当前环境已确认相关导入可用，否则仍需在运行包装器前执行

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

；缓存的权重并不意味着缓存了Python包。如果设置步骤需要

cd "$NV_GENERATE_ROOT"

，请在调用

skills/nv-generate-mr/scripts/run_mr.py

前返回Medical AI Skills仓库目录。

Usage

用法

bash

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py \
  PATH_TO_MR_CONFIG.json \
  --output-dir runs/nv_generate_mr_demo \
  --modality mri_t1 \
  --random-seed 0

Replace

PATH_TO_MR_CONFIG.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 request is at

runs/.../default_mri_t1.json

", that exact path is the first positional argument to

scripts/run_mr.py

Supported rflow-mr modality names are

mri

mri_t1

mri_t2

, and

mri_flair

, matching the upstream MR image-generation guide. The upstream README recommends

rflow-mr-brain

instead when synthesizing brain images; use

skills/nv-generate-mr-brain

for that path. For FOV and setup details, see

references/fov-and-downloads.md

The fixture argument is a small JSON override for

configs/config_maisi_diff_model_rflow-mr.json

. Pass

default

to use the upstream defaults plus the CLI modality and random seed. Common override keys are

dim

spacing

num_inference_steps

cfg_guidance_scale

, and

modality

Each run records the staged config, model inventory, upstream command, output geometry, spacing, affine, intensity range, and non-constant / finite-data checks. Output volumes are synthetic and are not safe as production training data without independent review.

Not for clinical interpretation, production deployment, autonomous diagnosis, or regulatory submission.

bash

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-.workbench_data/upstreams/NV-Generate-CTMR}" && \
python -m pip install -r "$NV_GENERATE_ROOT/requirements.txt" && \
python skills/nv-generate-mr/scripts/run_mr.py \
  PATH_TO_MR_CONFIG.json \
  --output-dir runs/nv_generate_mr_demo \
  --modality mri_t1 \
  --random-seed 0

将

PATH_TO_MR_CONFIG.json

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

runs/.../default_mri_t1.json

”，请将该精确路径作为

scripts/run_mr.py

的第一个位置参数。

rflow-mr支持的模态名称包括

mri

、

mri_t1

、

mri_t2

和

mri_flair

，与上游MR影像生成指南一致。上游README文档推荐在合成脑部影像时使用

rflow-mr-brain

；请通过

skills/nv-generate-mr-brain

路径使用该工具。关于FOV和设置细节，请参阅

references/fov-and-downloads.md

。

测试用例参数是对

configs/config_maisi_diff_model_rflow-mr.json

的小型JSON覆盖。传入

default

将使用上游默认值加上CLI指定的模态和随机种子。常见的覆盖键包括

dim

、

spacing

、

num_inference_steps

、

cfg_guidance_scale

和

modality

。

每次运行都会记录暂存的配置、模型清单、上游命令、输出几何结构、间距、仿射变换、强度范围以及非恒定/有限数据检查。生成的影像体积为合成数据，未经独立审核不得作为生产训练数据使用。

不适用于临床解读、生产部署、自动诊断或监管申报。