FSLeyes plugins¶
FSLeyes 0.32.0 has a simple plugin architecture, allowing you to write and install custom views, controls, and tools.
Note
The FSLeyes plugin architecture is new to FSLeyes 0.26.0 - as of the release of this version there are no FSLeyes plugins in existence, so don’t bother searching for any just yet.
For users¶
FSLeyes plugins come in two forms:
- Python libraries (e.g. as hosted on PyPi - the Python Package Index)
- Standalone Python
.py
files
.py
plugin files¶
If you wish to use a FSLeyes plugin which comes as a .py
file, you can
simply use the File ⇒ Load plugin menu item. The panels and
tools that the plugin provides will then be available in the View,
Settings and Tools menus.
Plugin libraries¶
If you wish to use FSLeyes plugin which has been published on PyPi, you will need to install the plugin into the Python environment that FSLeyes is running in. You may wish to ask your local system adminsistrator or Python expert to help you with this.
For developers¶
Note
The FSLeyes API documentation can be found at http://users.fmrib.ox.ac.uk/~paulmc/fsleyes/apidoc/latest
For both types of plugin (Python libraries and .py
files),, FSLeyes uses
setuptools
entry points
to locate the items provided by plugin library/files.
Things plugins can provide¶
FSLeyes plugins can provide custom views, controls and tools:
- A view is a top level panel, such as an
OrthoPanel
,Scene3DPanel
, orTimeSeriesPanel
. Views provided by plugins are added to the top level Views menu.- A control is a secondary panel, or toolbar, which is embedded within a view, such as an
OverlayListPanel
,OrthoToolBar
, orMelodicClassificationPanel
. Controls provided by plugins are added to the Settings menu for each active view.- A tool is an
Action
which is associated with a menu item under the top-level Tools menu, such as theApplyFlirtXfmAction
and theResampleAction
.
Loading/installing FSLeyes plugins¶
FSLeyes plugins are loaded into a running FSLeyes as follows:
- Any Python libraries (e.g. installed from
PyPi
) which are present the environment that FSLeyes is running in, and which have a name beginning withfsleyes-plugin-
will automatically be detected by FSLeyes.- Plugin
.py
files, which contain view, control, and/or tool definitions, can be passed directly to theloadPlugin()
function.- Plugin
.py
files which are present in the FSLeyes settings directory, or which are found in theFSLEYES_PLUGIN_PATH
environment variable, will be loaded by theinitialise()
function.
A plugin can be installed permanently into FSLeyes as follows:
- Any Python libraries (e.g. installed from
PyPi
) which are present the environment that FSLeyes is running in, and which have a name beginning withfsleyes-plugin-
will automatically be detected by FSLeyes..py
plugin files can be passed to theinstallPlugin()
function. This file will be saved into the FSLeyes settings directory (e.g.~/.fsleyes/plugins/
).
Writing a FSLeyes plugin¶
Note
A minimal example of a FSLeyes plugin library can be found in
tests/testdata/fsleyes_plugin_example/
.
A FSLeyes plugin is a Python library, or a .py
file, which contains
definitions for custom views, controls, and tools.
- Views must be sub-classes of the
ViewPanel
class.- Controls must be sub-classes of the
ControlPanel
class.- Tools must be sub-classes of the
Action
class.
To write a .py
file which can be loaded as a FSLeyes plugin, simply
define your views, controls, and tools in the file. The file path can then
be passed to the loadPlugin()
or installPlugin()
function.
To release a FSLeyes plugin as a library, you need to organise your code as a Python library. Minimally, this requires the following:
- Arrange your
.py
file(s) into a Python package.- Write a
setup.py
file.- Give your library a name (the
name
argument to thesetup
function) which begins with'fsleyes-plugin-
.- Expose your custom views, controls, and tools as entry points (the
entry_points
argument to thesetup
function).
A minimal setup.py
file for a FSLeyes plugin might look like this:
import setuptools
setup(
# the name must begin with "fsleyes-plugin-"
name='fsleyes-plugin-my-cool-plugin',
# Views, controls, and tools must be exposed
# as entry points within groups called
# "fsleyes_views", "fsleyes_controls" and
# "fsleyes_tools" respectively.
entry_points={
'fsleyes_views' : [
'My cool view = myplugin:MyView'
]
'fsleyes_controls' : [
'My cool control = myplugin:MyControl'
]
'fsleyes_tools' : [
'My cool tool = myplugin:MyTool'
]
}
)
See the Python Packaging guide for more
details on writing a setup.py
file.