Debian Codegraph @

doc/features/advanced/plugins.rst

raw
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