fsleyes.plugins

This package provides access to installed and built-in FSLeyes plugins.

FSLeyes uses a simple plugin architecture for loading custom views, controls, tools, and layouts. 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 entry points to locate the items provided by plugin library/files.

Things plugins can provide

FSLeyes plugins can provide custom views, controls, tools, and layouts:

• 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, the CropImageAction, and the ResampleAction.

• A layout is a string which specifies the layout of the FSLeyes frame, comprising one or more view panels, and a set of control panels for each view. Refer to the fsleyes.layouts module for more details.

FSLeyes plugin sources

FSLeyes plugins can be loaded from the following locations:

• Built-in plugins from the fsleyes.plugins package.

• Single-file plugins that have been loaded/installed by the user.

• Plugins from third-party libraries that are installed into the running Python environment.

The default behaviour, when FSLeyes starts up, is to only expose plugins from the first two locations - plugins from third party libraries are hidden by default. However, third-party plugins are automatically made available when a layout from the same library is loaded.

Third-party plugins can also be made visible by default if you start FSLeyes with the --showAllPlugins command-line option.

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 provide any FSLeyes entry points, will automatically be detected by FSLeyes.

• Plugin .py files, which contain view, control, tool, and/or layout 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 provide any FSLeyes entry points, 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 fsleyes/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, tools, and layouts have unique names. So expect problems if, for example, you define your own FSLeyes control with a name that is already used by a built-in control, e.g. OverlayListPanel.

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

• Views must be sub-classes of the ViewPanel class.

• Controls must be sub-classes of the ControlPanel or ControlToolBar classes.

• Tools must be sub-classes of the Action class.

• Layouts must be strings or tuples. For single-file plugins, layout variables must have a name that begins with FSLEYES_LAYOUT_. If a layout is a string, it is given a name based on the name of the variable. If a layout is a tuple, the first value in the tuple is used as the name, and the second value is assumed to be the layout string.

To write a .py file which can be loaded as a FSLeyes plugin, simply define your views, controls, tools, and layouts 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.

• Expose your custom views, controls, tools, and layouts as entry points.

A minimal pyproject.toml file for a FSLeyes plugin might look like this:

[build-system]
requires      = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "my-cool-fsleyes-plugin"

# Views, controls, tools, and layouts
# must be exposed as entry points
# within groups called "fsleyes_views",
# "fsleyes_controls", "fsleyes_tools"
# and "fsleyes_layouts" respectively.

[project.entry-points.fsleyes_views]
"My cool view" = "myplugin:MyView"

[project.entry-points.fsleyes_controls]
"My cool control" = "myplugin:MyControl"

[project.entry-points.fsleyes_tools]
"My cool tool" = "myplugin.MyTool"

[project.entry-points.fsleyes_layouts]
"My cool layout" = "myplugin.MyLayout"

See the Python Packaging guide for more details on packaging Python libraries.

Module contents

As plugins provided by installed libraries are automatically taken care of by importlib, most of the logic in this module is for managing single-file FSLeyes plugins. When a plugin file is loaded, a custom importlib.metadata.Distribution instance is created and registered using a custom importlib.abvc.MetaPathFinder instance. The plugin file is scanned to identify the plugins that it provides, and these are exposed as entry points of the distribution.

At present there are few examples available on how to accomplish the above, but there are enough clues in the importlib.metadata documentation at:

https://docs.python.org/3/library/importlib.metadata.html#extending-the-search-algorithm.

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:

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.
listLayouts	Returns a dictionary of {name : str} mappings containing the custom layouts provided by all installed FSLeyes plugins.
lookupControl	Looks up the FSLeyes control with the given class name.
lookupTool	Looks up the FSLeyes tool with the given class name.
layoutModule	Return the module that a given layout is defined iwthin.
pluginTitle	Looks and returns up the title under which the given plugin is registered.

fsleyes.plugins.SHOW_THIRD_PARTY_PLUGINS = {}

Global toggle which controls whether plugins provided by installed third-party libraries are exposed by the listViews(), listControls(), and listTools() functions. Layouts provided by plugins are always visible.

This field may either be a set containing the names of specific third-party plugins to show, or a boolean which will toggle all third party plugins on or off.

fsleyes.plugins.showThirdPartyPlugin(modname: str)

Show plugins from the given third party module.

fsleyes.plugins.shouldShowThirdPartyPlugin(modname: str) → bool

Return True if the given plugin should be visible, False otherwise.

class fsleyes.plugins.FSLeyesPlugin(*args, **kwargs)

Bases: Distribution

Custom importlib.metadata.Distribution used to represent FSLeyes plugins that are loaded from a single file.

