Usage: Command Line

When installed (see Installation), Nifti Overlay can be accessed from the command line, using the command nifti_overlay. See the docstring for the command line interface (CLI) like so:

nifti_overlay -h

The source code for the CLI can be viewed here.

Basic Usage

There are three primary flavors of arguments that can be supplied to nifti_overlay:

  1. Paths to images you want to visualize

  2. Image-specific options (which modify the plotting of images they are bound to)

  3. Global options (which modify the plot for everything being plotted)

You must provide at least one path to an image to be plotted. There are a few different modes for plotting images:

  • Anatomy (-A, --anat): The most basic plot, which plots the raw values from an image. If you want to view a continuously valued image (from a structural MRI, PET, CT, or whatever), use this option to add images.

  • Mask (-M, --mask): Plots a binary mask or a single label from a segmentation. A single color is used to show the spatial distribution of a label.

  • Edges (-E, --edges): For each slice, an automated edge detection is applied. The extracted edges are plotted.

  • Checkerboard (-C, --checker): Use 2 (or more) images, created a checkerboard pattern where images are interleaved with each other. The typical use case for this is checking registration alignment.

With this information, the most basic call is the specifiy a single image to plot:

nifti_overlay -A t1.nii.gz

There is no limit on how many images you can plot; adding more images will overlay one on top of the other (with the last specified one appearing “on top”).

nifti_overlay -A t1.nii.gz -M brain_mask.nii.gz

Each mode of plotting has specific options which will alter the plotting of a single image. Image-specific arguments are applied to the preceeding image path.

nifti_overlay -A t1.nii.gz --alpha 1.0 -M brain_mask.nii.gz --alpha 0.7

In theabove example, unique opacity values (--alpha) are specified for the anatomy (1.0) and the mask (0.7).

Global arguments, on the other hand, can be specified wherever in the call. For example, these calls (which increase the number of slices plotted) will produce the same output:

nifti_overlay -A t1.nii.gz -M brain_mask.nii.gz --nslices 12
nifti_overlay -A t1.nii.gz --nslices 12 -M brain_mask.nii.gz

See the help docstring for a full list of image-specific and global options.

Outputs

By default, any created visualizations are shown in an interactive matplotlib window. After closing this display, the program exits and the image is not saved (although the interactive viewer can be used to save the image).

To save the image to file, specify the -o/--output argument with a path to an image (see here for a discussion of acceptable image formats).

nifti_overlay -A t1.nii.gz -M brain_mask.nii.gz --nslices 12 -o my_image.png

When writing to a file, the plot is not shown interactively, unless -P/--plot is included.