NeuroImaging in PyTorch
NITorch¶
NITorch is a toolbox for medical image processing and analysis, with a focus on neuroimaging. It is written in PyTorch, which gives it two properties that are rare in a single package: its algorithms run unchanged on a CPU or on a GPU, and its building blocks are differentiable, so they can be used inside neural networks as well as inside classical optimisation-based pipelines.
Much of NITorch is about image registration and spatial transformation. It implements affine matrices (including their Lie-algebra encoding), dense displacement fields, B-spline-encoded deformations, stationary velocity fields and geodesic shooting. On top of these it provides registration tools that work from the command line, algorithms for quantitative MRI and for inverse problems in MRI, a reimplementation of SPM's Unified Segmentation, and a set of small utilities for cropping, padding, resampling and inspecting volumes.
NITorch has been mostly written by Yael Balbastre and Mikael Brudfors in John Ashburner's group at the Wellcome Centre for Human Neuroimaging (the FIL), and is conceptually related to SPM. It is released under the MIT license.
Who it is for¶
NITorch is for people who process brain images and want control over what happens: researchers who build pipelines in shell scripts, who need a registration or a resampling step that behaves the same way every time, or who need to run an algorithm on a cluster without writing any code. It is equally for people who write Python and want tested, differentiable building blocks for registration, resampling and image-based losses.
Two ways to use it¶
The command line is the focus of this site. The nitorch program bundles
the tools into subcommands that read and write NIfTI and MGH volumes, so they
fit into a shell pipeline next to FreeSurfer, FSL or SPM. You do not need to
know any Python to use them. Start with the command-line overview.
The Python library exposes the same algorithms, and the lower-level functions and neural-network layers they are built from. The Python documentation is still being written; see the Python page for an overview of what is there.
What the command line can do¶
-
Inspect, convert, crop, pad, split, pool, smooth and inpaint volumes, and compute overlap metrics between images.
-
Fix or change the orientation of a volume, resize it, reslice it through linear, dense and velocity transformations, compose transformations and compute a mean space.
-
Pairwise affine and non-linear registration with a choice of similarity measures and optimisers, and groupwise normalisation of several scans of a subject.
-
Fit T1, T2* and MTsat maps from multi-echo gradient-echo data, fit exponential decays, and correct geometric distortions of echo-planar data.
-
Total-variation denoising of images and of MRI volumes, and tissue segmentation with a reimplementation of SPM's Unified Segmentation.
-
View volumetric images in an interactive window.
The reference lists every command with a one-line summary.
Quick start¶
Install NITorch (this also installs PyTorch if it is missing; see Installation for GPU support), look at an image, and crop a 64-voxel cube out of its centre:
pip install "nitorch[io,plot] @ git+https://github.com/balbasty/nitorch"
nitorch info T1w.nii.gz
nitorch crop T1w.nii.gz -s 64 64 64
The last command writes T1w.crop.nii.gz next to the input.
Where to go next¶
-
Install NITorch, set up PyTorch for your GPU, and check that it works.
-
How the
nitorchprogram works, with a first session you can follow. -
How options are parsed, which file formats are supported, how output files are named, and how transformations and coordinates are expressed.
-
One page per command, with every option and examples.
-
Worked examples: preparing images, registering two images and working with transformations.
-
The library behind the commands.
NITorch is developed on GitHub, where you can report problems and propose changes.