Customising FSLeyes

This page contains details on customising various aspects of FSLeyes.

Note

If you are a Python developer, and want to develop custom plugins for FSLeyes, check out the page on plugins.

FSLeyes settings directory

FSLeyes stores all of its user-specific settings, and user-added colour maps, lookup tables, and layouts in a directory which, under macOS, will be located at:

$HOME/.fsleyes/

Under Linux, the FSLeyes directory will be found in either:

$XDG_CONFIG_HOME/fsleyes/

or:

$HOME/.config/fsleyes/

Most FSLeyes settings are stored in a Python pickle file called config.pkl. The FSLeyes ⇒ Clear FSLeyes settings menu option simply deletes this directory, which causes FSLeyes to forget all settings (and user-added colour maps, lookup tables, and layouts).

FSLeyes site configuration directory

FSLeyes can load colour maps, lookup tables, and layouts from a site-specific directory which can be specified via an environment variable called ${FSLEYES_SITE_CONFIG_DIR}. This may be useful if you are managing a multi-user installation and would like to make a set of custom colour maps, lookup tables, and/or layouts available to all users.

FSLeyes will automatically load colour maps, lookup tables and layouts that are respectively located in these directories:

${FSLEYES_SITE_CONFIG_DIR}/colourmaps/

${FSLEYES_SITE_CONFIG_DIR}/luts/

${FSLEYES_SITE_CONFIG_DIR}/layouts/

The expected file formats are outlined in the sections below.

Default command-line arguments

If there are some FSLeyes command-line options which you would always like to have applied, you can store them in a file called default_arguments.txt, located within the FSLeyes settings or site configuration directory. More information on this file can be found here.

Colour maps

For volume overlays, the overlay display panel has a Load colour map button which allows you to load new colour maps into FSLeyes. Clicking on this button will bring up a file selection dialog, allowing you to choose a file which contains a custom colour map.

FSLeyes can read in two types of colour map files, both described below:

RGB files, which simply contain a list of RGB values

VEST files, which are in the format used by FSLView.

When you apply a colour map to an image, FSLeyes will map the image display range to the colours in the colour map - the low display range value will map to the first colour in the colour map (i.e. the first colour in the file), and the high display range to the last colour (the last colour in the file). The Interpolate colour maps setting for volume allows you to define a continuous colour map by only specifying a few colours. For example, you could define the greyscale colour map with just two colours:

0.0 0.0 0.0
1.0 1.0 1.0

When the Interpolate colour maps setting is enabled, FSLeyes will interpolate between these colours.

Built-in colour maps

FSLeyes comes with a set of built-in colour maps - these files (formatted as RGB files) can be found at:

<env-dir>/lib/python<pyver>/site-packages/fsleyes/assets/colourmaps/

where <env-dir> is the location of the Python environment into which FSLeyes is installed, and <pyver> is the Python version (e.g. 3.11).

You can customise the display names and order of the built-in colour maps. Inside the colourmaps/ directory you will find a file called order.txt. This file defines the order in which colour maps are displayed in the FSLeyes interface, and also contains the display name for each colour map; it contains a list of colour map file names (without the .cmap suffix), and corresponding display names for each:

greyscale        Greyscale
red-yellow       Red-Yellow
blue-lightblue   Blue-Light blue
red              Red
...

Any colour maps which exist in the colourmaps/ directory, but are not listed in order.txt will still be available in the FSLeyes interface, but will be added after all of the colour maps listed in order.txt.

Warning

When creating your own .cmap file, make sure that there are no spaces in the file name. This also applies to .lut files (covered below).

User- and site-added colour maps

When you load a custom colour map through the overlay display panel, FSLeyes will ask you if you would like to install it permanently. If you choose to do so, FSLeyes will save the colour map (as a RGB file) under the FSLeyes settings directory (in a sub-directory called colourmaps/), renaming the file so it ends with .cmap. In the FSLeyes interface, all user-added colour maps will appear after the built-in colour maps.

You can also create your own order.txt file and store it alongside the user-added colour map files - it will be used in place of the built-in order.txt file.

