meanspace¶

Compute an average oriented voxel space from a set of images, write it as an empty "mock" image, and optionally reslice every input onto it. Use it to put a group of images, which may differ in field of view, voxel size and orientation, on one common grid.

nitorch meanspace FILE... [-o FILE] [-r [FILE]] [-v VAL... [UNIT]]
                          [-p VAL... [UNIT]] [-l LAYOUT]

Description¶

An oriented voxel space is a regular grid of voxels placed in world space: a shape (the number of voxels along each axis) together with an orientation matrix (where the grid sits, which way its axes point and how large its voxels are). Every image defines one. meanspace reads only the headers of its inputs, never their voxel data, and builds a single space that is representative of all of them and large enough to contain all of them.

The space is built in four steps:

1. Orientation. The orientation matrices of the inputs are first brought to a common RAS layout, so that matrices that describe the same orientation with different storage orders can be compared. Their mean is then computed as a log-Euclidean mean (the average of the matrix logarithms, mapped back with the exponential), which averages rotations, scalings and translations sensibly, instead of averaging matrix entries. Spurious shears are removed, so that the result is a rotation and translation combined with a voxel size. Finally, the matrix is converted to the layout that most inputs have (the majority layout), unless you request another one with -l.
2. Voxel size. By default, the voxel size is the one of the mean matrix: the average voxel size of the inputs. You can set another with -v, either in millimetres or as a percentage of that average.
3. Field of view. The corners of all input fields of view are projected into the new space. The space is the bounding box of all of them, so that no input is cropped. -p enlarges (or, with negative values, shrinks) the box.
4. Shape. The box is rounded to a whole number of voxels. A tolerance of 1% of a voxel is used, so that rounding errors do not add an extra slice.

What it is used for¶

The mean space is the natural target when you need to compare, average or jointly analyse images that were not acquired on the same grid, for example before template building or group statistics, or to resample all the images of a study to one resolution without favouring any subject. The output of meanspace is a header and a shape, so the command writes them as an image filled with zeros. This image can be used as the target of reslice (-t); meanspace can also do this resampling for you with -r.

The shape and the orientation matrix of the mean space are printed to the terminal.

Output files¶

• The mean-space image (-o) is a volume of zeros of floating-point type, with the shape and orientation matrix computed above. It is written in the format given by its extension, which is that of the first input by default. If you set -o to no, false or 0, nothing is written unless -r is given; with -r, the mean-space image then goes to a temporary directory, which is removed once the inputs have been resliced.
• With -r, each input is also resliced onto the mean space with the default settings of reslice, that is, linear interpolation and zeros outside the field of view of the input. For other interpolation orders or for label maps, run reslice yourself with the mean-space image as the target.

Arguments¶

Options¶

Voxel size and padding units¶

-v 100 % (the default) keeps the average voxel size; -v 50 % halves it, so that the mean space has twice as many voxels along each axis; -v 1 or -v 1 mm gives 1 mm isotropic voxels; -v 0.8 0.8 1.2 sets anisotropic voxels.

For padding, -p 10 % enlarges the field of view by 10% of its size along each axis (5% on each side), and -p -10 % shrinks it by the same amount. With -p 5 mm, the field of view grows by 5 mm on each side. Here mm stands for any unit other than %, pct or vox: the value is a length in millimetres, converted to voxels with the voxel size of the mean space. With -p 3 vox, it is instead a number of voxels of the mean space added on each side. pct is a synonym of %.

Examples¶

Compute the mean space of three subjects and write it next to the first one as meanspace.nii.gz:

nitorch meanspace sub-01_T1w.nii.gz sub-02_T1w.nii.gz sub-03_T1w.nii.gz

Choose 1 mm isotropic voxels and a name for the output:

nitorch meanspace sub-*_T1w.nii.gz -v 1 mm -o group_space.nii.gz

Compute the mean space with 5% of margin around the union of the fields of view, and reslice every image onto it. Each resliced image is written next to its input, with the suffix .meanspace:

nitorch meanspace sub-01_T1w.nii.gz sub-02_T1w.nii.gz -p 5 % -r

Do the same, but choose where the resliced images go, and keep the mean-space image in a work directory:

nitorch meanspace sub-01_T1w.nii.gz sub-02_T1w.nii.gz \
    -o work/space.nii.gz -r 'work/{base}_group{ext}'

Resample an image onto the mean space yourself, to choose the interpolation order (here cubic splines):

nitorch reslice sub-01_T1w.nii.gz -t work/space.nii.gz -i 3 -o work/sub-01_T1w_cubic.nii.gz

See also¶

• reslice resamples images onto a target space such as the one computed here.
• resize changes the voxel size of an image on a grid derived from its own.
• info prints the shape and orientation matrix of a file.