nv-generate-mr-brain

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

NV-Generate-MR-Brain

Purpose

用途

Used for generating synthetic brain MRI volumes with NV-Generate-CTMR rflow-mr-brain. Not for 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_brain_volumes

and

result_json

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

清单I/O：输入为

model_config_override

；输出为

synthetic_mr_brain_volumes

和

result_json

。

Instructions

使用说明

Read
```
skill_manifest.yaml
```
before changing arguments, side effects, or validation gates.
Run
```
scripts/run_mr_brain.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_brain.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_brain.py
```
；将输出保存至调用者指定的运行目录下。
如果宿主Agent提供
```
run_script
```
接口，请使用
```
run_script("scripts/run_mr_brain.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_brain.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_brain.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-brain generates image-only synthetic brain MRI volumes. It does not emit paired segmentation masks.
Output volumes are synthetic. They are not safe as training data for production medtech models without independent 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-brain仅生成纯影像的合成脑部MRI数据，不会输出配对的分割掩码。
输出的影像为合成数据，未经独立质量审核前，不可作为医疗科技生产模型的训练数据。
不可用于临床部署、临床解读、自主诊断或监管申报。

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

, then summarizes the generated NIfTI volume.

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

本工具封装了上游

NVIDIA-Medtech/NV-Generate-CTMR

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

rflow-mr-brain

对应的

python -m scripts.diff_model_infer

命令，然后对生成的NIfTI影像数据进行汇总。

Exact Runnable Surface

可运行命令规范

For user run commands, use this repo-root wrapper path 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-brain/scripts/run_mr_brain.py PATH_TO_MR_BRAIN_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 1234

Do not invent

generate.sh

infer.py

Medical AI Skills run

, or

python -m nv_generate_mr_brain

commands.

PATH_TO_MR_BRAIN_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-brain/scripts/run_mr_brain.py PATH_TO_MR_BRAIN_CONFIG.json --output-dir OUT_DIR --modality mri_t1 --random-seed 1234

请勿自行创建

generate.sh

、

infer.py

、

Medical AI Skills run

或

python -m nv_generate_mr_brain

等命令。

PATH_TO_MR_BRAIN_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-brain weights:

bash

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr-brain --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-brain/scripts/run_mr_brain.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"

下载脑部MRI模型权重：

bash

cd "$NV_GENERATE_ROOT"
python -m scripts.download_model_data --version rflow-mr-brain --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-brain/scripts/run_mr_brain.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-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234

Replace

PATH_TO_MR_BRAIN_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_brain.py

Supported MR-brain modality names are

mri

mri_t1

mri_t2

mri_flair

mri_swi

mri_t1_skull_stripped

mri_t2_skull_stripped

mri_flair_skull_stripped

, and

mri_swi_skull_stripped

. These map to the upstream

configs/modality_mapping.json

IDs documented in the README. 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-brain.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-brain/scripts/run_mr_brain.py \
  PATH_TO_MR_BRAIN_CONFIG.json \
  --output-dir runs/nv_generate_mr_brain_demo \
  --modality mri_t1 \
  --random-seed 1234

将

PATH_TO_MR_BRAIN_CONFIG.json

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

runs/.../default_mri_t1.json

”，则该路径即为

scripts/run_mr_brain.py

的第一个位置参数。

支持的脑部MRI模态名称包括

mri

、

mri_t1

、

mri_t2

、

mri_flair

、

mri_swi

、

mri_t1_skull_stripped

、

mri_t2_skull_stripped

、

mri_flair_skull_stripped

和

mri_swi_skull_stripped

。这些模态对应上游

configs/modality_mapping.json

中记录的ID，具体可参考README文档。关于视场（FOV）及设置细节，请查看

references/fov-and-downloads.md

。

测试用例参数是对

configs/config_maisi_diff_model_rflow-mr-brain.json

的小型JSON覆盖。传入

default

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

dim

、

spacing

、

num_inference_steps

、

cfg_guidance_scale

和

modality

。

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

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