You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The **Installation and Configuration** dialog box is a diagnostic tool available from DataLab’s graphical interface. It provides a structured overview of the current installation, user-specific settings, and available plugins and I/O features.
9
7
10
-
Because of the multiple ways of installing DataLab on your machine,
11
-
understanding why the application behaves unexpectedly without any
12
-
information on your configuration could be very challenging.
8
+
This tool is primarily designed for troubleshooting and verification purposes — whether you are a user trying to understand how DataLab is set up on your system, or a developer validating your plugin integration.
13
9
14
-
That is why DataLab provides the dialog box "Installation and configuration"
15
-
which gathers all the information about your installation and configuration.
10
+
To open the dialog box, go to the "?" menu in the main DataLab window and select **Installation and configuration**. This will open a dialog window that displays all relevant information about your DataLab installation.
16
11
17
-
.. note::
12
+
The dialog window is divided into **three tabs**, each covering a specific aspect of the environment.
18
13
19
-
The installation and configuration viewer is accessible from the "?" menu in the main window.
14
+
1. Installation Configuration
15
+
-----------------------------
20
16
21
17
.. figure:: /images/shots/instviewer.png
22
18
23
-
Installation and configuration (see "?" menu)
19
+
Installation and configuration (see "?" menu), tab 1
20
+
21
+
This tab displays system-level information about the DataLab installation, including:
22
+
23
+
- Application version;
24
+
- Platform and operating system;
25
+
- Whether DataLab is running in frozen (standalone) mode or as a standard Python package;
26
+
- Internal paths used for data storage and plugin discovery;
This section is especially useful for debugging path-related issues or confirming the installation context (e.g., standalone vs. pip-installed).
31
+
32
+
2. User Configuration
33
+
---------------------
34
+
35
+
.. figure:: /images/shots/instviewer2.png
36
+
37
+
Installation and configuration (see "?" menu), tab 2
38
+
39
+
This tab lists user-specific configuration details, through the contents of DataLab's configuration file.
40
+
41
+
It helps users verify their personalized settings and ensures that DataLab is reading the correct directories for user-defined plugins or preferences.
42
+
43
+
3. Plugins and I/O Features
44
+
---------------------------
45
+
46
+
.. figure:: /images/shots/instviewer3.png
47
+
48
+
Installation and configuration (see "?" menu), tab 3
49
+
50
+
This tab lists all plugins and I/O handlers currently available in the application.
51
+
52
+
This view is ideal for verifying that all expected plugins and I/O features are detected, loaded, and functional.
53
+
54
+
Usage Tips
55
+
----------
56
+
57
+
- You can copy text from any of the tabs for diagnostic or support purposes.
58
+
- If a plugin or I/O feature does not appear, check that its filename starts with `cdl_` and that it is located in a recognized plugin directory (see the *User Configuration* tab).
59
+
60
+
.. note::
24
61
25
-
Reporting unexpected behavior or any other bug on `GitHub Issues`_
26
-
will be greatly appreciated, especially if above contents are attached
27
-
to the report (as well log files, see :ref:`ref-to-logviewer`).
62
+
Reporting unexpected behavior or any other bug on `GitHub Issues`_ will be greatly appreciated, especially if the contents of this viewer are attached to the report (as well as log files, see :ref:`ref-to-logviewer`).
Copy file name to clipboardExpand all lines: en/_sources/features/general/plugins.rst.txt
+50-55Lines changed: 50 additions & 55 deletions
Original file line number
Diff line number
Diff line change
@@ -7,103 +7,98 @@ Plugins
7
7
:description: Plugin system for DataLab, the open-source scientific data analysis and visualization platform
8
8
:keywords: DataLab, plugin, processing, input/output, HDF5, file format, data analysis, visualization, scientific, open-source, platform
9
9
10
-
DataLab is a modular application. It is possible to add new features to DataLab
11
-
by writing plugins. A plugin is a Python module that is loaded at startup by
12
-
DataLab. A plugin may add new features to DataLab, or modify existing features.
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.
13
11
14
-
The plugin system currently supports the following features:
12
+
What is a plugin?
13
+
-----------------
15
14
16
-
- Processing features: add new processing tasks to the DataLab processing
17
-
system, including specific graphical user interfaces.
18
-
- Input/output features: add new file formats to the DataLab file I/O system.
19
-
- HDF5 features: add new HDF5 file formats to the DataLab HDF5 I/O system.
15
+
A plugin is a Python module that is automatically loaded by DataLab at startup. It can define new features or modify existing ones.
20
16
21
-
What is a plugin?
22
-
^^^^^^^^^^^^^^^^^
17
+
To be recognized as a plugin, the file must:
23
18
24
-
A plugin is a Python module that is loaded at startup by DataLab. A plugin may
25
-
add new features to DataLab, or modify existing features.
19
+
- Be a Python module whose name **starts with** ``cdl_`` (e.g. ``cdl_myplugin.py``),
20
+
- Contain a class that **inherits from** :class:`cdl.plugins.PluginBase`,
21
+
- Include a class attribute named ``PLUGIN_INFO``, which must be an instance of :class:`cdl.plugins.PluginInfo`.
26
22
27
-
A plugin is a Python module which file name starts with ``cdl_``, and which
28
-
contains a class derived from the :class:`cdl.plugins.PluginBase` class.
29
-
The name of the class is not important, as long as it is derived from
30
-
:class:`cdl.plugins.PluginBase` and has a ``PLUGIN_INFO`` attribute that is an
31
-
instance of the :class:`cdl.plugins.PluginInfo` class. The ``PLUGIN_INFO`` attribute
32
-
is used by DataLab to retrieve information about the plugin.
23
+
This `PLUGIN_INFO` object is used by DataLab to retrieve metadata such as the plugin name, type, and menu integration.
33
24
34
25
.. note::
35
26
36
-
DataLab's plugin discovery mechanism will only load plugins that are defined
37
-
in Python files which names start with ``cdl_`` (e.g. ``cdl_myplugin.py``).
27
+
Only Python files whose names start with ``cdl_`` 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.
38
39
39
40
Where to put a plugin?
40
-
^^^^^^^^^^^^^^^^^^^^^^
41
+
----------------------
41
42
42
-
As plugins are Python modules, they can be put anywhere in the Python path of
43
-
the DataLab installation.
43
+
Plugins are automatically discovered at startup from multiple locations:
44
44
45
-
Special additional locations are available for plugins:
45
+
- The user plugin directory:
46
+
Typically `~/.DataLab/plugins` on Linux/macOS or `C:/Users/YourName/.DataLab/plugins` on Windows.
46
47
47
-
- The `plugins` directory in the user configuration folder
48
-
(e.g. `C:/Users/JohnDoe/.DataLab/plugins` on Windows
49
-
or `~/.DataLab/plugins` on Linux).
48
+
- A custom plugin directory:
49
+
Configurable in DataLab's preferences.
50
50
51
-
- The `plugins` directory in the same folder as the `DataLab` executable
52
-
in case of a standalone installation.
51
+
- The standalone distribution directory:
52
+
If using a frozen (standalone) build, the `plugins` folder located next to the executable is scanned.
53
53
54
-
- The `plugins` directory in the `cdl` package in case for internal plugins
55
-
only (i.e. it is not recommended to put your own plugins there).
54
+
- The internal `cdl/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
56
57
57
How to develop a plugin?
58
-
^^^^^^^^^^^^^^^^^^^^^^^^
58
+
------------------------
59
59
60
-
To develop a plugin, you may start by deriving from one of the example plugins
61
-
(see below) and modify it to suit your needs.
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 `cdl/plugins` folder or refer to community-contributed examples.
62
61
63
-
If you want to code a plugin in your usual Python development environment (preferably
64
-
with an IDE like `Spyder <https://www.spyder-ide.org/>`_) and take advantage of the
65
-
code completion, you can add the `cdl` package to your Python path.
62
+
To develop in your usual Python environment (e.g., with an IDE like `Spyder <https://www.spyder-ide.org/>`_), you can:
66
63
67
-
This can be done:
64
+
1. **Install DataLab in your Python environment**, using one of the following methods:
68
65
69
-
- By installing DataLab in your Python environment (using one of the following methods:
70
-
:ref:`install_conda`, :ref:`install_pip`, :ref:`install_wheel`, or :ref:`install_source`),
66
+
- :ref:`install_conda`
67
+
- :ref:`install_pip`
68
+
- :ref:`install_wheel`
69
+
- :ref:`install_source`
71
70
72
-
- Or by adding the `cdl` package to your Python path manually:
71
+
2. **Or add the `cdl` package manually to your Python path**:
73
72
74
-
- Download the DataLab source code from the `PyPI page <https://pypi.org/project/cdl/>`_,
75
-
- Unzip the source code to a folder on your computer,
76
-
- Add the `cdl` package to your Python path (e.g. by using the *PYTHONPATH Manager* in Spyder).
73
+
- Download the source from the `PyPI page <https://pypi.org/project/cdl/>`_,
74
+
- Unzip the archive,
75
+
- Add the `cdl` directory to your PYTHONPATH (e.g., using the *PYTHONPATH Manager* in Spyder).
77
76
78
77
.. note::
79
78
80
-
Even if you have installed the `cdl` package properly in your Python environment,
81
-
you won't be able to run the DataLab application from your development environment
82
-
to test your plugin. You will need to run DataLab from the command line or from
83
-
the shortcut created during the installation.
79
+
Even if you’ve installed `cdl` 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
80
85
81
Example: processing plugin
86
-
^^^^^^^^^^^^^^^^^^^^^^^^^^
82
+
--------------------------
87
83
88
-
Here is a simple example of a plugin that adds a new features to DataLab.
84
+
Here is a minimal example of a plugin that prints a message when activated:
Other examples of plugins can be found in the `plugins/examples` directory of
103
-
the DataLab source code (explore `here on GitHub <https://github.com/DataLab-Platform/DataLab/tree/main/plugins/examples>`_).
98
+
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>`_).
0 commit comments