FSLeyes will also automatically load any colour maps stored in ${FSLEYES_SITE_CONFIG_DIR}/colourmaps/.

RGB colour map files

RGB colour map files simply contain a list of RGB colours, one per line, with each colour specified by three space-separated floating point values in the range 0.0 - 1.0, with each value corresponding to the R, G, and B colour channels respectively. For example:

000000 0.260217 0.000000
000000 0.687239 1.000000
738949 0.000000 1.000000

VEST colour map files

VEST colour map files follow the colour map file format supported by FSLView. They contain a list of RGB colour tuples, with some additional metadata [*]. A VEST file looks something like this:

%!VEST-LUT
%%BeginInstance
<<
/SavedInstanceClassName /ClassLUT
/PseudoColorMinimum 0.00
/PseudoColorMaximum 1.00
/PseudoColorMinControl /Low
/PseudoColorMaxControl /High
/PseudoColormap [
<-color{0.000000,0.000000,0.000000}->
<-color{0.010000,0.010000,0.010000}->
.
.
.
<-color{1.000000,1.000000,1.000000}->
]
>>

%%EndInstance
%%EOF

Lookup tables

Label overlays are coloured according to a lookup table, which is distinct from a colour map. The lookup table panel allows you to create your own lookup tables, and load a lookup table from a file.

FSLeyes manages lookup tables for label overlays in a very similar manner as for colour maps. A FSLeyes lookup table file has a name that ends in .lut, and defines a lookup table which may be used to display images wherein each voxel has a discrete integer label. The lookup table file defines a name and a colour for each of the possible voxel values in such an image.

Each line in a .lut file must specify a label value, RGB colour, and associated name. The first column (where columns are space-separated) defines the label value, the second to fourth columns specify the RGB values, and all remaining columns give the label name. For example:

0.00000 0.93333 0.00000 Frontal Pole
0.62745 0.32157 0.17647 Insular Cortex
1.00000 0.85490 0.72549 Superior Frontal Gyrus

FSLeyes manages lookup table files in the same manner as described for colour maps. Built-in lookup table files can be located under the FSLeyes assets/luts/ directory. A file called order.txt allows you to customise the display names and order of built-in lookup tables. Custom lookup tables which are added via the lookup table panel are saved into the FSLeyes settings directory, in a sub-directory called luts. FSLeyes will also automatically load any lookup tables stored in ${FSLEYES_SITE_CONFIG_DIR}/luts/.

Layouts

FSLeyes allows you to save your view and control panel configuration as a _layout_. You can save and load your custom layouts from the Views ⇒ Layouts menu. FSLeyes layouts are stored as plain-text files in the FSLeyes settings directory, in a sub-directory called layouts/. FSLeyes will also read any layout files that are stored in

${FSLEYES_SITE_CONFIG_DIR}/layouts/.

FSLeyes layout files are stored as plain-text, and must end with a suffix of .txt. These files have the format:

<layout-title>
<layout-specification>

where:

<layout-title> is the display title for the layout (i.e. how it will appear in the Views ⇒ Layouts menu); and
<layout-specification> is a FSLeyes layout specification, as described in the fsleyes.layouts module documentation.

If you need to manually create a FSLeyes layout file, the easiest option is to follow these instructions:

Open FSLeyes, and set up your layout by hand (i.e. opening the views and controls that you wish to have included in your layout).
Start a Jupyter Notebook session via the File ⇒ Open notebooks menu option. Alternatively, you could start FSLeyes with the -nb or -nbb options - see the page on FSLeyes and Jupyter notebook for more details.

Enter the following code into a notebook or attached Python terminal:

from fsleyes import layouts
with open('my_layout.txt', 'wt') as f:
    f.write('My layout title\n')
    f.write(layouts.serialiseLayout(frame))

The file my_layout.txt will contain the FSLeyes layout specification - in order to use this file, you can copy it into the FSLeyes settings directory (within the layouts/ sub-directory) or ${FSLEYES_SITE_CONFIG_DIR}/layouts/.

