Brain template example

This example builds a population brain template from the LUMIR24 dataset using TransMorphTVF, VFA, or ConvexAdam. The script is self‑contained except for the dataset itself: you must download LUMIR24 dataset in advance.

Pipeline overview

  1. Initialize the model (TransMorphTVF, VFA, or ConvexAdam).

  2. For a set number of iterations:

    • Register all subjects to the current template.

    • Average the deformed images in either log‑domain (velocity) or displacement field domain to form a new template.

  3. Save the intermediate templates as NIfTI files.

Prerequisites

  • LUMIR24 dataset downloaded locally.

  • CUDA‑enabled PyTorch (recommended).

  • Internet access on first run to download pretrained weights (TransMorphTVF/VFA) and the LUMIR JSON file.

Dataset requirement

Download LUMIR24 and set the base directory in the script:

  • LUMIR_BASE_DIR: root folder that contains the LUMIR24 images referenced by LUMIR_dataset.json.

The script will download LUMIR_dataset.json automatically if it is missing, but the images themselves must be present.

Run the example

From tutorials/build_brain_template:

python3.8 -u build_template.py

Configuration

Edit these settings near the top of build_template.py to match your environment and method choice:

  • MODEL_TYPE: "TransMorphTVF", "VFA", or "ConvexAdam"

  • LUMIR_BASE_DIR: path to your local LUMIR24 data

  • WEIGHTS_PATH: folder for pretrained weights (auto‑download)

  • OUT_DIR: output folder for NIfTI templates

  • NUM_ITERS: number of template refinement iterations

  • SHAPE_AVG_LOGDOMAIN: log‑domain (velocity) averaging vs. flow averaging

Outputs

Templates are saved as NIfTI files in template_outputs:

  • template_outputs/template_iter_00.nii.gz

  • template_outputs/template_iter_01.nii.gz

  • …

Notes

  • Pretrained weights are downloaded only for TransMorphTVF and VFA.

  • ConvexAdam does not require pretrained weights.