`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, or TimeSeriesPanel. 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, or MelodicClassificationPanel. 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 the ApplyFlirtXfmAction and the ResampleAction.

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()[source]¶: Calls loadPlugin() on all plugin files in the FSLeyes settings directory, and found on the FSLEYES_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 by ControlMixin.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 to modname), and finds the FSLeyes entry points (views, controls, or tools) that are defined within.

fsleyes.plugins.loadPlugin(filename)[source]¶: Loads the given Python file as a FSLeyes plugin.

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

fsleyes.plugins¶