| 1 |
.. _about_plugins: |
| 2 |
|
| 3 |
Plugins |
| 4 |
======= |
| 5 |
|
| 6 |
.. meta:: |
| 7 |
:description: Plugin system for DataLab, the open-source scientific data analysis and visualization platform |
| 8 |
:keywords: DataLab, plugin, processing, input/output, HDF5, file format, data analysis, visualization, scientific, open-source, platform |
| 9 |
|
| 10 |
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. |
| 11 |
|
| 12 |
What is a plugin? |
| 13 |
----------------- |
| 14 |
|
| 15 |
A plugin is a Python module that is automatically loaded by DataLab at startup. It can define new features or modify existing ones. |
| 16 |
|
| 17 |
To be recognized as a plugin, the file must: |
| 18 |
|
| 19 |
- Be a Python module whose name **starts with** ``datalab_`` (e.g. ``datalab_myplugin.py``), |
| 20 |
- Contain a class that **inherits from** :class:`datalab.plugins.PluginBase`, |
| 21 |
- Include a class attribute named ``PLUGIN_INFO``, which must be an instance of :class:`datalab.plugins.PluginInfo`. |
| 22 |
|
| 23 |
This `PLUGIN_INFO` object is used by DataLab to retrieve metadata such as the plugin name, type, and menu integration. |
| 24 |
|
| 25 |
.. note:: |
| 26 |
|
| 27 |
Only Python files whose names start with ``datalab_`` will be scanned for plugins. |
| 28 |
|
| 29 |
DataLab supports three categories of plugins, each with its own purpose and registration mechanism: |
| 30 |
|
| 31 |
- **Processing and visualization plugins** |
| 32 |
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. |
| 33 |
|
| 34 |
- **Input/Output plugins** |
| 35 |
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. |
| 36 |
|
| 37 |
- **HDF5 plugins** |
| 38 |
Special plugins that support HDF5 files with domain-specific tree structures. These allow DataLab to interpret signals or images organized in non-standard ways. |
| 39 |
|
| 40 |
Where to put a plugin? |
| 41 |
---------------------- |
| 42 |
|
| 43 |
Plugins are automatically discovered at startup from multiple locations: |
| 44 |
|
| 45 |
- The user plugin directory: |
| 46 |
Typically `~/.DataLab/plugins` on Linux/macOS or `C:/Users/YourName/.DataLab/plugins` on Windows. |
| 47 |
|
| 48 |
- A custom plugin directory: |
| 49 |
Configurable in DataLab's preferences. |
| 50 |
|
| 51 |
- The standalone distribution directory: |
| 52 |
If using a frozen (standalone) build, the `plugins` folder located next to the executable is scanned. |
| 53 |
|
| 54 |
- The internal `datalab/plugins` folder (not recommended for user plugins): |
| 55 |
This location is reserved for built-in or bundled plugins and should not be modified manually. |
| 56 |
|
| 57 |
How to develop a plugin? |
| 58 |
------------------------ |
| 59 |
|
| 60 |
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. |
| 61 |
|
| 62 |
.. note:: |
| 63 |
|
| 64 |
Most of DataLab's signal and image processing functionalities have been externalized into a dedicated library called **Sigima** (`https://sigima.readthedocs.io/en/latest/ <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. |
| 65 |
|
| 66 |
To develop in your usual Python environment (e.g., with an IDE like `Spyder <https://www.spyder-ide.org/>`_), you can: |
| 67 |
|
| 68 |
1. **Install DataLab in your Python environment**, using one of the following methods: |
| 69 |
|
| 70 |
- :ref:`install_conda` |
| 71 |
- :ref:`install_pip` |
| 72 |
- :ref:`install_wheel` |
| 73 |
- :ref:`install_source` |
| 74 |
|
| 75 |
2. **Or add the `datalab` package manually to your Python path**: |
| 76 |
|
| 77 |
- Download the source from the `PyPI page <https://pypi.org/project/datalab-platform/>`_, |
| 78 |
- Unzip the archive, |
| 79 |
- Add the `datalab` directory to your PYTHONPATH (e.g., using the *PYTHONPATH Manager* in Spyder). |
| 80 |
|
| 81 |
.. note:: |
| 82 |
|
| 83 |
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. |
| 84 |
|
| 85 |
Example: processing plugin |
| 86 |
-------------------------- |
| 87 |
|
| 88 |
Here is a minimal example of a plugin that prints a message when activated: |
| 89 |
|
| 90 |
.. literalinclude:: ../../../datalab/plugins/datalab_testdata.py |
| 91 |
|
| 92 |
Example: input/output plugin |
| 93 |
---------------------------- |
| 94 |
|
| 95 |
Here is a simple example of a plugin that adds a new file formats to DataLab. |
| 96 |
|
| 97 |
.. literalinclude:: ../../../datalab/plugins/datalab_imageformats.py |
| 98 |
|
| 99 |
Other examples |
| 100 |
-------------- |
| 101 |
|
| 102 |
Other examples of plugins can be found in the `plugins/examples` directory of the DataLab source code (explore `here on GitHub <https://github.com/DataLab-Platform/DataLab/tree/main/plugins/examples>`_). |
| 103 |
|
| 104 |
Migrating from v0.20 to v1.0 |
| 105 |
---------------------------- |
| 106 |
|
| 107 |
If you have existing plugins written for DataLab v0.20, please refer to the :ref:`migration guide <migration_v020_to_v100>` for detailed instructions on updating your plugins to work with DataLab v1.0. |
| 108 |
|
| 109 |
Public API |
| 110 |
---------- |
| 111 |
|
| 112 |
.. automodule:: datalab.plugins |
| 113 |
:members: PluginInfo, PluginBase, FormatInfo, ImageFormatBase, ClassicsImageFormat, SignalFormatBase |