Troubleshooting

This page describes some problems which you may encounter when using FSLeyes. If you are having a problem which is not listed here, try searching the FSL mailing list archives to see if somebody else has had the same problem. Failing that, send an email to the mailing list - we will try our best to help!

$FSLDIR is not set

When you first start FSLeyes, you may be presented with the following warning:

_images/troubleshooting_fsldir_not_set.png

This means that FSLeyes has been unable to locate the directory in which FSL is installed, and may mean that your FSL environment is not correctly configured. If you see this warning, you can tell FSLeyes where FSL is located by clicking on the Locate $FSLDIR button, and selecting the FSL installation directory (typically /usr/local/fsl/). Alternately, you can click Skip to ignore the warning- you can still use FSLeyes, however some features (e.g. atlases) will not be available.

FSLeyes has saved the wrong $FSLDIR

FSLeyes keeps track of the location that it thinks FSL is installed in. If you move or re-install FSL, or have multiple versions of FSL installed, and need to update FSLeyes, you can force FSLeyes to forget its settings via the FSLeyesClear FSLeyes settings menu option.

Images are not overlaid on each other correctly

Sometimes when you load some images into FSLeyes, they will be displayed incorrectly - either badly oriented, or mis-aligned:

_images/troubleshooting_misaligned.png _images/troubleshooting_bad_orientation.png

This can mean one of two things:

  1. The images are not aligned, and they are not supposed to be (the top example above). For example, they are from different subjects, modalities, or studies.

  2. The images should be aligned, but there is an error in the orientation information stored in the NIFTI header, for one (or several) of the images (the bottom example above).

The first scenario is not a problem - you can safely load and view data from different subjects and studies into FSLeyes, but be aware that there will be no anatomical correspondence, across the different images, in the world or voxel coordinates.

The second scenario is more serious, as it means that the orientation information for one or more images has somehow been corrupted. The overlay information panel is useful here, as it allows you to check the orientation information of each images, including the sform and qform codes and transformation matrices, and the voxel and world coordinate orientations.

Once you identify the image(s) which is/are causing the problem, you need to re-generate the image (if it was generated as part of a processing pipeline), or correct the orientation information in the NIFTI file header. In the future, you will be able to do this from within FSLeyes, but as of version 0.32.1, you must do this with an external program such as fslcpgeom or fsledithd.

My image is tilted/oblique! How do I make it oriented/rectangular?

Open the view settings panel (the spanner_icon button) and set the Display space to the image which you want oriented.

There are weird striping artifacts in my image!

_images/troubleshooting_striping.png

Those are slice boundaries - your image is being displayed obliquely to the display, and FSLeyes is using nearest-neighbour interpolation to draw the image to the screen. Change the interpolation (in the overlay display panel) to linear or spline.

Movie mode gives me a black/flickering screen

Try changing the Synchronise movie updates setting, in the view settings panel (the spanner_icon button).

Line vectors/tensors/fibre orientation distributions are left/right flipped

Occasionally you might load a vector image (or tensor or SH image) into FSLeyes, only to find that the orientation of the vectors is incorrectly inverted along the left-right axis. This can occur because different software tools may output vector image data in different ways, depending on the image orientation.

_images/troubleshooting_line_vector_orientation.png

For images which are stored radiologically (with the X axis in the voxel coordinate system increasing from right to left, the top image), FSL tools such as dtifit will generate vectors which are oriented according to the voxel coordinate system.

However, for neurologically stored images (X axis increasing from left to right), FSL tools generate vectors which are radiologically oriented (the middle image), and thus are inverted with respect to the X axis in the voxel coordinate system. Therefore, in order to correctly display vectors from such an image, we must flip each vector about the X axis (the bottom image).

Vector overlays have a L/R orientation flip setting, which allows you to flip vectors (or tensor ellipsoids, or FODs) along the left/right axis. FSLeyes will automatically adjust this setting based on the orientation of the image data, and will correctly display all vector images that have been generated by FSL tools.

