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:
A view is a top level panel, such as an
OrthoPanel
,Scene3DPanel
, orTimeSeriesPanel
. 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
, orMelodicClassificationPanel
. 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 theApplyFlirtXfmAction
, theCropImageAction
, and theResampleAction
.
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 withfsleyes-plugin-
will automatically be detected by FSLeyes.Plugin
.py
files, which contain view, control, and/or tool definitions, can be passed directly to theloadPlugin()
function.Plugin
.py
files which are present in the FSLeyes settings directory, or which are found in theFSLEYES_PLUGIN_PATH
environment variable, will be loaded by theinitialise()
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 withfsleyes-plugin-
will automatically be detected by FSLeyes.
.py
plugin files can be passed to theinstallPlugin()
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.
Views must be sub-classes of the
ViewPanel
class.Controls must be sub-classes of the
ControlPanel
orControlToolBar
classes.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 thesetup
function) which begins withfsleyes-plugin-
.Expose your custom views, controls, and tools as entry points (the
entry_points
argument to thesetup
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:
Loads all plugins, including built-ins, plugin files in the FSLeyes settings directory, and those found on the |
|
Loads the given Python file as a FSLeyes plugin. |
|
Copies the given Python file into the FSLeyes settings directory, within a sub-directory called |
The following functions can be used to access plugins:
Returns a list containing the names of all installed FSLeyes plugins. |
|
Returns a dictionary of |
|
Returns a dictionary of |
|
Returns a dictionary of |
|
Looks up the FSLeyes view with the given class name. |
|
Looks up the FSLeyes control with the given class name. |
|
Looks up the FSLeyes tool with the given class name. |
|
Looks and returns up the title under which the given |
-
fsleyes.plugins.
class_defines_method
(cls, methname)[source]¶ Check to see whether
methname
is implemented oncls
, and not on a base-class.Action.ignoreTool()
,ControlMixin.ignoreControl()
, andControlMixin.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 thefsleyes.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 byControlMixin.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 byAction.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 tomodname
.
-
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. TheViewPanel
,ControlPanel
,ControlToolBar
andAction
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.
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 toloadPlugin()
.