TopoFit is a learning-based tool that rapidly fits a topologically-correct surface to cerebral cortex in brain MRI. This code base implements the model described in the following paper:
TopoFit: Rapid Reconstruction of Topologically-Correct Cortical Surfaces
Andrew Hoopes, Juan Eugenio Iglesias, Bruce Fischl, Douglas Greve, Adrian V. Dalca
Medical Imaging with Deep Learning. 2022.
To evaluate a pretrained TopoFit model, you can download the development version of FreeSurfer and run the mris_estimate_wm command line tool. However, to develop and train a TopoFit model using custom data, clone this repository and follow the instructs below.
The guided (or neighborhood-based) training loss requires a 500MB neighorhood mapping file that is too large to store on GitHub. In order to train a model, you must download neighorhoods.npz and move it to the topofit subdirectory of this repository.
Brain surface data needs to be preprocessed so that all 'ground-truth' meshes share the same template topology. First, FreeSurfer's recon-all command must be run on each subject's T1w brain MRI. Following this, the preprocess script must be run on each recon output:
./preprocess /path/to/recon/subject
This will generate additional surface files in the subject's surf subdirectory.
Once surfaces have been preprocessed, a TopoFit model is trained for a given brain hemisphere (lr or rh) with:
./train --hemi lh \
--outdir /path/to/output/directory \
--training-subjs /path/to/train.txt \
--validation-subjs /path/to/validation.txt
In this example, train.txt and validation.txt are line-by-line lists of full paths to preprocessed recon subjects. Subjects will be randomly sampled from this list during training. Only 5-20 validation subjects are necessary. This script implements a learning-rate decay strategy based on the validation distance metric. Training will exit automatically once accuracy plateaus. In general, training should complete between 2000-3000 epochs. Logging and model weight checkpoints will be saved to the specified output directory.
Once a model has been trained, it can be evaluated on any set of recon-all subjects by running:
./evaluate --hemi lh \
--model /path/to/output/directory/2000.pt \
--subjs /path/to/recon/subject ...
This will save the predicted FreeSurfer-formatted surface as lh.white.topofit in the subject's surf subdirectory.
We provide a public dataset of white matter surface meshes that correspond to 414 subjects in the processed neurite oasis MRI dataset (the T1 image data can be downloaded through this link). The corresponding surface data is available for download here.