Installing and Getting Started

PySurfer can be installed with pip. Note that the package name on PyPi is different from the library name that you import:

pip install pysurfer

If you already have PySurfer installed, you can also use pip to update it:

pip install -U --no-deps pysurfer

If you would like to save movies of time course data, it is necessary to include the optional dependency imageio with:

pip install pysurfer[save_movie]

If you’d like to install the development version, you have two options. You can install straight from github:

pip install https://api.github.com/repos/nipy/PySurfer/zipball/master

Or you can clone the git repository and install from your local source directory:

pip install .

Dependencies

PySurfer works on Python 2.7 and 3.6+. (Older Python 3 versions will probably work, but are not tested.)

To use PySurfer, you will need to have the following Python packages:

Some input/output functions also make use of the Python Imaging Library (PIL) and imageio, although they are not mandatory.

Getting started

Because PySurfer relies on some complicated dependencies (Mayavi, VTK and a GUI library), it can be more difficult to get started with than is the case with other Python libraries. Consider using the Anaconda distribution or Enthough Canopy environment. The difficulty on these platforms is generally getting Mayavi and VTK installed; see their installation instructions for information.

PySurfer generally works out of the box on Linux systems. Getting started on OSX may be trickier. We have had success using the Anaconda distribution with the additional step of setting the environment variables QT_API and ETS_TOOLKIT, e.g.:

export QT_API=pyqt
export ETS_TOOLKIT=qt4

The values you set should match the GUI library you are using.

You may wish to consult the Mayavi installation docs if you are having trouble getting things working.

If you are using PySurfer interactively in IPython/Jupyter, you should activate one of the GUI event loops so that the Mayavi window runs in a separate process. After starting IPython (either in the terminal, qtconsole, or notebook), you have to activate the correct GUI backend, which is probably qt:

%gui qt

This will allow you to have an open PySurfer window while still being able to execute code in the console/notebook.

It is also possible to embed the PySurfer visualization into a Jupyter notebook. This is achieved by leveraging Mayavi’s notebook integration:

from mayavi import mlab
mlab.init_notebook(backend='png')

The backend parameter can either be 'png' to render the visualization as a static PNG image, or 'x3d' to render it using X3D (still experimental).

If you are having trouble getting started using PySurfer, please describe the problem on the nipy mailing list.