However, if you are working with vector (or tensor, or SH) data generated by a different tool, you may need to flip the orientation, via the L/R orientation flip setting in the overlay display panel, in order to display the data correctly.

macOS - Keyboard navigation doesn’t work in the IC classification panel

Under macOS, you may have focus-related issues while navigating around the IC classification panel with the keyboard.

If this is happening to you, you may need to enable Full keyboard access for the MELODIC classification panel to work with keyboard navigation/focus. This setting can be changed through System PreferencesKeyboardShortcuts, and changing Full Keyboard Access to All controls.

macOS - FSLeyes breaks after updating

Under macOS, you may encounter the following error after overwriting an old version of FSLeyes with a new version:

_images/troubleshooting_fsleyes_update_error.png

This is happening because macOS is caching the old version of the FSLeyes application specification file (found in FSLeyes.app/Contents/Info.plist), and ignoring the new version. You can fix this problem by temporarily moving this file to a different location, and then moving it back again, for example:

cd /Path/to/FSLeyes.app
mv Contents/Info.plist ./Info.plist.backup
# This command will fail
./Contents/MacOS/fsleyes
mv ./Info.plist.backup Contents/Info.plist
# FSLeyes should now work
./Contents/MacOS/fsleyes

If, after the above, the problem is still occurring, it may be that you are using a symbolic link to call FSLeyes (e.g. a link called $FSLDIR/bin/fsleyes which points to /Applications/FSLeyes.app/Contents/MacOS/fsleyes. If this is the case, try replacing the symlink with a wrapper script that contains the following:

#!/bin/bash
/path/to/FSLeyes.app/Contents/MacOS/fsleyes $@

macOS - I can’t start FSLeyes from IPython/Jupyter Notebook

If you are using macOS, and you are using FSLeyes from a conda environment, you may encounter this error when trying to use FSLeyes:

This program needs access to the screen. Please run with a Framework
build of python, and only when you are logged in on the main display
of your Mac.

This is due to a problem with the way that conda interacts with macOS. If you are using python/ipython, you can work around the problem by using pythonw instead of python. If you are using ipython, you can run it like so:

pythonw $(which ipython)

If you are using a Jupyter Notebook, things are a little bit more complicated. You will need to define a custom Jupyter kernel specification file, which uses pythonw. The easiest way to do this is to create a copy of the default kernel specification, e.g:

cp -r [conda environment location]/share/jupyter/python3 \
      ~/Library/Jupyter/kernels/python3w

Then open ~/Library/Jupyter/kernels/python3w/kernel.json in a text editor, and change the first element in the argv list to pythonw instead of python. For example, if the contents of kernel.json look like this:

{
 "argv": [
  "/Users/paulmc/miniconda3/envs/fsleyes/bin/python",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "Python 3",
 "language": "python"
}

Change it to this:

{
 "argv": [
  "/Users/paulmc/miniconda3/envs/fsleyes/bin/pythonw",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "Python 3 (GUI)",
 "language": "python"
}

The next time you start a new Jupyter notebook, select the Python 3 (GUI) kernel.

Linux - FSLeyes does not start

glutInit

Under linux, you might be presented with the following error when you try to start FSLeyes:

WARNING          __init__.py  596: create          - GLContext callback function raised NullFunctionError: Attempt to call an undefined function glutInit, check for bool(glutInit) before calling
Traceback (most recent call last):
  File "fsleyes/gl/__init__.py", line 590, in create
  File "fsleyes/main.py", line 371, in realCallback
  File "fsleyes/gl/__init__.py", line 377, in bootstrap
  File "site-packages/OpenGL/GLUT/special.py", line 333, in glutInit
  File "site-packages/OpenGL/platform/baseplatform.py", line 407, in __call__
NullFunctionError: Attempt to call an undefined function glutInit, check for bool(glutInit) before calling

This error is occurring because FSLeyes depends on some features provided by [GLUT](https://www.opengl.org/resources/libraries/glut/), which is not necessarily present on linux systems. You can avoid this error simply by installing [FreeGLUT](http://freeglut.sourceforge.net/), which should be available through your package manager (e.g. yum install freeglut under CentOS, or apt-get install freeglut3 under Ubuntu).

libxcb

Another possible error which you may encounter when running on older Linux platforms:

Traceback (most recent call last):
  File "fsleyes/__main__.py", line 4, in <module>
  File "fsleyes/main.py", line 33, in <module>
  File "site-packages/wx-3.0-gtk2/wx/__init__.py", line 45, in <module>
  File "site-packages/wx-3.0-gtk2/wx/_core.py", line 4, in <module>
ImportError: libX11.so.6: undefined symbol: xcb_wait_for_reply64
Failed to execute script __main__

This error is occurring because FSLeyes requires a more up-to-date version of the libxcb library. You can solve this problem simply by upgrading libxcb. Under CentOS, simply run yum update libxcb (with administrator privileges).

GLib version too old (micro mismatch)

If you see an error that looks like this:

(fsleyes:15552): Gtk-WARNING **: GModule (/usr/lib64/gtk-2.0/2.10.0/immodules/im-ibus.so) initialization check failed: GLib version too old (micro mismatch)

Then you are probably using a version of FSLeyes which has been built for a different operating system (e.g. using a version of FSLeyes that has been built for CentOS6 on a CentOS7 machine). Head to the FSLeyes home page and follow the instructions to download the correct version for your platform.

Running FSLeyes remotely

FSLeyes is capable of running on remote servers, over SSH/X11 connections, or from within VNC or other remote desktop tools. However, you may need to configure your environment before FSLeyes will work correctly.

OpenGL 1.4 or newer is required (detected version: 1.2)

FSLeyes requires OpenGL 1.4 or newer. In some remote desktop environments, the OpenGL version may be restricted. If you receive this error when trying to start FSLeyes, try the following:

unset LIBGL_ALWAYS_INDIRECT
fsleyes

If you are running FSLeyes within a VNC session, you may need to force software-based rendering:

export LIBGL_ALWAYS_SOFTWARE=1
fsleyes

Options are missing!

Sometimes, in a remote desktop environment, FSLeyes is not able to provide all of the features that it can when running locally. When you run FSLeyes over X11, the following options will not be available:

XQuartz - FSLeyes doesn’t start, and just shows an error

Under XQuartz 2.7.9 and newer, FSLeyes may not start, and you may see the following error:

Gdk-ERROR **: The program 'fsleyes' received an X Window System error.
This probably reflects a bug in the program.
The error was 'BadValue (integer parameter out of range for operation)'.
  (Details: serial 695 error_code 2 request_code 149 minor_code 24)
  (Note to programmers: normally, X errors are reported asynchronously;
   that is, you will receive the error a while after causing it.
   To debug your program, run it with the --sync command line
   option to change this behavior. You can then get a meaningful
   backtrace from your debugger if you break on the gdk_x_error() function.)
aborting...

This is caused by a configuration issue with XQuartz - you will be unable to run any OpenGL application, not just FSLeyes. Fortunately, there is a solution: if you are using XQuartz 2.7.10 or newer, run this command (locally, not within the SSH session):

defaults write org.macosforge.xquartz.X11 enable_iglx -bool true

If you are using XQuartz 2.7.9, and you cannot upgrade to 2.7.10 or newer, you will need to edit /usr/X11R6/bin/startx (you will probably need administrator privileges). There is a section in this script, around line 100, which configures a variable called defaultserverargs. Immediately after this section, add the following line:

defaultserverargs="$defaultserverargs +iglx"

After making this change, restart XQuartz - FSLeyes should now start.

XQuartz - keyboard shortcuts don’t work

If you are using XQuartz, you may need to select the Option keys send Alt_L and Alt_R option in the XQuartz Preferences dialog before keyboard shortcuts will work in FSLeyes.