Command line interface

FSLeyes has a comprehensive command line interface. Nearly everything that you can control through the overlay display panel, and the view settings panel for orthographic/lightbox views, can be set via the command line.

Overview

The FSLeyes command line interface follows this pattern:

fsleyes [options] file [displayOpts] file [displayOpts] ...

where:

  • options refers to options which relate to FSLeyes layout, behaviour, orthographic/lightbox configuration, etc.
  • displayOpts refers to a group of options which are applied to the file that preceeds the group.

Help

To get a brief overview of the FSLeyes command line interface, which just displays basic options:

fsleyes --help
fsleyes  -h

To get help on the full FSLeyes command line interface (warning: it is quite long!):

fsleyes --fullhelp
fsleyes  -fh

To print the version of FSLeyes you are using:

fsleyes --version
fsleyes  -V

Useful command line options

What follows is a short list highlighting some of the features in FSLeyes that you can access through the command line interface. For full details, refer to the command line help.

Auto-display

fsleyes --autoDisplay files ...
fsleyes  -ad          files ...

The --autoDisplay option tells FSLeyes to automatically configure certain display properties when you load an overlay. For example, if you start FSLeyes with --autoDisplay, and then load some Z-statistic images from a FEAT analysis, FSLeyes will set a colour map and threshold value on the images.

As another example, loading a MELODIC analysis with --autoDisplay enabled will cause FSLeyes to load a background image, and to configure positive and negative colour maps on the melodic_IC image.

Add standard

fsleyes --standard    files ...
fsleyes --standard1mm files ...
fsleyes  -std         files ...
fsleyes  -std1mm      files ...

The --standard and --standard1mm options respectively tell FSLeyes to load 2mm and 1mm versions of the MNI152 template. These options only work if your command line environment has been correctly configured to use FSL (e.g. the $FSLDIR environment variable is set).

Perspectives

fsleyes --scene feat     files ...
fsleyes --scene melodic  files ...
fsleyes --scene default  files ...
fsleyes --scene ortho    files ...
fsleyes --scene ligthbox files ...
fsleyes  -s     feat     files ...
fsleyes  -s     melodic  files ...
fsleyes  -s     default  files ...
fsleyes  -s     ortho    files ...
fsleyes  -s     ligthbox files ...

The --scene option allows you to tell FSLeyes to start up with a specific perspective. If you have saved your own custom perspective, you can also load it, by name, using the --scene option.

Neurological orientation

fsleyes --neuroOrientation files ...
fsleyes  -no               files ...

By default, FSLeyes displays images in radiological orientation (i.e. with subject right to the left of the display, and subject left to the right). You can use the --neuroOrientation option to tell FSLeyes to use neurological orientation instead.

Force-load images

fsleyes --bigmem files ...
fsleyes  -b      files ...

By default, FSLeyes keeps large compressed NIFTI files on disk, only decompressing and loading data on-demand (i.e. when it needs to be viewed). While this reduces the amount of RAM needed to view such images, it also slows down the performance of changing volumes (e.g. via movie mode) and of viewing time series.

If you are using a computer with a large amount of RAM, and you don’t mind loading the entire image into memory, you can use the --bigmem argument to tell FSLeyes to do just that.

Run script

fsleyes --runscript script.py files ...
fsleyes  -r         script.py files ...

FSLeyes has a programming interface which you can use to programmatically set up complex scenes. The --runscript option allows you to execute a Python script when FSLeyes starts, which can load overlays and configure their display properties, and set up the FSLeyes interface. These scripts have access to the same environment that is available in the Python shell.

Examples

Volume overlays

Set up display/clipping/colourmap/interpolation on an image, and centre display at a specific voxel:

fsleyes -sortho -std1mm -vl 33 20 31 \
  zstat1.nii.gz -dr 2.5 3.5 -cr 2.5 3.5 -cm hot -in spline

Set up positive/negative colour map on a PE image:

fsleyes -std1mm pe1 -un -cm red-yellow \
  -nc blue-lightblue -dr 10 60 -in spline

Vector overlays

Display dtifit output as an RGB vector:

fsleyes dti_FA dti_V1 -ot rgbvector

Display bedpostx two-fibre output as line vectors:

fsleyes mean_f1samples dyads1 -ot linevector dyads2_thr0.05 -ot linevector

Display dtifit output as a tensor (not possible in a SSH/X11 session). You can specify the dtifit output directory:

fsleyes dtifit/dti_FA dtifit/

Or the 6-volume image containing the unique elements of the tensor matrix:

fsleyes dtifit/dti_FA dtifit/dti_tensor.nii.gz -ot tensor

Display spherical harmonic coefficients (not possible in a SSH/X11 session):

fsleyes asym_fods.nii.gz -ot sh

Melodic mode

Specify the path to your filtered_func_data.ica directory:

fsleyes -s melodic path/to/analysis.ica/filtered_func_data.ica

Or the path to your melodic_IC file:

fsleyes -s melodic path/to/analysis.ica/filtered_func_data.ica/melodic_IC

Use the -ad flag (--autoDisplay) to automatically set up colour maps:

fsleyes -ad -s melodic path/to/analysis.ica/filtered_func_data.ica/melodic_IC

Off-screen rendering

FSLeyes is capable of generating screenshots from the command line. This is useful, for example, if you need to generate a large number of PNG images for quality control purposes. Simply build a FSLeyes command line which generates the scene that you wish to view, and then tell FSLeyes to render the scene to a file.

You can access the FSLeyes off-screen renderer by passing the word render as the first argument to FSLeyes:

fsleyes render ...

FSLeyes should also work on systems which do not have a display (e.g. cluster nodes), via a tool such as Xvfb… Make sure you specify a 24-bit depth-buffer, for example:

xvfb-run -s "-screen 0 640x480x24" fsleyes render ...

You can access command line help in the same manner as described above:

fsleyes render --help
fsleyes render  -h
fsleyes render --fullhelp
fsleyes render  -fh

Using the off-screen renderer is nearly identical to using the standard FSLeyes command line interface, but you must also specify an output file:

fsleyes render [options] --outfile outfile file [displayOpts] ...
fsleyes render [options]  -of      outfile file [displayOpts] ...

You may also specify the size of the generated image, in pixels:

fsleyes render [options] --outfile outfile --size 800 600 file [displayOpts] ...
fsleyes render [options]  -of      outfile  -sz   800 600 file [displayOpts] ...

When using the off-screen renderer, the --scene option, normally used to specify a perspective, allows you to choose between generating a screenshot with an orthographic view or a lightbox view:

fsleyes render --scene ortho    --outfile outfile file [displayOpts] ...
fsleyes render --scene lightbox --outfile outfile file [displayOpts] ...