Plugins#
DataLab supports a robust plugin architecture, allowing users to extend the applicationâs features without modifying its core. Plugins can introduce new processing tools, data import/export formats, or custom GUI elements â all seamlessly integrated into the platform.
What is a plugin?#
A plugin is a Python module that is automatically loaded by DataLab at startup. It can define new features or modify existing ones.
To be recognized as a plugin, the file must:
Be a Python module whose name starts with
datalab_(e.g.datalab_myplugin.py),Contain a class that inherits from
datalab.plugins.PluginBase,Include a class attribute named
PLUGIN_INFO, which must be an instance ofdatalab.plugins.PluginInfo.
This PLUGIN_INFO object is used by DataLab to retrieve metadata such as the plugin name, type, and menu integration.
Note
Only Python files whose names start with datalab_ will be scanned for plugins.
DataLab supports three categories of plugins, each with its own purpose and registration mechanism:
Processing and visualization plugins Add custom actions for signal or image processing. These may include new computation functions, data visualization tools, or interactive dialogs. Integrated into a dedicated submenu of the âPluginsâ menu.
Input/Output plugins Define new file formats (read and/or write) handled transparently by DataLabâs I/O framework. These plugins extend compatibility with custom or third-party data formats.
HDF5 plugins Special plugins that support HDF5 files with domain-specific tree structures. These allow DataLab to interpret signals or images organized in non-standard ways.
Where to put a plugin?#
Plugins are automatically discovered at startup from multiple locations:
The user plugin directory: Typically ~/.DataLab/plugins on Linux/macOS or C:/Users/YourName/.DataLab/plugins on Windows.
A custom plugin directory: Configurable in DataLabâs preferences.
The standalone distribution directory: If using a frozen (standalone) build, the plugins folder located next to the executable is scanned.
The internal datalab/plugins folder (not recommended for user plugins): This location is reserved for built-in or bundled plugins and should not be modified manually.
How to develop a plugin?#
The recommended approach to developing a plugin is to derive from an existing example and adapt it to your needs. You can explore the source code in the datalab/plugins folder or refer to community-contributed examples.
Note
Most of DataLabâs signal and image processing functionalities have been externalized into a dedicated library called Sigima (https://sigima.readthedocs.io/en/latest/). When developing DataLab plugins, you will typically import and use many Sigima functions and features to perform data processing, analysis, and visualization tasks. Sigima provides a comprehensive set of tools for scientific data manipulation that can be leveraged directly in your plugins.
To develop in your usual Python environment (e.g., with an IDE like Spyder), you can:
Install DataLab in your Python environment, using one of the following methods:
Or add the `datalab` package manually to your Python path:
Download the source from the PyPI page,
Unzip the archive,
Add the datalab directory to your PYTHONPATH (e.g., using the PYTHONPATH Manager in Spyder).
Note
Even if youâve installed datalab in your environment, you cannot run the full DataLab application directly from an IDE. You must launch DataLab via the command line or using the installer-created shortcut to properly test your plugin.
Example: processing plugin#
Here is a minimal example of a plugin that prints a message when activated:
# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
"""
Test Data Plugin for DataLab
----------------------------
This plugin is an example of DataLab plugin. It provides test data samples
and some actions to test DataLab functionalities.
"""
from __future__ import annotations
import sigima.tests.data as test_data
from sigima.io.image import ImageIORegistry
from sigima.io.signal import SignalIORegistry
from sigima.tests import helpers
from datalab.config import _
from datalab.plugins import PluginBase, PluginInfo
from datalab.utils.qthelpers import create_progress_bar
# ------------------------------------------------------------------------------
# All computation functions must be defined as global functions, otherwise
# they cannot be pickled and sent to the worker process
# ------------------------------------------------------------------------------
class PluginTestData(PluginBase):
"""DataLab Test Data Plugin"""
PLUGIN_INFO = PluginInfo(
name=_("Test data"),
version="1.0.0",
description=_("Testing DataLab functionalities"),
)
def load_test_objs(
self, registry_class: type[SignalIORegistry | ImageIORegistry], title: str
) -> None:
"""Load all test objects from a given registry class
Args:
registry_class: Registry class (SignalIORegistry or ImageIORegistry)
title: Progress bar title
Returns:
List of (filename, object) tuples
"""
test_objs = list(helpers.read_test_objects(registry_class))
with create_progress_bar(self.signalpanel, title, max_=len(test_objs)) as prog:
for i_obj, (_fname, obj) in enumerate(test_objs):
prog.setValue(i_obj + 1)
if prog.wasCanceled():
break
if obj is not None:
self.proxy.add_object(obj)
# Signal processing features ------------------------------------------------
def create_paracetamol_signal(self) -> None:
"""Create paracetamol signal"""
obj = test_data.create_paracetamol_signal()
self.proxy.add_object(obj)
# Image processing features ------------------------------------------------
def create_peak_image(self) -> None:
"""Create 2D peak image"""
obj = self.imagepanel.new_object(add_to_panel=False)
if obj is not None:
param = test_data.PeakDataParam.create(size=max(obj.data.shape))
self.imagepanel.processor.update_param_defaults(param)
if param.edit(self.main):
obj.data, _coords = test_data.get_peak2d_data(param)
self.proxy.add_object(obj)
def create_sincos_image(self) -> None:
"""Create 2D sin cos image"""
newparam = self.edit_new_image_parameters(hide_type=True)
if newparam is not None:
obj = test_data.create_sincos_image(newparam)
self.proxy.add_object(obj)
def create_noisy_gaussian_image(self) -> None:
"""Create 2D noisy gauss image"""
newparam = self.edit_new_image_parameters(hide_height=True, hide_type=True)
if newparam is not None:
obj = test_data.create_noisy_gaussian_image(newparam, add_annotations=False)
self.proxy.add_object(obj)
def create_multigaussian_image(self) -> None:
"""Create 2D multi gauss image"""
newparam = self.edit_new_image_parameters(hide_height=True, hide_type=True)
if newparam is not None:
obj = test_data.create_multigaussian_image(newparam)
self.proxy.add_object(obj)
def create_2dstep_image(self) -> None:
"""Create 2D step image"""
newparam = self.edit_new_image_parameters(hide_type=True)
if newparam is not None:
obj = test_data.create_2dstep_image(newparam)
self.proxy.add_object(obj)
def create_ring_image(self) -> None:
"""Create 2D ring image"""
param = test_data.RingParam(_("Ring"))
if param.edit(self.main):
obj = test_data.create_ring_image(param)
self.proxy.add_object(obj)
def create_annotated_image(self) -> None:
"""Create annotated image"""
obj = test_data.create_annotated_image()
self.proxy.add_object(obj)
def create_grid_gaussian_image(self) -> None:
"""Create image with a grid of gaussian spots"""
param = test_data.GridOfGaussianImages(_("Grid of Gaussian Images"))
if param.edit(self.main):
obj = test_data.create_grid_of_gaussian_images(param)
self.proxy.add_object(obj)
# Plugin menu entries ------------------------------------------------------
def create_actions(self) -> None:
"""Create actions"""
# Signal Panel ----------------------------------------------------------
sah = self.signalpanel.acthandler
with sah.new_menu(_("Test data")):
sah.new_action(
_("Load spectrum of paracetamol"),
triggered=self.create_paracetamol_signal,
select_condition="always",
)
sah.new_action(
_("Load all test signals"),
triggered=lambda regclass=SignalIORegistry,
title=_("Load all test signals"): self.load_test_objs(regclass, title),
select_condition="always",
separator=True,
)
# Image Panel -----------------------------------------------------------
iah = self.imagepanel.acthandler
with iah.new_menu(_("Test data")):
iah.new_action(
_("Create image with peaks"),
triggered=self.create_peak_image,
select_condition="always",
separator=True,
)
iah.new_action(
_("Create 2D sin cos image"),
triggered=self.create_sincos_image,
select_condition="always",
)
iah.new_action(
_("Create 2D noisy gaussian image"),
triggered=self.create_noisy_gaussian_image,
select_condition="always",
)
iah.new_action(
_("Create 2D multi gaussian image"),
triggered=self.create_multigaussian_image,
select_condition="always",
)
iah.new_action(
_("Create annotated image"),
triggered=self.create_annotated_image,
select_condition="always",
)
iah.new_action(
_("Create 2D step image"),
triggered=self.create_2dstep_image,
select_condition="always",
)
iah.new_action(
_("Create ring image"),
triggered=self.create_ring_image,
select_condition="always",
)
iah.new_action(
_("Create image with a grid of gaussian spots"),
triggered=self.create_grid_gaussian_image,
select_condition="always",
)
iah.new_action(
_("Load all test images"),
triggered=lambda regclass=ImageIORegistry,
title=_("Load all test images"): self.load_test_objs(regclass, title),
select_condition="always",
separator=True,
)
Example: input/output plugin#
Here is a simple example of a plugin that adds a new file formats to DataLab.
# Copyright (c) DataLab Platform Developers, BSD 3-Clause license, see LICENSE file.
"""
Image file formats Plugin for DataLab
-------------------------------------
This plugin is an example of DataLab plugin.
It provides image file formats from cameras, scanners, and other acquisition devices.
"""
import struct
import numpy as np
from sigima.io.base import FormatInfo
from sigima.io.image.base import SingleImageFormatBase
# ==============================================================================
# Thales Pixium FXD file format
# ==============================================================================
class FXDFile:
"""Class implementing Thales Pixium FXD Image file reading feature
Args:
fname (str): path to FXD file
debug (bool): debug mode
"""
HEADER = "<llllllffl"
def __init__(self, fname: str = None, debug: bool = False) -> None:
self.__debug = debug
self.file_format = None # long
self.nbcols = None # long
self.nbrows = None # long
self.nbframes = None # long
self.pixeltype = None # long
self.quantlevels = None # long
self.maxlevel = None # float
self.minlevel = None # float
self.comment_length = None # long
self.fname = None
self.data = None
if fname is not None:
self.load(fname)
def __repr__(self) -> str:
"""Return a string representation of the object"""
info = (
("Image width", f"{self.nbcols:d}"),
("Image Height", f"{self.nbrows:d}"),
("Frame number", f"{self.nbframes:d}"),
("File format", f"{self.file_format:d}"),
("Pixel type", f"{self.pixeltype:d}"),
("Quantlevels", f"{self.quantlevels:d}"),
("Min. level", f"{self.minlevel:f}"),
("Max. level", f"{self.maxlevel:f}"),
("Comment length", f"{self.comment_length:d}"),
)
desc_len = max(len(d) for d in list(zip(*info))[0]) + 3
res = ""
for description, value in info:
res += ("{:" + str(desc_len) + "}{}\n").format(description + ": ", value)
res = object.__repr__(self) + "\n" + res
return res
def load(self, fname: str) -> None:
"""Load header and image pixel data
Args:
fname (str): path to FXD file
"""
with open(fname, "rb") as data_file:
header_s = struct.Struct(self.HEADER)
record = data_file.read(9 * 4)
unpacked_rec = header_s.unpack(record)
(
self.file_format,
self.nbcols,
self.nbrows,
self.nbframes,
self.pixeltype,
self.quantlevels,
self.maxlevel,
self.minlevel,
self.comment_length,
) = unpacked_rec
if self.__debug:
print(unpacked_rec)
print(self)
data_file.seek(128 + self.comment_length)
if self.pixeltype == 0:
size, dtype = 4, np.float32
elif self.pixeltype == 1:
size, dtype = 2, np.uint16
elif self.pixeltype == 2:
size, dtype = 1, np.uint8
else:
raise NotImplementedError(f"Unsupported pixel type: {self.pixeltype}")
block = data_file.read(self.nbrows * self.nbcols * size)
data = np.frombuffer(block, dtype=dtype)
self.data = data.reshape(self.nbrows, self.nbcols)
class FXDImageFormat(SingleImageFormatBase):
"""Object representing Thales Pixium (FXD) image file type"""
FORMAT_INFO = FormatInfo(
name="Thales Pixium",
extensions="*.fxd",
readable=True,
writeable=False,
)
@staticmethod
def read_data(filename: str) -> np.ndarray:
"""Read data and return it
Args:
filename (str): path to FXD file
Returns:
np.ndarray: image data
"""
fxd_file = FXDFile(filename)
return fxd_file.data
# ==============================================================================
# DĂŒrr NDT XYZ file format
# ==============================================================================
class XYZImageFormat(SingleImageFormatBase):
"""Object representing DĂŒrr NDT XYZ image file type"""
FORMAT_INFO = FormatInfo(
name="DĂŒrr NDT",
extensions="*.xyz",
readable=True,
writeable=True,
)
@staticmethod
def read_data(filename: str) -> np.ndarray:
"""Read data and return it
Args:
filename (str): path to XYZ file
Returns:
np.ndarray: image data
"""
with open(filename, "rb") as fdesc:
cols = int(np.fromfile(fdesc, dtype=np.uint16, count=1)[0])
rows = int(np.fromfile(fdesc, dtype=np.uint16, count=1)[0])
arr = np.fromfile(fdesc, dtype=np.uint16, count=cols * rows)
arr = arr.reshape((rows, cols))
return np.fliplr(arr)
@staticmethod
def write_data(filename: str, data: np.ndarray) -> None:
"""Write data to file
Args:
filename: File name
data: Image array data
"""
data = np.fliplr(data)
with open(filename, "wb") as fdesc:
fdesc.write(np.array(data.shape[1], dtype=np.uint16).tobytes())
fdesc.write(np.array(data.shape[0], dtype=np.uint16).tobytes())
fdesc.write(data.tobytes())
Other examples#
Other examples of plugins can be found in the plugins/examples directory of the DataLab source code (explore here on GitHub).
Migrating from v0.20 to v1.0#
If you have existing plugins written for DataLab v0.20, please refer to the migration guide for detailed instructions on updating your plugins to work with DataLab v1.0.
Public API#
DataLab plugin system#
DataLab plugin system provides a way to extend the application with new functionalities.
Plugins are Python modules that relies on two classes:
PluginInfo, which stores information about the plugin
PluginBase, which is the base class for all plugins
Plugins may also extends DataLab I/O features by providing new image or
signal formats. To do so, they must provide a subclass of ImageFormatBase
or SignalFormatBase, in which format information is defined using the
FormatInfo class.
- class datalab.plugins.PluginRegistry(name, bases, attrs)[source]#
Metaclass for registering plugins
- classmethod get_plugin_classes() list[type[PluginBase]][source]#
Return plugin classes
- classmethod get_plugins() list[PluginBase][source]#
Return plugin instances
- classmethod get_plugin(name_or_class: str | type[PluginBase]) PluginBase | None[source]#
Return plugin instance
- classmethod register_plugin(plugin: PluginBase)[source]#
Register plugin
- classmethod unregister_plugin(plugin: PluginBase)[source]#
Unregister plugin
- class datalab.plugins.PluginInfo(name: str | None = None, version: str = '0.0.0', description: str = '', icon: str | None = None)[source]#
Plugin info
- class datalab.plugins.PluginBaseMeta(name, bases, namespace, **kwargs)[source]#
Mixed metaclass to avoid conflicts
- class datalab.plugins.PluginBase[source]#
Plugin base class
- property signalpanel: SignalPanel#
Return signal panel
- property imagepanel: ImagePanel#
Return image panel
- ask_yesno(message: str, title: str | None = None, cancelable: bool = False) bool[source]#
Ask yes/no question
- edit_new_signal_parameters(title: str | None = None, size: int | None = None) NewSignalParam[source]#
Create and edit new signal parameter dataset
- Parameters:
title â title of the new signal
size â size of the new signal (default: None, get from current signal)
- Returns:
New signal parameter dataset (or None if canceled)
- edit_new_image_parameters(title: str | None = None, shape: tuple[int, int] | None = None, hide_height: bool = False, hide_width: bool = False, hide_type: bool = True, hide_dtype: bool = False) NewImageParam | None[source]#
Create and edit new image parameter dataset
- Parameters:
title â title of the new image
shape â shape of the new image (default: None, get from current image)
hide_height â hide image heigth parameter (default: False)
hide_width â hide image width parameter (default: False)
hide_type â hide image type parameter (default: True)
hide_dtype â hide image data type parameter (default: False)
- Returns:
New image parameter dataset (or None if canceled)
- register(main: main.DLMainWindow) None[source]#
Register plugin
- datalab.plugins.discover_plugins() list[type[PluginBase]][source]#
Discover plugins using naming convention
- Returns:
List of discovered plugins (as classes)
- datalab.plugins.discover_v020_plugins() list[tuple[str, str]][source]#
Discover v0.20 plugins (with
cdl_prefix) without importing them- Returns:
List of tuples (plugin_name, directory_path) for discovered v0.20 plugins
- datalab.plugins.get_available_plugins() list[PluginBase][source]#
Instantiate and get available plugins
- Returns:
List of available plugins (as instances)