Atlases

The atlas management panel allows you to load custom atlases into FSLeyes. FSL 6.0.4 and FSLeyes 1.15.0 supports atlases which are described by an xml file that adheres to the FSL atlas XML file format.

FSLeyes 1.15.0 understands two types of atlases [†]:

A label (or summary) atlas is a 3D NIFTI image which contains different discrete integer values for each region defined in the atlas.

A probabilistic atlas is a 4D NIFTI image, where each volume contains a probability map for one region in the atlas. This probabilistic image may also be accompanied by a corresponding label image.

Multiple versions of these images, at different resolutions, may exist (e.g. 1mm and 2mm versions of the same image may be present).

If you have an atlas image which you would like to use in FSLeyes, you must write an xml file which describes the atlas, contains paths to the atlas image(s), and contains a description of every region in the atlas.

The best way to create one of these files is to look at the atlas files that exist in $FSLDIR/data/atlases. Create a copy of one of these files - select one which describes an atlas that is similar to your own atlas (i.e. probabilistic or label) - and then modify the atlas name, file paths, and label descriptions to suit your atlas. Your xml atlas file should end up looking something like the following:

<atlas>

  <!-- The header defines the atlas name, type,
       and paths to the atlas image files. -->
  <header>

    <!-- Human-readable atlas name -->
    <name>Harvard-Oxford Cortical Structural Atlas</name>

    <!-- Abbreviated atlas name -->
    <shortname>HOCPA</shortname>

    <!-- Atlas type - "Probabilistic" or "Label" -->
    <type>Probabilistic</type>

    <!-- Paths (defined relative to the location
         of this XML file) to the atlas images.
         Multiple <images> elements may be present
         - one for each resolution in which the
         atlas is available. -->
    <images>

      <!-- If the atlas type is "Probabilistic", the
           <imagefile> must be a path to a 4D image
           which contains one volume per region.
           Otherwise, if the atlas type is "Label",
           the <imagefile> must be a path to 3D
           label image. -->
      <imagefile>/HarvardOxford/HarvardOxford-cort-prob-2mm</imagefile>

      <!-- If the atlas type is "Probabilistic", the
           <summaryimagefile> must be a path to a 3D
           label image which 'summarises' the
           probabilistic image. If the atlas type is
           "Label", the <summaryimagefile> is identical
           to the <imagefile>. There must be a
           <summaryimagefile> for every <imagefile>. -->
      <summaryimagefile>/HarvardOxford/HarvardOxford-cort-maxprob-thr25-2mm</summaryimagefile>
    </images>

    <!-- A 1mm version of the same atlas images. -->
    <images>
      <imagefile>/HarvardOxford/HarvardOxford-cort-prob-1mm</imagefile>
      <summaryimagefile>/HarvardOxford/HarvardOxford-cort-maxprob-thr25-1mm</summaryimagefile>
    </images>
  </header>

  <!-- The <data> element contains descriptions
       of all regions in the atlas. -->
  <data>

    <!-- Every region in the atlas has a <label> element which defines:

         - The "index". For probabilistic atlases, this is the index
           of the corresponding volume in the 4D image file. For
           label images, the index is the value of voxels which
           are in the corresponding region. For 3D summary images of
           probabilistic atlases, add 1 to the index to get the
           label value.

         - The "x", "y", and "z" coordinates of a pre-
           calculated "centre-of-gravity" for this region.
           These are specified as voxel coordinates,
           relative to the *first* image in the <images>
           list, above.

         - The name of the region. -->

    <label index="0" x="48" y="94" z="35">Frontal Pole</label>
    <label index="1" x="25" y="70" z="32">Insular Cortex</label>
    <label index="2" x="33" y="73" z="63">Superior Frontal Gyrus</label>

    <!-- ... -->

    <label index="45" x="74" y="53" z="40">Planum Temporale</label>
    <label index="46" x="44" y="21" z="42">Supracalcarine Cortex</label>
    <label index="47" x="37" y="15" z="34">Occipital Pole</label>
  </data>
</atlas>