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