PySurfer on a headless linux server

pysurfer_setup.md

Get pysurfer running on a headless server

There have been some issues lately getting PySurfer set up and running. Here is how I recently got things set up on our server.

1. Install PySurfer

I am pretty sure that the anaconda build of mayavi is broken, but I have had success installing everything with pip (go figure). To demonstrate, I am going to install everything into a fresh conda enviornment.

conda create -n setup_pysurfer python=3.7 pip
. activate setup_pysurfer
pip install pysurfer pyqt5

Now, if you were following the pysurfer install documentation, you would set the QT_API and ETS_TOOLKIT environment variables. I have found that doing so is no longer helpful and is in fact detrimental. On my test system, I don't have either variable set and things seem to work fine. Look, I don't know. Computers are hard.

2. Activate a virtual display

If you're running things locally, you should now be done. The second step if you want to use a server has to do with using a virtual display.

Xvfb :10 -screen 0 1280x1024x24 -auth localhost
export DISPLAY=:10

Now I am able to run pysurfer in offscreen mode, which is useful for scripted visualization. e.g.

from surfer import Brain
b = Brain("fsaverage", "both", "pial", cortex=None, offscreen=True)
b.save_image("surface.png")

3. Set up interaction within a jupyter notebook

If you need interaction, that can be achieved within jupyterlab using mayavi's support for jupyter widgets.

First, install the jupyter-matplotlib extension here: https://github.com/matplotlib/jupyter-matplotlib

Then in a notebook, use the following two startup steps:

%matplotlib widget
from mayavi import mlab
mlab.init_notebook()

Now, create a pysurfer visualization as normal.

from surfer import Brain
b = Brain("fsaverage", "both", "pial", cortex=None)
b

The repl value for the Brain object will be an interactive window with the visualization. You can click on it and move the brain around like you would in a normal mayavi window. Depending on your connection, it may be a little laggy. But it should be functional.