Fsleyes Atlas

[Kimberly Ballas]

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

If there are some FSLeyes command-line options which you would always liketo have applied, you can store them in a file calleddefault_arguments.txt, located within the FSLeyes settings or siteconfiguration directory. More information on this file can be foundhere.

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

When you apply a colour map to an image, FSLeyes will map the image displayrange to the colours in the colour map - the low display range value will mapto the first colour in the colour map (i.e. the first colour in the file), andthe high display range to the last colour (the last colour in the file). TheInterpolate colour maps setting for volume allowsyou to define a continuous colour map by only specifying a few colours. Forexample, you could define the greyscale colour map with just two colours:

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

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

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

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

FSLeyes manages lookup tables for label overlays in a very similar manner asfor 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 eachvoxel has a discrete integer label. The lookup table file defines a name anda 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, andassociated name. The first column (where columns are space-separated) definesthe label value, the second to fourth columns specify the RGB values, and allremaining columns give the label name. For example:

FSLeyes manages lookup table files in the same manner as described forcolour maps. Built-in lookup table files canbe located under the FSLeyes assets/luts/ directory. A file calledorder.txt allows you to customise the display names and order of built-inlookup tables. Custom lookup tables which are added via the lookuptable panel are saved into theFSLeyes settings directory, ina sub-directory called luts. FSLeyes will also automatically load anylookup tables stored in $FSLEYES_SITE_CONFIG_DIR/luts/.

If you have an atlas image which you would like to use in FSLeyes, you mustwrite an xml file which describes the atlas, contains paths to the atlasimage(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 thatexist 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 endup looking something like the following:

FSL comes bundled with a collection of NIFTI templates and atlases. A variety of probabilisticand discrete atlases are included, comprising cortical, sub-cortical, andregional parcellations. It is also possible to add your own atlases toFSL.

All of the atlases included with FSL 6.0.4 have beenaligned to the MNI152 standard template. This means that anyimages which you wish to query using these atlases must be alsoregistered to MNI152 space.

The list on the left allows you to select the atlases that you wish to query -click the check boxes to the left of an atlas to toggle information on and offfor that atlas. The Harvard-Oxford cortical and sub-cortical structuralatlases are both selected by default.

The panel on the right displays information about the current display locationfrom each selected atlas. For probabilistic atlases, the region(s)corresponding to the display location are listed, along with theirprobabilities. For discrete atlases, the region at the current location islisted.

Some of the atlases included in FSL (e.g. the Talairach) containa large number of regions. Generating and displaying the regionlist can therefore take some time, so please be patient the firsttime that you select an atlas!

When you select an atlas in this list, all of the regions in that atlas arelisted in the area to the right. Again, the checkbox to the left of eachregion name toggles an overlay for that region on and off (either avolume or mask overlay,depending on whether the atlas is probabilstic or discrete). The + button nextto each region moves the display location to the (approximate) centre of thatregion.

When you type some characters into the search field, the region list will befiltered, so that only those regions with a name that contains the charactersyou entered are displayed. The atlas list on the left will also be updated sothat any atlases which contain regions matching the search term arehighlighted in bold.

The atlas management tab displays a list of all loaded atlases, and allows youto add and remove atlases from FSLeyes. The name of each atlas is shown in thelist, but you can click and hold on an atlas to display the path to the atlasspecification file.

You can load a new atlas into FSLeyes by clicking the + button, and selectingthe FSL atlas specification file which describes the atlas - see the page oncustomising FSLeyes for details. You can remove an atlasfrom FSLeyes by selecting it in the list and clicking the - button [*].

FSLeyes (pronounced fossilise) is the new FSL image viewer for 3Dand 4D data (replacing FSLView). It does not perform any processing oranalysis of images - that is done by separate tools. FSLeyes has lots offeatures to visualise data and results in a variety of useful ways, and someof these are shown in this introductory practical. You will also be usingFSLeyes throughout the course, so it is useful to get a feel for it, but manymore useful features will be included in the course.

This practical provides a quick introduction to some FSLeyes features thatyou will be likely to use quite often. For a full overview of what FSLeyes cando, take a look at theFSLeyes user guide.Getting startedAssuming you have downloaded the data and it is in the correct directory,please open a command terminal and type:

The & means that the program you asked for(fsleyes) runs in the background in the terminal (or shell), andyou can keep typing and running other commands while fsleyes continues torun. If you had not made fsleyes run in the background (i.e., ifyou had just typed fsleyes without the & at theend) then you would not be able to get anything to run in that terminal untilyou killed fsleyes (although you could still type things, butthey would not run).

FSLeyes by defaults opens in the ortho view mode. If you addimage filenames on the command line (after typing fsleyes) itwill load them all automatically, and you can also add many options from thecommand line. FSLeyes assumes that all of the images which you load share asingle coordinate system, but images do not have to have the same field of view, number of voxels, or timepoints.

In FSLeyes, load in the image example_func.nii.gz, by pressingFile > Add overlay from file and selecting the image.Hold the mouse button down in one of the ortho canvases and move it around- see how various things update as you do so:

The display toolbar allows you to adjust the display properties of the currently selected image. Play around with the controls and note how the image display changes (but leave the "overlay type" as "3D/4D volume").

If FSLeyes does not have enough room to display a toolbar in full, it willdisplay left and right arrows (,) on each side of the toolbar - youcan click on these arrows to navigate back and forth through the toolbar.

Open a lightbox view using View > Lightbox View. Ifyou drag the mouse around in the viewer you can see that the cursor positionis linked in the two views of the data (the ortho and the lightboxviews). This is particularly useful when you have several images loaded in atthe same time (you can view each in a separate view window and move around allof them simultaneously).

You can "unlink" the cursor position between the two views (it is linked by default). Go into one of the views, e.g., the lightbox view, and press the spanner button (). This will open the lightbox view settings panel. Turn off the Link Location option, and close the view settings panel.. You will now find that this view (the lightbox view) is no longer linked to the "global" cursor position, and you can move the cursor independently (in this view) from where it is in the other views.

3a8082e126