| 1 |
.. _migration_v020_to_v100: |
| 2 |
|
| 3 |
Migrating from DataLab v0.20 to v1.0 |
| 4 |
==================================== |
| 5 |
|
| 6 |
.. meta:: |
| 7 |
:description: Guide for migrating DataLab plugins from v0.20 to v1.0 |
| 8 |
:keywords: DataLab, plugin, migration, v0.20, v1.0, Sigima, API changes |
| 9 |
|
| 10 |
.. warning:: |
| 11 |
|
| 12 |
**Critical compatibility notice:** |
| 13 |
|
| 14 |
DataLab v1.0 introduces **major breaking changes** that are **not backward compatible** with v0.20. |
| 15 |
|
| 16 |
- **Plugins** developed for v0.20 **will not work** and must be updated |
| 17 |
- **API changes** require code modifications for all custom integrations |
| 18 |
|
| 19 |
Please read this guide carefully before upgrading to v1.0. |
| 20 |
|
| 21 |
DataLab v1.0 introduces significant architectural changes compared to v0.20. The most important change is the **externalization of signal and image processing features** into a separate library called **Sigima**. |
| 22 |
|
| 23 |
This architectural change improves modularity, testability, and enables the reuse of processing functions in other projects. However, it requires updates to existing plugins to adapt to the new API. |
| 24 |
|
| 25 |
This guide describes the steps to migrate plugins from DataLab v0.20 to v1.0. |
| 26 |
|
| 27 |
.. contents:: |
| 28 |
:local: |
| 29 |
:depth: 2 |
| 30 |
|
| 31 |
What changed in v1.0? |
| 32 |
--------------------- |
| 33 |
|
| 34 |
Major architectural changes |
| 35 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 36 |
|
| 37 |
The most significant change in DataLab v1.0 is the creation of the **Sigima library**, which now contains: |
| 38 |
|
| 39 |
- **Signal and image objects** (``SignalObj``, ``ImageObj``, ROI classes) |
| 40 |
- **Processing parameters** (all ``*Param`` classes) |
| 41 |
- **Processing functions** (``sigima.proc.signal`` and ``sigima.proc.image`` modules) |
| 42 |
- **Algorithms** for signal and image processing, or data type conversion, coordinates transformation, ... (``sigima.tools`` module) |
| 43 |
- **I/O functions** (reading and writing signals/images) |
| 44 |
- **Test data utilities** (test signal and image generation) |
| 45 |
- **Result objects** (``TableResult`` and ``GeometryResult``, replacing ``ResultProperties`` and ``ResultShape``) |
| 46 |
|
| 47 |
What remains in DataLab: |
| 48 |
|
| 49 |
- **GUI components** (panels, widgets, plot integration) |
| 50 |
- **Plugin system** (``datalab.plugins`` module) |
| 51 |
- **Application logic** (main window, configuration, project management) |
| 52 |
- **Result metadata adapters** (``TableAdapter``, ``GeometryAdapter`` for storing results in object metadata) |
| 53 |
|
| 54 |
Package renaming |
| 55 |
^^^^^^^^^^^^^^^^ |
| 56 |
|
| 57 |
The DataLab package was renamed from ``cdl`` to ``datalab`` for clarity: |
| 58 |
|
| 59 |
.. code-block:: python |
| 60 |
|
| 61 |
# v0.20 |
| 62 |
import cdl.obj |
| 63 |
import cdl.param |
| 64 |
from cdl.plugins import PluginBase |
| 65 |
|
| 66 |
# v1.0 |
| 67 |
import sigima.objects |
| 68 |
import sigima.params |
| 69 |
from datalab.plugins import PluginBase |
| 70 |
|
| 71 |
Plugin file naming convention |
| 72 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 73 |
|
| 74 |
Plugin filenames must follow the new naming convention: |
| 75 |
|
| 76 |
.. important:: |
| 77 |
|
| 78 |
Plugin files must be renamed from ``cdl_*.py`` to ``datalab_*.py``. |
| 79 |
|
| 80 |
**Examples:** |
| 81 |
|
| 82 |
- ``cdl_myplugin.py`` → ``datalab_myplugin.py`` |
| 83 |
- ``cdl_custom_filters.py`` → ``datalab_custom_filters.py`` |
| 84 |
- ``cdl_example.py`` → ``datalab_example.py`` |
| 85 |
|
| 86 |
This naming convention is required for DataLab to automatically discover and load plugins at startup. Plugins that don't follow this naming pattern will not be loaded. |
| 87 |
|
| 88 |
.. note:: |
| 89 |
|
| 90 |
The plugin discovery mechanism looks for Python files matching the pattern ``datalab_*.py`` in the plugins directory. Make sure to update your plugin filenames accordingly. |
| 91 |
|
| 92 |
New result objects |
| 93 |
^^^^^^^^^^^^^^^^^^ |
| 94 |
|
| 95 |
DataLab v1.0 introduces two new immutable result types: |
| 96 |
|
| 97 |
- **TableResult**: Replaces ``ResultProperties`` for tabular scalar results (e.g., statistics, measurements) |
| 98 |
- **GeometryResult**: Replaces ``ResultShape`` for geometric results (e.g., detected features, contours) |
| 99 |
|
| 100 |
These new result types are computation-oriented and free of application-specific logic (e.g., Qt, metadata). All metadata-related behaviors have been migrated to the DataLab application layer using **adapter classes** (``TableAdapter``, ``GeometryAdapter``). |
| 101 |
|
| 102 |
Object UUID access |
| 103 |
^^^^^^^^^^^^^^^^^^ |
| 104 |
|
| 105 |
The way to access an object's UUID has changed: |
| 106 |
|
| 107 |
.. code-block:: python |
| 108 |
|
| 109 |
# v0.20 - Direct attribute access |
| 110 |
obj_uuid = obj.uuid |
| 111 |
|
| 112 |
# v1.0 - Use helper function from datalab.objectmodel |
| 113 |
from datalab.objectmodel import get_uuid |
| 114 |
obj_uuid = get_uuid(obj) |
| 115 |
|
| 116 |
# Alternative in v1.0 - Access metadata directly |
| 117 |
obj_uuid = obj.get_metadata_option("uuid") |
| 118 |
|
| 119 |
This change applies to both ``SignalObj`` and ``ImageObj`` objects. The UUID is now stored in the object's metadata rather than as a direct attribute. |
| 120 |
|
| 121 |
.. note:: |
| 122 |
|
| 123 |
The ``get_uuid()`` function is defined in ``datalab.objectmodel``, not as a method on the object itself. Import it before use: ``from datalab.objectmodel import get_uuid``. |
| 124 |
|
| 125 |
Unified processor interface |
| 126 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 127 |
|
| 128 |
The processor methods have been unified and renamed: |
| 129 |
|
| 130 |
- Most specific ``compute_*`` methods now use the generic ``run_feature()`` method |
| 131 |
- Naming conventions updated: ``compute_11`` → ``compute_1_to_1``, ``compute_10`` → ``compute_1_to_0``, etc. |
| 132 |
|
| 133 |
Updating the imports |
| 134 |
-------------------- |
| 135 |
|
| 136 |
Import path changes |
| 137 |
^^^^^^^^^^^^^^^^^^^ |
| 138 |
|
| 139 |
The following table gives the equivalence between DataLab v0.20 and v1.0 imports. |
| 140 |
|
| 141 |
The table below shows the mapping between DataLab v0.20 and v1.0 API. For most entries, only the import statement needs to be updated. |
| 142 |
|
| 143 |
.. csv-table:: DataLab v0.20 to v1.0 Compatibility Table |
| 144 |
:file: v020_to_v100.csv |
| 145 |
:header-rows: 1 |
| 146 |
:widths: 50, 50 |
| 147 |
:delim: ; |
| 148 |
|
| 149 |
Migrating plugin code |
| 150 |
--------------------- |
| 151 |
|
| 152 |
Example 1: Simple processing plugin |
| 153 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 154 |
|
| 155 |
Here's how a simple custom filter plugin needs to be updated: |
| 156 |
|
| 157 |
**DataLab v0.20:** |
| 158 |
|
| 159 |
.. code-block:: python |
| 160 |
|
| 161 |
import numpy as np |
| 162 |
import scipy.ndimage as spi |
| 163 |
|
| 164 |
import cdl.computation.image as cpi |
| 165 |
import cdl.obj |
| 166 |
import cdl.param |
| 167 |
import cdl.plugins |
| 168 |
|
| 169 |
|
| 170 |
def weighted_average_denoise(data: np.ndarray) -> np.ndarray: |
| 171 |
"""Apply a custom denoising filter to an image.""" |
| 172 |
def filter_func(values: np.ndarray) -> float: |
| 173 |
central_pixel = values[len(values) // 2] |
| 174 |
differences = np.abs(values - central_pixel) |
| 175 |
weights = np.exp(-differences / np.mean(differences)) |
| 176 |
return np.average(values, weights=weights) |
| 177 |
return spi.generic_filter(data, filter_func, size=5) |
| 178 |
|
| 179 |
|
| 180 |
class CustomFilters(cdl.plugins.PluginBase): |
| 181 |
"""DataLab Custom Filters Plugin""" |
| 182 |
|
| 183 |
PLUGIN_INFO = cdl.plugins.PluginInfo( |
| 184 |
name="My custom filters", |
| 185 |
version="1.0.0", |
| 186 |
description="This is an example plugin", |
| 187 |
) |
| 188 |
|
| 189 |
def create_actions(self) -> None: |
| 190 |
"""Create actions""" |
| 191 |
acth = self.imagepanel.acthandler |
| 192 |
proc = self.imagepanel.processor |
| 193 |
with acth.new_menu(self.PLUGIN_INFO.name): |
| 194 |
for name, func in (("Weighted average denoise", weighted_average_denoise),): |
| 195 |
# Wrap function to handle ImageObj objects |
| 196 |
wrapped_func = cpi.Wrap11Func(func) |
| 197 |
acth.new_action( |
| 198 |
name, triggered=lambda: proc.compute_11(wrapped_func, title=name) |
| 199 |
) |
| 200 |
|
| 201 |
**DataLab v1.0:** |
| 202 |
|
| 203 |
.. code-block:: python |
| 204 |
|
| 205 |
import numpy as np |
| 206 |
import scipy.ndimage as spi |
| 207 |
import sigima.proc.image as sipi |
| 208 |
|
| 209 |
import datalab.plugins |
| 210 |
|
| 211 |
|
| 212 |
def weighted_average_denoise(data: np.ndarray) -> np.ndarray: |
| 213 |
"""Apply a custom denoising filter to an image.""" |
| 214 |
def filter_func(values: np.ndarray) -> float: |
| 215 |
central_pixel = values[len(values) // 2] |
| 216 |
differences = np.abs(values - central_pixel) |
| 217 |
weights = np.exp(-differences / np.mean(differences)) |
| 218 |
return np.average(values, weights=weights) |
| 219 |
return spi.generic_filter(data, filter_func, size=5) |
| 220 |
|
| 221 |
|
| 222 |
class CustomFilters(datalab.plugins.PluginBase): |
| 223 |
"""DataLab Custom Filters Plugin""" |
| 224 |
|
| 225 |
PLUGIN_INFO = datalab.plugins.PluginInfo( |
| 226 |
name="My custom filters", |
| 227 |
version="1.0.0", |
| 228 |
description="This is an example plugin", |
| 229 |
) |
| 230 |
|
| 231 |
def create_actions(self) -> None: |
| 232 |
"""Create actions""" |
| 233 |
acth = self.imagepanel.acthandler |
| 234 |
proc = self.imagepanel.processor |
| 235 |
with acth.new_menu(self.PLUGIN_INFO.name): |
| 236 |
for name, func in (("Weighted average denoise", weighted_average_denoise),): |
| 237 |
# Wrap function to handle ImageObj objects |
| 238 |
wrapped_func = sipi.Wrap1to1Func(func) |
| 239 |
acth.new_action( |
| 240 |
name, |
| 241 |
triggered=lambda: proc.compute_1_to_1(wrapped_func, title=name), |
| 242 |
) |
| 243 |
|
| 244 |
**Key changes:** |
| 245 |
|
| 246 |
1. ``cdl.computation.image`` → ``sigima.proc.image`` |
| 247 |
2. ``cdl.plugins`` → ``datalab.plugins`` |
| 248 |
3. ``Wrap11Func`` → ``Wrap1to1Func`` |
| 249 |
4. ``compute_11`` → ``compute_1_to_1`` |
| 250 |
|
| 251 |
Example 2: Plugin using built-in features |
| 252 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 253 |
|
| 254 |
**DataLab v0.20:** |
| 255 |
|
| 256 |
.. code-block:: python |
| 257 |
|
| 258 |
import cdl.obj |
| 259 |
import cdl.param |
| 260 |
import cdl.plugins |
| 261 |
|
| 262 |
|
| 263 |
class ExtractBlobs(cdl.plugins.PluginBase): |
| 264 |
"""DataLab Example Plugin""" |
| 265 |
|
| 266 |
PLUGIN_INFO = cdl.plugins.PluginInfo( |
| 267 |
name="Extract blobs (example)", |
| 268 |
version="1.0.0", |
| 269 |
description="This is an example plugin", |
| 270 |
) |
| 271 |
|
| 272 |
def preprocess(self) -> None: |
| 273 |
"""Preprocess image""" |
| 274 |
panel = self.imagepanel |
| 275 |
param = cdl.param.BinningParam.create(sx=2, sy=2) |
| 276 |
panel.processor.compute_binning(param) |
| 277 |
panel.processor.compute_moving_median(cdl.param.MovingMedianParam.create(n=5)) |
| 278 |
|
| 279 |
def detect_blobs(self) -> None: |
| 280 |
"""Detect circular blobs""" |
| 281 |
panel = self.imagepanel |
| 282 |
param = cdl.param.BlobOpenCVParam() |
| 283 |
param.filter_by_color = False |
| 284 |
param.min_area = 600.0 |
| 285 |
param.max_area = 6000.0 |
| 286 |
param.filter_by_circularity = True |
| 287 |
param.min_circularity = 0.8 |
| 288 |
param.max_circularity = 1.0 |
| 289 |
panel.processor.compute_blob_opencv(param) |
| 290 |
|
| 291 |
def create_actions(self) -> None: |
| 292 |
"""Create actions""" |
| 293 |
acth = self.imagepanel.acthandler |
| 294 |
with acth.new_menu(self.PLUGIN_INFO.name): |
| 295 |
acth.new_action("Preprocess image", triggered=self.preprocess) |
| 296 |
acth.new_action("Detect circular blobs", triggered=self.detect_blobs) |
| 297 |
|
| 298 |
**DataLab v1.0:** |
| 299 |
|
| 300 |
.. code-block:: python |
| 301 |
|
| 302 |
import sigima.objects |
| 303 |
import sigima.params |
| 304 |
|
| 305 |
import datalab.plugins |
| 306 |
|
| 307 |
|
| 308 |
class ExtractBlobs(datalab.plugins.PluginBase): |
| 309 |
"""DataLab Example Plugin""" |
| 310 |
|
| 311 |
PLUGIN_INFO = datalab.plugins.PluginInfo( |
| 312 |
name="Extract blobs (example)", |
| 313 |
version="1.0.0", |
| 314 |
description="This is an example plugin", |
| 315 |
) |
| 316 |
|
| 317 |
def preprocess(self) -> None: |
| 318 |
"""Preprocess image""" |
| 319 |
panel = self.imagepanel |
| 320 |
param = sigima.params.BinningParam.create(sx=2, sy=2) |
| 321 |
panel.processor.run_feature("binning", param) |
| 322 |
panel.processor.run_feature( |
| 323 |
"moving_median", sigima.params.MovingMedianParam.create(n=5) |
| 324 |
) |
| 325 |
|
| 326 |
def detect_blobs(self) -> None: |
| 327 |
"""Detect circular blobs""" |
| 328 |
panel = self.imagepanel |
| 329 |
param = sigima.params.BlobOpenCVParam() |
| 330 |
param.filter_by_color = False |
| 331 |
param.min_area = 600.0 |
| 332 |
param.max_area = 6000.0 |
| 333 |
param.filter_by_circularity = True |
| 334 |
param.min_circularity = 0.8 |
| 335 |
param.max_circularity = 1.0 |
| 336 |
panel.processor.run_feature("blob_opencv", param) |
| 337 |
|
| 338 |
def create_actions(self) -> None: |
| 339 |
"""Create actions""" |
| 340 |
acth = self.imagepanel.acthandler |
| 341 |
with acth.new_menu(self.PLUGIN_INFO.name): |
| 342 |
acth.new_action("Preprocess image", triggered=self.preprocess) |
| 343 |
acth.new_action("Detect circular blobs", triggered=self.detect_blobs) |
| 344 |
|
| 345 |
**Key changes:** |
| 346 |
|
| 347 |
1. ``cdl.param`` → ``sigima.params`` |
| 348 |
2. ``cdl.plugins`` → ``datalab.plugins`` |
| 349 |
3. ``compute_binning(param)`` → ``run_feature("binning", param)`` |
| 350 |
4. ``compute_moving_median(param)`` → ``run_feature("moving_median", param)`` |
| 351 |
5. ``compute_blob_opencv(param)`` → ``run_feature("blob_opencv", param)`` |
| 352 |
|
| 353 |
Example 3: Plugin creating objects and handling results |
| 354 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 355 |
|
| 356 |
**DataLab v0.20:** |
| 357 |
|
| 358 |
.. code-block:: python |
| 359 |
|
| 360 |
import numpy as np |
| 361 |
import cdl.obj as dlo |
| 362 |
import cdl.tests.data as test_data |
| 363 |
from cdl.computation import image as cpima |
| 364 |
from cdl.config import _ |
| 365 |
from cdl.plugins import PluginBase, PluginInfo |
| 366 |
|
| 367 |
|
| 368 |
def add_noise_to_image(src: dlo.ImageObj, p: dlo.NormalRandomParam) -> dlo.ImageObj: |
| 369 |
"""Add gaussian noise to image""" |
| 370 |
dst = cpima.dst_11(src, "add_gaussian_noise", f"mu={p.mu},sigma={p.sigma}") |
| 371 |
test_data.add_gaussian_noise_to_image(dst, p) |
| 372 |
return dst |
| 373 |
|
| 374 |
|
| 375 |
class PluginTestData(PluginBase): |
| 376 |
"""DataLab Test Data Plugin""" |
| 377 |
|
| 378 |
PLUGIN_INFO = PluginInfo( |
| 379 |
name=_("Test data"), |
| 380 |
version="1.0.0", |
| 381 |
description=_("Testing DataLab functionalities"), |
| 382 |
) |
| 383 |
|
| 384 |
def add_noise_to_image(self) -> None: |
| 385 |
"""Add noise to image""" |
| 386 |
self.imagepanel.processor.compute_11( |
| 387 |
add_noise_to_image, |
| 388 |
paramclass=dlo.NormalRandomParam, |
| 389 |
title=_("Add noise"), |
| 390 |
) |
| 391 |
|
| 392 |
def create_noisygauss_image(self) -> None: |
| 393 |
"""Create 2D noisy gauss image""" |
| 394 |
newparam = self.edit_new_image_parameters( |
| 395 |
hide_image_height=True, hide_image_type=True |
| 396 |
) |
| 397 |
if newparam is not None: |
| 398 |
obj = test_data.create_noisygauss_image(newparam, add_annotations=False) |
| 399 |
self.proxy.add_object(obj) |
| 400 |
|
| 401 |
def create_actions(self) -> None: |
| 402 |
"""Create actions""" |
| 403 |
iah = self.imagepanel.acthandler |
| 404 |
with iah.new_menu(_("Test data")): |
| 405 |
iah.new_action(_("Add noise to image"), triggered=self.add_noise_to_image) |
| 406 |
iah.new_action( |
| 407 |
_("Create 2D noisy gauss image"), |
| 408 |
triggered=self.create_noisygauss_image, |
| 409 |
select_condition="always", |
| 410 |
) |
| 411 |
|
| 412 |
**DataLab v1.0:** |
| 413 |
|
| 414 |
.. code-block:: python |
| 415 |
|
| 416 |
import numpy as np |
| 417 |
import sigima.objects |
| 418 |
import sigima.tests.data as test_data |
| 419 |
from sigima.proc import image as sipi |
| 420 |
from datalab.config import _ |
| 421 |
from datalab.plugins import PluginBase, PluginInfo |
| 422 |
|
| 423 |
|
| 424 |
def add_noise_to_image( |
| 425 |
src: sigima.objects.ImageObj, p: sigima.objects.NormalDistribution2DParam |
| 426 |
) -> sigima.objects.ImageObj: |
| 427 |
"""Add gaussian noise to image""" |
| 428 |
dst = sipi.dst_1to1(src, "add_gaussian_noise", f"mu={p.mu},sigma={p.sigma}") |
| 429 |
test_data.add_gaussian_noise_to_image(dst, p) |
| 430 |
return dst |
| 431 |
|
| 432 |
|
| 433 |
class PluginTestData(PluginBase): |
| 434 |
"""DataLab Test Data Plugin""" |
| 435 |
|
| 436 |
PLUGIN_INFO = PluginInfo( |
| 437 |
name=_("Test data"), |
| 438 |
version="1.0.0", |
| 439 |
description=_("Testing DataLab functionalities"), |
| 440 |
) |
| 441 |
|
| 442 |
def add_noise_to_image(self) -> None: |
| 443 |
"""Add noise to image""" |
| 444 |
self.imagepanel.processor.compute_1_to_1( |
| 445 |
add_noise_to_image, |
| 446 |
paramclass=sigima.objects.NormalDistribution2DParam, |
| 447 |
title=_("Add noise"), |
| 448 |
) |
| 449 |
|
| 450 |
def create_noisy_gaussian_image(self) -> None: |
| 451 |
"""Create 2D noisy gauss image""" |
| 452 |
newparam = self.edit_new_image_parameters( |
| 453 |
hide_height=True, hide_type=True |
| 454 |
) |
| 455 |
if newparam is not None: |
| 456 |
obj = test_data.create_noisy_gaussian_image(newparam, add_annotations=False) |
| 457 |
self.proxy.add_object(obj) |
| 458 |
|
| 459 |
def create_actions(self) -> None: |
| 460 |
"""Create actions""" |
| 461 |
iah = self.imagepanel.acthandler |
| 462 |
with iah.new_menu(_("Test data")): |
| 463 |
iah.new_action(_("Add noise to image"), triggered=self.add_noise_to_image) |
| 464 |
iah.new_action( |
| 465 |
_("Create 2D noisy gaussian image"), |
| 466 |
triggered=self.create_noisy_gaussian_image, |
| 467 |
select_condition="always", |
| 468 |
) |
| 469 |
|
| 470 |
**Key changes:** |
| 471 |
|
| 472 |
1. ``cdl.obj`` → ``sigima.objects`` |
| 473 |
2. ``cdl.tests.data`` → ``sigima.tests.data`` |
| 474 |
3. ``cdl.computation.image`` → ``sigima.proc.image`` |
| 475 |
4. ``dst_11`` → ``dst_1to1`` |
| 476 |
5. ``compute_11`` → ``compute_1_to_1`` |
| 477 |
6. ``dlo.NormalRandomParam`` → ``sigima.objects.NormalDistribution2DParam`` |
| 478 |
7. ``create_noisygauss_image`` → ``create_noisy_gaussian_image`` |
| 479 |
8. ``hide_image_height`` → ``hide_height``, ``hide_image_type`` → ``hide_type`` |
| 480 |
|
| 481 |
Working with result objects |
| 482 |
--------------------------- |
| 483 |
|
| 484 |
Changes to result objects |
| 485 |
^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 486 |
|
| 487 |
The result object architecture has been completely redesigned in v1.0: |
| 488 |
|
| 489 |
**v0.20 Result Objects:** |
| 490 |
|
| 491 |
- ``ResultProperties``: For tabular results (statistics, etc.) |
| 492 |
- ``ResultShape``: For geometric results (detected features, etc.) |
| 493 |
- These objects contained Qt-specific code and metadata handling logic |
| 494 |
- Methods like ``add_to(obj)`` and ``from_metadata_entry()`` were part of the result class |
| 495 |
|
| 496 |
**v1.0 Result Objects:** |
| 497 |
|
| 498 |
- ``TableResult``: Immutable, computation-oriented table results |
| 499 |
- ``GeometryResult``: Immutable, computation-oriented geometry results |
| 500 |
- No Qt or metadata dependencies |
| 501 |
- Metadata handling moved to DataLab adapter classes |
| 502 |
|
| 503 |
Using TableResult and GeometryResult |
| 504 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 505 |
|
| 506 |
In v1.0, when your plugin receives results from ``compute_1_to_0`` operations, you'll work with ``TableResult`` or ``GeometryResult`` objects. |
| 507 |
|
| 508 |
**Example 1: Computing signal dynamic parameters (TableResult)** |
| 509 |
|
| 510 |
This example shows how to compute dynamic parameters (ENOB, SINAD, THD, etc.) and work with the resulting ``TableResult``: |
| 511 |
|
| 512 |
.. code-block:: python |
| 513 |
|
| 514 |
import sigima.params |
| 515 |
import sigima.proc.signal |
| 516 |
from datalab.adapters_metadata import TableAdapter |
| 517 |
|
| 518 |
# Get the current signal from the panel |
| 519 |
panel = self.signalpanel |
| 520 |
obj = panel.objview.get_current_object() |
| 521 |
|
| 522 |
# Compute dynamic parameters |
| 523 |
param = sigima.params.DynamicParam.create(full_scale=1.0) |
| 524 |
table = sigima.proc.signal.dynamic_parameters(obj, param) |
| 525 |
|
| 526 |
# Access specific values from the table |
| 527 |
enob = table["enob"][0] # Effective Number of Bits |
| 528 |
sinad = table["sinad"][0] # Signal-to-Noise and Distortion Ratio |
| 529 |
thd = table["thd"][0] # Total Harmonic Distortion |
| 530 |
|
| 531 |
# Convert to dictionary for easy access |
| 532 |
result_dict = table.as_dict() |
| 533 |
print(f"ENOB: {result_dict['enob']}") |
| 534 |
print(f"SINAD: {result_dict['sinad']} dB") |
| 535 |
|
| 536 |
# Store result in object metadata using adapter |
| 537 |
adapter = TableAdapter(table) |
| 538 |
adapter.add_to(obj) |
| 539 |
|
| 540 |
# Convert to pandas DataFrame for further processing |
| 541 |
df = table.to_dataframe() |
| 542 |
print(df) |
| 543 |
|
| 544 |
**Example 2: Detecting image peaks (GeometryResult)** |
| 545 |
|
| 546 |
This example shows how to detect peaks in an image and work with the resulting ``GeometryResult``: |
| 547 |
|
| 548 |
.. code-block:: python |
| 549 |
|
| 550 |
import sigima.params |
| 551 |
import sigima.proc.image |
| 552 |
from datalab.adapters_metadata import GeometryAdapter |
| 553 |
|
| 554 |
# Get the current image from the panel |
| 555 |
panel = self.imagepanel |
| 556 |
obj = panel.objview.get_current_object() |
| 557 |
|
| 558 |
# Configure peak detection parameters |
| 559 |
param = sigima.params.Peak2DDetectionParam.create( |
| 560 |
size=50, # Neighborhood size |
| 561 |
threshold=0.5, # Relative threshold |
| 562 |
create_rois=True # Create ROI for each peak |
| 563 |
) |
| 564 |
|
| 565 |
# Compute peak detection |
| 566 |
geometry = sigima.proc.image.peak_detection(obj, param) |
| 567 |
|
| 568 |
# Access geometry data |
| 569 |
coords = geometry.coords # numpy array of shape (n_peaks, 2) |
| 570 |
n_peaks = len(coords) |
| 571 |
print(f"Detected {n_peaks} peaks") |
| 572 |
|
| 573 |
# Iterate over detected peaks |
| 574 |
for i, (x, y) in enumerate(coords): |
| 575 |
print(f"Peak {i+1}: x={x:.2f}, y={y:.2f}") |
| 576 |
|
| 577 |
# Check geometry kind |
| 578 |
from sigima.objects import KindShape |
| 579 |
assert geometry.kind == KindShape.POINT |
| 580 |
|
| 581 |
# Store geometry in object metadata using adapter |
| 582 |
adapter = GeometryAdapter(geometry) |
| 583 |
adapter.add_to(obj) |
| 584 |
|
| 585 |
**Example 3: Computing bandwidth (GeometryResult with segments)** |
| 586 |
|
| 587 |
This example shows how to compute signal bandwidth, which returns a segment geometry: |
| 588 |
|
| 589 |
.. code-block:: python |
| 590 |
|
| 591 |
import sigima.proc.signal |
| 592 |
from datalab.adapters_metadata import GeometryAdapter |
| 593 |
|
| 594 |
# Get the current signal from the panel |
| 595 |
panel = self.signalpanel |
| 596 |
obj = panel.objview.get_current_object() |
| 597 |
|
| 598 |
# Compute -3dB bandwidth |
| 599 |
geometry = sigima.proc.signal.bandwidth_3db(obj) |
| 600 |
|
| 601 |
# Access segment coordinates [x0, y0, x1, y1] |
| 602 |
x0, y0, x1, y1 = geometry.coords[0] |
| 603 |
print(f"Bandwidth segment: ({x0}, {y0}) to ({x1}, {y1})") |
| 604 |
|
| 605 |
# Calculate bandwidth length |
| 606 |
bandwidth = geometry.segments_lengths()[0] |
| 607 |
print(f"Bandwidth@-3dB: {bandwidth:.2f}") |
| 608 |
|
| 609 |
# Store in metadata |
| 610 |
adapter = GeometryAdapter(geometry) |
| 611 |
adapter.add_to(obj) |
| 612 |
|
| 613 |
Retrieving results from metadata |
| 614 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 615 |
|
| 616 |
To retrieve results stored in object metadata: |
| 617 |
|
| 618 |
.. code-block:: python |
| 619 |
|
| 620 |
from datalab.adapters_metadata import TableAdapter, GeometryAdapter |
| 621 |
|
| 622 |
obj = ... # Some signal or image object |
| 623 |
|
| 624 |
# Iterate over all table results |
| 625 |
for adapter in TableAdapter.iterate_from_obj(obj): |
| 626 |
result = adapter.result # TableResult instance |
| 627 |
title = adapter.title |
| 628 |
df = result.to_dataframe() |
| 629 |
|
| 630 |
# Iterate over all geometry results |
| 631 |
for adapter in GeometryAdapter.iterate_from_obj(obj): |
| 632 |
result = adapter.result # GeometryResult instance |
| 633 |
title = adapter.title |
| 634 |
coords = result.coords |
| 635 |
|
| 636 |
Processor method changes |
| 637 |
------------------------ |
| 638 |
|
| 639 |
The processor interface has been unified in v1.0. Most specific ``compute_*`` methods now use the generic ``run_feature()`` method. |
| 640 |
|
| 641 |
Using run_feature() |
| 642 |
^^^^^^^^^^^^^^^^^^^ |
| 643 |
|
| 644 |
The ``run_feature()`` method is a unified interface for running processing features: |
| 645 |
|
| 646 |
.. code-block:: python |
| 647 |
|
| 648 |
# v1.0 - Generic interface |
| 649 |
proc = panel.processor |
| 650 |
|
| 651 |
# Simple features (no parameters) |
| 652 |
proc.run_feature("normalize") |
| 653 |
proc.run_feature("fft") |
| 654 |
|
| 655 |
# Features with parameters |
| 656 |
param = sigima.params.GaussianParam.create(sigma=2.0) |
| 657 |
proc.run_feature("gaussian_filter", param) |
| 658 |
|
| 659 |
# Features with direct function reference |
| 660 |
import sigima.proc.image as sipi |
| 661 |
proc.run_feature(sipi.normalize) |
| 662 |
proc.run_feature(sipi.gaussian_filter, param) |
| 663 |
|
| 664 |
Method renaming |
| 665 |
^^^^^^^^^^^^^^^ |
| 666 |
|
| 667 |
Several processor methods have been renamed for consistency: |
| 668 |
|
| 669 |
.. list-table:: |
| 670 |
:header-rows: 1 |
| 671 |
:widths: 50 50 |
| 672 |
|
| 673 |
* - v0.20 |
| 674 |
- v1.0 |
| 675 |
* - ``compute_11(func, ...)`` |
| 676 |
- ``compute_1_to_1(func, ...)`` |
| 677 |
* - ``compute_10(func, ...)`` |
| 678 |
- ``compute_1_to_0(func, ...)`` |
| 679 |
* - ``compute_n1(func, ...)`` |
| 680 |
- ``compute_n_to_1(func, ...)`` |
| 681 |
* - ``compute_1n(func, ...)`` |
| 682 |
- ``compute_1_to_n(func, ...)`` |
| 683 |
* - ``compute_21(func, ...)`` |
| 684 |
- ``compute_2_to_1(func, ...)`` |
| 685 |
|
| 686 |
Built-in features using run_feature |
| 687 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 688 |
|
| 689 |
Most built-in processing features that previously had dedicated ``compute_*`` methods now use ``run_feature()``: |
| 690 |
|
| 691 |
.. code-block:: python |
| 692 |
|
| 693 |
# v0.20 |
| 694 |
proc.compute_binning(param) |
| 695 |
proc.compute_moving_median(param) |
| 696 |
proc.compute_blob_opencv(param) |
| 697 |
proc.compute_gaussian_filter(param) |
| 698 |
|
| 699 |
# v1.0 |
| 700 |
proc.run_feature("binning", param) |
| 701 |
proc.run_feature("moving_median", param) |
| 702 |
proc.run_feature("blob_opencv", param) |
| 703 |
proc.run_feature("gaussian_filter", param) |
| 704 |
|
| 705 |
Some complex features still have dedicated methods: |
| 706 |
|
| 707 |
.. code-block:: python |
| 708 |
|
| 709 |
# These still use dedicated methods in v1.0 |
| 710 |
proc.compute_roi_extraction(roi) |
| 711 |
proc.compute_multigaussianfit() |
| 712 |
proc.compute_peak_detection(param) |
| 713 |
|
| 714 |
Testing your plugin |
| 715 |
------------------- |
| 716 |
|
| 717 |
After migration, thoroughly test your plugin: |
| 718 |
|
| 719 |
1. **Import checks**: Verify all imports work correctly |
| 720 |
2. **Parameter creation**: Check that parameter classes are correctly instantiated |
| 721 |
3. **Object creation**: Test signal/image object creation functions |
| 722 |
4. **Processing operations**: Verify all processing features work as expected |
| 723 |
5. **Result handling**: Check that results are correctly generated and stored |
| 724 |
6. **GUI integration**: Test that menus and actions appear correctly |
| 725 |
|
| 726 |
Common issues and solutions |
| 727 |
--------------------------- |
| 728 |
|
| 729 |
Import errors |
| 730 |
^^^^^^^^^^^^^ |
| 731 |
|
| 732 |
**Problem**: ``ModuleNotFoundError: No module named 'cdl'`` |
| 733 |
|
| 734 |
**Solution**: Update all imports from ``cdl.*`` to either ``datalab.*`` or ``sigima.*`` depending on the module. |
| 735 |
|
| 736 |
Attribute errors on processor |
| 737 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 738 |
|
| 739 |
**Problem**: ``AttributeError: 'ImageProcessor' object has no attribute 'compute_binning'`` |
| 740 |
|
| 741 |
**Solution**: Replace ``compute_*`` method calls with ``run_feature()`` calls: |
| 742 |
|
| 743 |
.. code-block:: python |
| 744 |
|
| 745 |
# Wrong (v0.20 style) |
| 746 |
proc.compute_binning(param) |
| 747 |
|
| 748 |
# Correct (v1.0 style) |
| 749 |
proc.run_feature("binning", param) |
| 750 |
|
| 751 |
Result object incompatibility |
| 752 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 753 |
|
| 754 |
**Problem**: ``AttributeError: 'TableResult' object has no attribute 'add_to'`` |
| 755 |
|
| 756 |
**Solution**: Use adapter classes for metadata operations: |
| 757 |
|
| 758 |
.. code-block:: python |
| 759 |
|
| 760 |
# Wrong (v0.20 style) |
| 761 |
result.add_to(obj) |
| 762 |
|
| 763 |
# Correct (v1.0 style) |
| 764 |
from datalab.adapters_metadata import TableAdapter |
| 765 |
TableAdapter(result).add_to(obj) |
| 766 |
|
| 767 |
Missing parameters |
| 768 |
^^^^^^^^^^^^^^^^^^ |
| 769 |
|
| 770 |
**Problem**: ``ImportError: cannot import name 'SomeParam' from 'datalab'`` |
| 771 |
|
| 772 |
**Solution**: Import parameters from ``sigima.params`` instead of ``cdl.param``: |
| 773 |
|
| 774 |
.. code-block:: python |
| 775 |
|
| 776 |
# Wrong |
| 777 |
from cdl.param import GaussianParam |
| 778 |
|
| 779 |
# Correct |
| 780 |
from sigima.params import GaussianParam |
| 781 |
|
| 782 |
Additional resources |
| 783 |
-------------------- |
| 784 |
|
| 785 |
- `DataLab v1.0 documentation <https://datalab-platform.com/>`_ |
| 786 |
- `Sigima documentation <https://sigima.readthedocs.io/en/latest/>`_ |
| 787 |
- `Plugin examples <https://github.com/DataLab-Platform/DataLab/tree/main/plugins/examples>`_ |
| 788 |
- :doc:`DataLab API reference <api>` |
| 789 |
- `Sigima API reference <https://sigima.readthedocs.io/en/latest/api/index.html>`_ |
| 790 |
|
| 791 |
Getting help |
| 792 |
------------ |
| 793 |
|
| 794 |
If you encounter issues during migration: |
| 795 |
|
| 796 |
1. Check the `GitHub issue tracker <https://github.com/DataLab-Platform/DataLab/issues>`_ |
| 797 |
2. Consult the built-in plugin examples in the ``datalab/plugins`` directory |