Plugins#
DataLab is a modular application. It is possible to add new features to DataLab by writing plugins. A plugin is a Python module that is loaded at startup by DataLab. A plugin may add new features to DataLab, or modify existing features.
The plugin system currently supports the following features:
Processing features: add new processing tasks to the DataLab processing system, including specific graphical user interfaces.
Input/output features: add new file formats to the DataLab file I/O system.
HDF5 features: add new HDF5 file formats to the DataLab HDF5 I/O system.
What is a plugin?#
A plugin is a Python module that is loaded at startup by DataLab. A plugin may add new features to DataLab, or modify existing features.
A plugin is a Python module which file name starts with cdl_, and which
contains a class derived from the cdl.plugins.PluginBase class.
The name of the class is not important, as long as it is derived from
cdl.plugins.PluginBase and has a PLUGIN_INFO attribute that is an
instance of the cdl.plugins.PluginInfo class. The PLUGIN_INFO attribute
is used by DataLab to retrieve information about the plugin.
Note
DataLab’s plugin discovery mechanism will only load plugins that are defined
in Python files which names start with cdl_ (e.g. cdl_myplugin.py).
Where to put a plugin?#
As plugins are Python modules, they can be put anywhere in the Python path of the DataLab installation.
Special additional locations are available for plugins:
The plugins directory in the user configuration folder (e.g. C:UsersJohnDoe.DataLabplugins on Windows or ~/.DataLab/plugins on Linux).
The plugins directory in the same folder as the DataLab executable in case of a standalone installation.
The plugins directory in the cdl package in case for internal plugins only (i.e. it is not recommended to put your own plugins there).
How to develop a plugin?#
To develop a plugin, you may start by deriving from one of the example plugins (see below) and modify it to suit your needs.
If you want to code a plugin in your usual Python development environment (preferably with an IDE like Spyder) and take advantage of the code completion, you can add the cdl package to your Python path.
This can be done:
By installing DataLab in your Python environment (using one of the following methods: Conda package, Package manager pip, Wheel package, or Source package),
Or by adding the cdl package to your Python path manually:
Download the DataLab source code from the PyPI page,
Unzip the source code to a folder on your computer,
Add the cdl package to your Python path (e.g. by using the PYTHONPATH Manager in Spyder).
Note
Even if you have installed the cdl package properly in your Python environment, you won’t be able to run the DataLab application from your development environment to test your plugin. You will need to run DataLab from the command line or from the shortcut created during the installation.
Example: processing plugin#
Here is a simple example of a plugin that adds a new features to DataLab.
# 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.
"""
import cdl.obj as dlo
import cdl.tests.data as test_data
from cdl.computation import image as cpima
from cdl.computation import signal as cpsig
from cdl.config import _
from cdl.plugins import PluginBase, PluginInfo
# ------------------------------------------------------------------------------
# All computation functions must be defined as global functions, otherwise
# they cannot be pickled and sent to the worker process
# ------------------------------------------------------------------------------
def add_noise_to_signal(
src: dlo.SignalObj, p: test_data.GaussianNoiseParam
) -> dlo.SignalObj:
"""Add gaussian noise to signal"""
dst = cpsig.dst_11(src, "add_gaussian_noise", f"mu={p.mu},sigma={p.sigma}")
test_data.add_gaussian_noise_to_signal(dst, p)
return dst
def add_noise_to_image(src: dlo.ImageObj, p: dlo.NormalRandomParam) -> dlo.ImageObj:
"""Add gaussian noise to image"""
dst = cpima.dst_11(src, "add_gaussian_noise", f"mu={p.mu},sigma={p.sigma}")
test_data.add_gaussian_noise_to_image(dst, p)
return dst
class PluginTestData(PluginBase):
"""DataLab Test Data Plugin"""
PLUGIN_INFO = PluginInfo(
name=_("Test data"),
version="1.0.0",
description=_("Testing DataLab functionalities"),
)
# Signal processing features ------------------------------------------------
def add_noise_to_signal(self) -> None:
"""Add noise to signal"""
self.signalpanel.processor.compute_11(
add_noise_to_signal,
paramclass=test_data.GaussianNoiseParam,
title=_("Add noise"),
)
def create_paracetamol_signal(self) -> None:
"""Create paracetamol signal"""
obj = test_data.create_paracetamol_signal()
self.proxy.add_object(obj)
def create_noisy_signal(self) -> None:
"""Create noisy signal"""
obj = self.signalpanel.new_object(add_to_panel=False)
if obj is not None:
noiseparam = test_data.GaussianNoiseParam(_("Noise"))
self.signalpanel.processor.update_param_defaults(noiseparam)
if noiseparam.edit(self.main):
test_data.add_gaussian_noise_to_signal(obj, noiseparam)
self.proxy.add_object(obj)
# Image processing features ------------------------------------------------
def add_noise_to_image(self) -> None:
"""Add noise to image"""
self.imagepanel.processor.compute_11(
add_noise_to_image,
paramclass=dlo.NormalRandomParam,
title=_("Add noise"),
)
def create_peak2d_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 = 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_image_type=True)
if newparam is not None:
obj = test_data.create_sincos_image(newparam)
self.proxy.add_object(obj)
def create_noisygauss_image(self) -> None:
"""Create 2D noisy gauss image"""
newparam = self.edit_new_image_parameters(hide_image_type=True)
if newparam is not None:
obj = test_data.create_noisygauss_image(newparam, add_annotations=False)
self.proxy.add_object(obj)
def create_multigauss_image(self) -> None:
"""Create 2D multi gauss image"""
newparam = self.edit_new_image_parameters(hide_image_type=True)
if newparam is not None:
obj = test_data.create_multigauss_image(newparam)
self.proxy.add_object(obj)
def create_2dstep_image(self) -> None:
"""Create 2D step image"""
newparam = self.edit_new_image_parameters(hide_image_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)
# 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(_("Add noise to signal"), triggered=self.add_noise_to_signal)
sah.new_action(
_("Load spectrum of paracetamol"),
triggered=self.create_paracetamol_signal,
select_condition="always",
separator=True,
)
sah.new_action(
_("Create noisy signal"),
triggered=self.create_noisy_signal,
select_condition="always",
)
# Image Panel -----------------------------------------------------------
iah = self.imagepanel.acthandler
with iah.new_menu(_("Test data")):
iah.new_action(_("Add noise to image"), triggered=self.add_noise_to_image)
# with iah.new_menu(_("Data samples")):
iah.new_action(
_("Create image with peaks"),
triggered=self.create_peak2d_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 gauss image"),
triggered=self.create_noisygauss_image,
select_condition="always",
)
iah.new_action(
_("Create 2D multi gauss image"),
triggered=self.create_multigauss_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",
)
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 cdl.core.io.base import FormatInfo
from cdl.core.io.image.base import ImageFormatBase
# ==============================================================================
# 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(ImageFormatBase):
"""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(ImageFormatBase):
"""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).
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 infos are defined using the
FormatInfo class.
- class cdl.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 cdl.plugins.PluginInfo(name: str = None, version: str = '0.0.0', description: str = '', icon: str = None)[source]#
Plugin info
- class cdl.plugins.PluginBaseMeta(name, bases, namespace, /, **kwargs)[source]#
Mixed metaclass to avoid conflicts
- class cdl.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, hide_signal_type: bool = True) 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)
hide_signal_type – hide signal type parameter (default: True)
- Returns:
New signal parameter dataset (or None if canceled)
- edit_new_image_parameters(title: str | None = None, shape: tuple[int, int] | None = None, hide_image_type: bool = True, hide_image_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_image_type – hide image type parameter (default: True)
hide_image_dtype – hide image data type parameter (default: False)
- Returns:
New image parameter dataset (or None if canceled)
- register(main: main.CDLMainWindow) None[source]#
Register plugin
- cdl.plugins.discover_plugins() list[type[PluginBase]][source]#
Discover plugins using naming convention
- Returns:
List of discovered plugins (as classes)
- cdl.plugins.get_available_plugins() list[PluginBase][source]#
Instantiate and get available plugins
- Returns:
List of available plugins (as instances)