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 thefile
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
Lightbox view¶
Set Z axis, number of rows, and number of columns:
fsleyes -slightbox -zx Z -nr 10 -nc 10 -std1mm
Set slice spacing (mm):
fsleyes -slightbox -zx Z -ss 10 -std1mm
Set slice range (mm, starting from 0):
fsleyes -slightbox -zx Z -ss 5 -zr 0 91 -std1mm
fsleyes -slightbox -zx Z -ss 5 -zr 91 182 -std1mm
fsleyes -slightbox -zx Z -ss 5 -zr 45 136 -std1mm
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.
FSLeyes should also work on systems which do not have a display (e.g. cluster nodes), via a tool such as Xvfb..
You can access the FSLeyes off-screen renderer by passing the word render
as the first argument to FSLeyes:
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] ...