fsleyes.plugins

This package provides access to installed and built-in 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.

  • Built-in plugins located within the fsleyes.plugins package.

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/, and a range of built-in plugins can be found in fsleyes/plugins/.

Warning

FSLeyes assumes that all views, controls, and tools have unique class names. So expect problems if, for example, you define your own FSLeyes control with the name OverlayListPanel.

A FSLeyes plugin is a Python library, or a .py file, which contains definitions for custom views, controls, and tools.

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

Loads all plugins, including built-ins, plugin files in the FSLeyes settings directory, and those 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.

lookupView

Looks up the FSLeyes view with the given class name.

lookupControl

Looks up the FSLeyes control with the given class name.

lookupTool

Looks up the FSLeyes tool with the given class name.

pluginTitle

Looks and returns up the title under which the given plugin is registered.

fsleyes.plugins.class_defines_method(cls, methname)[source]

Check to see whether methname is implemented on cls, and not on a base-class.

Action.ignoreTool(), ControlMixin.ignoreControl(), and ControlMixin.supportSubClasses() need to be implemented on the specific class - inherited base class implementations are not considered.

fsleyes.plugins.initialise()[source]

Loads all plugins, including built-ins, plugin files in the FSLeyes settings directory, and those found on the FSLEYES_PLUGIN_PATH environment variable.

fsleyes.plugins._pluginGroup(cls: Union[Type[fsleyes.views.viewpanel.ViewPanel], Type[fsleyes.controls.controlpanel.ControlPanel], Type[fsleyes.actions.base.Action]]) Optional[str][source]

Returns the type/group of the given plugin, one of 'views', 'controls', or 'tools'.

fsleyes.plugins._loadBuiltIns()[source]

Called by initialise(). Loads all bulit-in plugins, from sub-modules of the fsleyes.plugins directory.

fsleyes.plugins.listPlugins() List[str][source]

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

fsleyes.plugins._listEntryPoints(group: str) Dict[str, Union[Type[fsleyes.views.viewpanel.ViewPanel], Type[fsleyes.controls.controlpanel.ControlPanel], Type[fsleyes.actions.base.Action]]][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() Dict[str, Type[fsleyes.views.viewpanel.ViewPanel]][source]

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

fsleyes.plugins.listControls(viewType: Optional[Type[fsleyes.views.viewpanel.ViewPanel]] = None) Dict[str, Type[fsleyes.controls.controlpanel.ControlPanel]][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(viewType: Optional[Type[fsleyes.views.viewpanel.ViewPanel]] = None) Dict[str, Type[fsleyes.actions.base.Action]][source]

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

Parameters

viewType – Sub-class of ViewPanel - if provided, only tools which are compatible with this view type are returned (as determined by Action.supportedViews.()).

fsleyes.plugins._lookupPlugin(clsname: str, group: str) Optional[Union[Type[fsleyes.views.viewpanel.ViewPanel], Type[fsleyes.controls.controlpanel.ControlPanel], Type[fsleyes.actions.base.Action]]][source]

Looks up the FSLeyes plugin with the given class name.

fsleyes.plugins.lookupView(clsName: str) Type[fsleyes.views.viewpanel.ViewPanel][source]

Looks up the FSLeyes view with the given class name.

fsleyes.plugins.lookupControl(clsName: str) Type[fsleyes.controls.controlpanel.ControlPanel][source]

Looks up the FSLeyes control with the given class name.

fsleyes.plugins.lookupTool(clsName: str) Type[fsleyes.actions.base.Action][source]

Looks up the FSLeyes tool with the given class name.

fsleyes.plugins.pluginTitle(plugin: Union[Type[fsleyes.views.viewpanel.ViewPanel], Type[fsleyes.controls.controlpanel.ControlPanel], Type[fsleyes.actions.base.Action]]) Optional[str][source]

Looks and returns up the title under which the given plugin is registered.

fsleyes.plugins._importModule(filename: str, modname: str) module[source]

Used by loadPlugin(). Imports the given Python file, setting the module name to modname.

fsleyes.plugins._findEntryPoints(mod: module, ignoreBuiltins: bool) Dict[str, Dict[str, Union[Type[fsleyes.views.viewpanel.ViewPanel], Type[fsleyes.controls.controlpanel.ControlPanel], Type[fsleyes.actions.base.Action]]]][source]

Used by loadPlugin(). Finds the FSLeyes entry points (views, controls, or tools) that are defined within the given module.

Parameters
  • mod – The module to search

  • ignoreBuiltins – If True, all, views, controls and tools which are built into FSLeyes will be ignored. The ViewPanel, ControlPanel, ControlToolBar and Action base classes are always ignored.

fsleyes.plugins._registerEntryPoints(name: str, module: module, ignoreBuiltins: bool)[source]

Called by loadPlugin(). Finds and registers all FSLeyes entry points defined within the given module.

fsleyes.plugins.loadPlugin(filename: str)[source]

Loads the given Python file as a FSLeyes plugin.

fsleyes.plugins.installPlugin(filename: str)[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().