A FSLeyesPlugin is created for each single-file FSLeyes plugin that is registered with the FSLeyesPluginFinder.add_plugin() method.

__init__(module: ModuleType, modname: str)

Create a FSLeyesPlugin from a single-file plugin file that has already been loaded as a module.

Parameters:

• module – The loaded module

• modname – The module name

property version: str

Return the ‘Version’ metadata for the distribution package.

property name: str

Return the ‘Name’ metadata for the distribution package.

read_text(filename)

Attempt to load metadata file given by the name.

Parameters:

filename – The name of the file in the distribution info.

Returns:

The text if found, otherwise None.

locate_file(path)

Given a path to a file in this distribution, return a path to it.

property entry_points: Sequence[EntryPoint]

Return a sequence of EntryPoint objects provided by the plugin. The FSLeyesPlugin.find_entry_points() function is used to scan the module for entry points.

static find_entry_points(mod: ModuleType) → Dict[str, Dict[str, Type[ViewPanel] | Type[ControlMixin] | Type[ControlToolBar] | Type[Action] | str | tuple]]

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

Parameters:

mod – The module to search

Returns:

A dictionary

__module__ = 'fsleyes.plugins'

class fsleyes.plugins.FSLeyesPluginFinder

Bases: MetaPathFinder

Custom MetaPathFinder for single-file FSLeyes plugins.

static instance() → FSLeyesPluginFinder

Return a singleton FSLeyesPluginFinder instance.

__init__()

Don’t create a FSLeyesPluginFinder. Instead, access the singleton instance via the instance() method.

add_plugin(module: ModuleType, modname: str)

Register a FSLeyes plugin module.

Parameters:

• module – The loaded module

• modname – The module name

find_distributions(context=None)

Returns all registered FSLeyesPlugin distributions.

find_spec(fullname, path, target=None)

May be called by importlib when attempting to import a module. Returns None.

__abstractmethods__ = frozenset({})

__module__ = 'fsleyes.plugins'

_abc_impl = <_abc._abc_data object>

fsleyes.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.

fsleyes.plugins._pluginType(item) → str | bool

Return the plugin type of the given object - one of 'view', 'control', 'tool' or 'layout'.

fsleyes.plugins._pluginGroup(plg: Type[ViewPanel] | Type[ControlMixin] | Type[ControlToolBar] | Type[Action] | str | tuple) → str | None

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

fsleyes.plugins._loadBuiltIns()

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

fsleyes.plugins._listEntryPoints(group: str, showAll: bool = False, load: bool = True) → Dict[str, Type[ViewPanel] | Type[ControlMixin] | Type[ControlToolBar] | Type[Action] | str | tuple]

Returns a dictionary containing {name : object} entry points for the given entry point group.

https://docs.python.org/3/library/importlib.metadata.html#entry-points

Parameters:

• group – One of 'fsleyes_views', 'fsleyes_controls, 'fsleyes_tools', or 'fsleyes_layouts'.

• showAll – If True, all plugins, including from installed third-party packages will be included. Otherwise (the default) plugins from third-party packages which are not in SHOW_THIRD_PARTY_PLUGINS will be omitted. :arg load:

• load – If True (the default), the returned dictionary will contain loaded entry point objects. If False, the entry points will not be loaded, and the returned dictionary will instead contain importlib.metadata.EntryPoint objects.

fsleyes.plugins.listViews() → Dict[str, Type[ViewPanel]]

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

fsleyes.plugins.listControls(viewType: Type[ViewPanel] | None = None) → Dict[str, Type[ControlMixin] | Type[ControlToolBar]]

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: Type[ViewPanel] | None = None) → Dict[str, Type[Action]]

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.listLayouts() → Dict[str, str | tuple]

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

fsleyes.plugins._lookupPlugin(plgname: str, group: str) → Type[ViewPanel] | Type[ControlMixin] | Type[ControlToolBar] | Type[Action] | str | tuple | None

Looks up the FSLeyes plugin with the given name.

fsleyes.plugins.lookupControl(clsName: str) → Type[ControlMixin] | Type[ControlToolBar]

Looks up the FSLeyes control with the given class name.

fsleyes.plugins.lookupTool(clsName: str) → Type[Action]

Looks up the FSLeyes tool with the given class name.

fsleyes.plugins.layoutModule(name: str) → str

Return the module that a given layout is defined iwthin.

fsleyes.plugins.pluginTitle(plugin: Type[ViewPanel] | Type[ControlMixin] | Type[ControlToolBar] | Type[Action] | str | tuple) → str | None

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

fsleyes.plugins.loadPlugin(filename: str)

Loads the given Python file as a FSLeyes plugin.

fsleyes.plugins.installPlugin(filename: str)

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