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:

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 with fsleyes-plugin- will automatically be detected by FSLeyes.
  • Plugin .py files, which contain view, control, and/or tool definitions, can be passed directly to the loadPlugin() function.
  • Plugin .py files which are present in the FSLeyes settings directory, or which are found in the FSLEYES_PLUGIN_PATH environment variable, will be loaded by the initialise() 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 with fsleyes-plugin- will automatically be detected by FSLeyes.
  • .py plugin files can be passed to the installPlugin() 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 the ControlMixin.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 the setup function) which begins with 'fsleyes-plugin-.
  • Expose your custom views, controls, and tools as entry points (the entry_points argument to the setup 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:

initialise Calls loadPlugin() on all plugin files in the FSLeyes settings directory, and found on the FSLEYES_PLUGIN_PATH environment variable.
loadPlugin Loads the given Python file as a FSLeyes plugin.
installPlugin Copies the given Python file into the FSLeyes settings directory, within a sub-directory called plugins.

The following functions can be used to access plugins:

listPlugins Returns a list containing the names of all installed FSLeyes plugins.
listViews Returns a dictionary of {name : ViewPanel} mappings containing the custom views provided by all installed FSLeyes plugins.
listControls Returns a dictionary of {name : ControlPanel} mappings containing the custom controls provided by all installed FSLeyes plugins.
listTools Returns a dictionary of {name : Action} mappings containing the custom tools provided by all installed FSLeyes plugins.
fsleyes.plugins.initialise()

Calls loadPlugin() on all plugin files in the FSLeyes settings directory, and found on the FSLEYES_PLUGIN_PATH environment variable.

fsleyes.plugins.listPlugins()

Returns a list containing the names of all installed FSLeyes plugins.

fsleyes.plugins._listEntryPoints(group)

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()

Returns a dictionary of {name : ViewPanel} mappings containing the custom views provided by all installed FSLeyes plugins.

fsleyes.plugins.listControls(viewType=None)

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 by ControlMixin.supportedViews.()).
fsleyes.plugins.listTools()

Returns a dictionary of {name : Action} mappings containing the custom tools provided by all installed FSLeyes plugins.

fsleyes.plugins._findEntryPoints(filename, modname)

Used by loadPlugin(). Imports the given Python file (setting the module name to modname), and finds the FSLeyes entry points (views, controls, or tools) that are defined within.

fsleyes.plugins.loadPlugin(filename)

Loads the given Python file as a FSLeyes plugin.

fsleyes.plugins.installPlugin(filename)

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 to loadPlugin().