NV-Generate-MR-Brain

Purpose

• Used for generating synthetic T1, T2, FLAIR, SWI, or MRA brain MRI volumes with NV-Generate-CTMR rflow-mr-brain v1. 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.

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.
• For a command-shape review, do not install packages, clone repositories, download weights, or start GPU inference. Emit only the exact wrapper command with the supplied config path plus explicit --output-dir, --modality, and --random-seed values.
• For an executable run, 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.
• If --modality mri_mra is selected, state that upstream reports sparse MRA training coverage and that output quality is not guaranteed.
• 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.

Examples

Command-shape review only (no setup or execution):

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

For an executable run, use the setup-aware command under Usage.

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]

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.

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.

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.

Exact Runnable Surface

For user run commands, use this repo-root wrapper path exactly:

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
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.

Preconditions

If NV_GENERATE_ROOT already names a local checkout, the wrapper uses it and records its current commit in the result. Otherwise, create the recommended pinned default checkout once:

if [ -z "${NV_GENERATE_ROOT:-}" ]; then
  export NV_GENERATE_COMMIT=da438fec6484cdb6f421f8c7051d954ebefff730
  export NV_GENERATE_ROOT="$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe"
  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
pip install -r "$NV_GENERATE_ROOT/requirements.txt"

The wrapper executes upstream code only when NV_GENERATE_ROOT is at the exact manifest commit and its tracked files are clean. Keep model weights untracked under models/, and use the wrapper override JSON instead of editing upstream configs. Child processes receive only an allowlist of runtime, CUDA, locale, and certificate variables; API keys, tokens, passwords, and unrelated parent environment values are not forwarded.

Download the reused autoencoder and MR-Brain v1 checkpoint from their exact manifest revisions:

python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-CT models/autoencoder_v1.pt \
  --revision 75ac080fb1083c403793563477724c038e7d430c \
  --local-dir "$NV_GENERATE_ROOT"
python -m huggingface_hub.commands.huggingface_cli download \
  nvidia/NV-Generate-MR-Brain models/diff_unet_3d_rflow-mr-brain_v1.pt \
  --revision ef9759bf221265b2704569cdeeac20bbf03b62ee \
  --local-dir "$NV_GENERATE_ROOT"

The wrapper verifies both downloaded files against their published Git LFS SHA-256 object IDs before launching inference.

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 if NV_GENERATE_ROOT is unset or does not have the required upstream layout.

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.

Usage

export NV_GENERATE_ROOT="${NV_GENERATE_ROOT:-$HOME/.cache/nvidia-skills/upstreams/NV-Generate-CTMR-da438fe}" && \
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_mra, mri_swi, mri_t1_skull_stripped, mri_t2_skull_stripped, mri_flair_skull_stripped, mri_mra_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 pinned v1 config ships axial T1w defaults of dim=[256,256,128], spacing=[0.94,0.94,1.36], 30 inference steps, and cfg_guidance_scale=2. Keep the staged config value unless a model-specific validation justifies an override; older examples may describe the v0 256^3/1 mm geometry or guidance scale 10. MRA is supported by v1, but the upstream training-data report contains few MRA scans, so output quality is not guaranteed.

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.