fsleyes.plugins
¶
This module provides access to installed FSLeyes plugins.
FSLeyes uses a simple plugin architecture for loading custom views, controls,
and tools. Plugins can be installed from Python libraries (e.g. as hosted on
PyPi), or installed directly from a .py
file.
In both cases, 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. If your custom control is designed to only work with a specific view, you should override theControlMixin.supportedViews
static method to return the views that your control supports.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 withfsleyes-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.
Module contents¶
The following functions can be used to load/install new plugins:
Calls |
|
Loads the given Python file as a FSLeyes plugin. |
|
Copies the given Python file into the FSLeyes settings directory, within a sub-directory called |
The following functions can be used to access plugins:
Returns a list containing the names of all installed FSLeyes plugins. |
|
Returns a dictionary of |
|
Returns a dictionary of |
|
Returns a dictionary of |
- fsleyes.plugins.initialise()[source]¶
Calls
loadPlugin()
on all plugin files in the FSLeyes settings directory, and found on theFSLEYES_PLUGIN_PATH
environment variable.
- fsleyes.plugins.listPlugins()[source]¶
Returns a list containing the names of all installed FSLeyes plugins.
- fsleyes.plugins._listEntryPoints(group)[source]¶
Returns a dictionary containing
{name : type}
entry points for the given entry point group.https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
- fsleyes.plugins.listViews()[source]¶
Returns a dictionary of
{name : ViewPanel}
mappings containing the custom views provided by all installed FSLeyes plugins.
- fsleyes.plugins.listControls(viewType=None)[source]¶
Returns a dictionary of
{name : ControlPanel}
mappings containing the custom controls provided by all installed FSLeyes plugins.- Parameters
viewType – Sub-class of
ViewPanel
- if provided, only controls which are compatible with this view type are returned (as determined byControlMixin.supportedViews.()
).
- fsleyes.plugins.listTools()[source]¶
Returns a dictionary of
{name : Action}
mappings containing the custom tools provided by all installed FSLeyes plugins.
- fsleyes.plugins._findEntryPoints(filename, modname)[source]¶
Used by
loadPlugin()
. Imports the given Python file (setting the module name tomodname
), and finds the FSLeyes entry points (views, controls, or tools) that are defined within.
- fsleyes.plugins.installPlugin(filename)[source]¶
Copies the given Python file into the FSLeyes settings directory, within a sub-directory called
plugins
. After the file has been copied, the path to the copy is passed toloadPlugin()
.