Panel#

The datalab.gui.panel package provides the panel objects for signals and images.

Three types of panels are available:

Signal and Image Panels are called Data Panels and are used to display and handle signals and images in the main window of DataLab.

Data Panels rely on the datalab.gui.panel.base.ObjectProp class (managing the object properties) and a set of modules to handle the GUI features:

The Macro Panel is used to display and run macros. It relies on the datalab.gui.macroeditor module to handle the macro edition and execution.

Base features#

datalab.gui.panel.base.collect_metadata_keys(objs: Sequence[TypeObj]) → list[tuple[str, str]][source]#

Return the user-visible scalar metadata keys of objects.

Parameters:

objs – objects to inspect

Returns:

Sorted (key, description) pairs, the description showing an example

value; internal options, ROIs and analysis results are excluded.

datalab.gui.panel.base.is_plot_item_serializable(item: Any) → bool[source]#

Return True if plot item is serializable

datalab.gui.panel.base.is_hdf5_file(filename: str, check_content: bool = False) → bool[source]#

Return True if filename has an HDF5 extension or is an HDF5 file.

Parameters:
  • filename – Path to the file to check

  • check_content – If True, also attempts to open the file to verify it’s a valid HDF5 file. If False, only checks the file extension.

Returns:

True if the file is (likely) an HDF5 file, False otherwise.

class datalab.gui.panel.base.ObjectProp(panel: BaseDataPanel, objclass: SignalObj | ImageObj)[source]#

Object handling panel properties

Parameters:
  • panel – parent data panel

  • objclass – class of the object handled by the panel (SignalObj or ImageObj)

display_analysis_parameters(obj: SignalObj | ImageObj) → bool[source]#

Set analysis parameter label.

Parameters:

obj – Signal or Image object

Returns:

True if analysis parameters were found and displayed, False otherwise.

display_processing_history(obj: SignalObj | ImageObj) → bool[source]#

Display the provenance of an object in the Provenance tab.

When the workspace ledger records a production, an old record or an analysis of the object, the provenance view is shown (see datalab.widgets.provenance.ProvenanceWidget); otherwise, the history rebuilt from the processing metadata of the object is shown.

Parameters:

obj – Signal or Image object

Returns:

True if a history was found and displayed, False otherwise.

refresh_history() → None[source]#

Show again the History of the current object (ledger read again).

Called when activities were recorded or the workspace changed: results of data checks and verifications shown before are dropped.

update_properties_from(obj: SignalObj | ImageObj | None = None, force_tab: Literal['creation', 'processing', 'analysis', None] | None = None) → None[source]#

Update properties panel (properties, creation, processing) from object.

Parameters:
  • obj – Signal or Image object

  • force_tab – Force a specific tab to be current

keeping_tab(kind: str) → Generator[None, None, None][source]#

Keep the tab of kind current when another object is shown meanwhile.

For navigation from a tab to another object (e.g. from the provenance of a result to one of its inputs), which otherwise shows Properties.

mark_as_newly_created(obj: SignalObj | ImageObj) → None[source]#

Mark object to show Creation tab on next selection.

Parameters:

obj – Object to mark

mark_as_freshly_processed(obj: SignalObj | ImageObj) → None[source]#

Mark object to show Processing tab on next selection.

Parameters:

obj – Object to mark

mark_as_fresh_analysis(obj: SignalObj | ImageObj) → None[source]#

Mark object to show Analysis tab on next selection.

Parameters:

obj – Object to mark

get_changed_properties() → dict[str, Any][source]#

Get dictionary of properties that have changed from original values.

Returns:

Dictionary mapping property names to their new values, containing only the properties that were modified by the user.

update_original_values() → None[source]#

Update the stored original values to the current dataset values.

This should be called after applying changes to reset the baseline for detecting future changes.

setup_creation_tab(obj: SignalObj | ImageObj, set_current: bool = False) → bool[source]#

Setup the Creation tab with parameter editor for interactive object creation.

Parameters:
  • obj – Signal or Image object

  • set_current – If True, set the Creation tab as current after creation

Returns:

True if Creation tab was set up, False otherwise

setup_legacy_creation_tab(obj: SignalObj | ImageObj, error: str, set_current: bool = False) → bool[source]#

Setup actions for explicitly converting historical peak parameters.

setup_invalid_creation_tab(obj: SignalObj | ImageObj, error: str, set_current: bool = False) → bool[source]#

Show a read-only state for invalid creation metadata.

convert_current_creation_parameters() → None[source]#

Convert the current object’s historical peak creation parameters.

apply_creation_parameters() → None[source]#

Apply creation parameters: recreate object with updated parameters.

setup_processing_tab(obj: SignalObj | ImageObj, reset_params: bool = True, set_current: bool = False) → bool[source]#

Setup the Processing tab to show and apply again a processing.

The call that produced the object is restored (see datalab.processingcall.resolve_processing_call()): 1-to-1, 2-to-1 and n-to-1 processing, with every input. Parameters are edited in a parameter editor; a processing without editable parameters gets an explicit Reapply button. When the processing cannot be applied again (deleted input, unavailable operation…), the reason is shown.

Parameters:
  • obj – Signal or Image object

  • reset_params – If True, call update_from_obj() to reset parameters from source object. If False, use parameters as stored in metadata.

  • set_current – If True, set the Processing tab as current after creation

Returns:

True if Processing tab was set up, False otherwise

reapply_processing(obj: SignalObj | ImageObj | None = None) → None[source]#

Apply again the processing of an object without editable parameters.

Parameters:

obj – Processed object (default: the object of the Processing tab).

setup_analysis_tab(obj: SignalObj | ImageObj, set_current: bool = False) → bool[source]#

Setup the Analysis tab with parameter editor for re-running analysis.

This tab lets the user edit the parameters of a 1-to-0 analysis operation (peak detection, FWHM, segments, etc.) and re-run it in place with the modified parameters.

Parameters:
  • obj – Signal or Image object

  • set_current – If True, set the Analysis tab as current after creation

Returns:

True if Analysis tab was set up, False otherwise

apply_analysis_parameters(obj: SignalObj | ImageObj | None = None, interactive: bool = True, param: DataSet | None = None) → bool[source]#

Apply analysis parameters: re-run the 1-to-0 analysis in place.

Parameters:
  • obj – Signal or Image object to re-analyze. If None, uses the current analysis object.

  • interactive – If True, show error messages in the UI.

  • param – Explicit analysis parameters to apply. When None (default), fall back to the editor dataset or the stored analysis parameters.

apply_processing_parameters(obj: SignalObj | ImageObj | None = None, interactive: bool = True, param: DataSet | None = None) → ProcessingReport[source]#

Apply processing parameters by recomputing the existing object in place.

Parameters:
  • obj – Signal or Image object to reprocess. If None, uses the current object.

  • interactive – If True, show progress and error messages in the UI.

  • param – Explicit processing parameters to apply. When provided, this takes precedence and makes the call independent of the Processing tab editor state (used e.g. by programmatic recompute paths). When None (default), fall back to the editor dataset or the stored processing parameters.

Returns:

ProcessingReport with success status, object UUID, and optional message.

apply_recomputed_object_in_place(obj: SignalObj | ImageObj, new_obj: SignalObj | ImageObj, proc_params: ProcessingParameters) → None[source]#

Apply a freshly recomputed object onto obj in place.

Copies scientific data, coordinates, labels and units while preserving metadata, annotations and display settings. Only processing metadata changes.

Parameters:
  • obj – Existing object to update in place (identity preserved).

  • new_obj – Freshly recomputed object providing title + data.

  • proc_params – Updated processing parameters to store on obj.

class datalab.gui.panel.base.H5ImportBatch(panel: BaseDataPanel, reference_remap: dict[str, str], objects: list[TypeObj], groups: list[ObjectGroup])[source]#

Objects and UUID remapping created by one native HDF5 import.

apply_reference_remap(reference_remap: dict[str, str], title_remap: dict[str, str]) → None[source]#

Remap title and processing references in this imported batch.

Parameters:
  • reference_remap – serialized UUID to imported UUID mapping

  • title_remap – serialized title reference to imported title reference

classmethod finalize_imports(batches: list[H5ImportBatch], refresh_panels: bool = False) → None[source]#

Apply the combined signal/image UUID remapping to imported batches.

class datalab.gui.panel.base.AbstractPanelMeta(name, bases, namespace, /, **kwargs)[source]#

Mixed metaclass to avoid conflicts

class datalab.gui.panel.base.AbstractPanel(parent)[source]#

Object defining DataLab panel interface, based on a vertical QSplitter widget

A panel handle an object list (objects are signals, images, macros…). Each object must implement datalab.gui.ObjItf interface

get_serializable_name(obj: ObjItf) → str[source]#

Return serializable name of object

serialize_object_to_hdf5(obj: ObjItf, writer: NativeH5Writer) → None[source]#

Serialize object to HDF5 file

deserialize_object_from_hdf5(reader: NativeH5Reader, name: str, reset_all: bool = False) → ObjItf[source]#

Deserialize object from a HDF5 file

Parameters:
  • reader – HDF5 reader

  • name – Object name in HDF5 file

  • reset_all – If True, preserve original UUIDs (workspace reload). If False, regenerate only UUIDs that conflict with existing objects (object import).

abstractmethod serialize_to_hdf5(writer: NativeH5Writer) → None[source]#

Serialize whole panel to a HDF5 file

abstractmethod deserialize_from_hdf5(reader: NativeH5Reader, reset_all: bool = False) → H5ImportBatch | None[source]#

Deserialize whole panel from a HDF5 file

Parameters:
  • reader – HDF5 reader

  • reset_all – If True, preserve original UUIDs (workspace reload). If False, regenerate only UUIDs that conflict with existing objects (object import).

abstractmethod create_object() → ObjItf[source]#

Create and return object

abstractmethod add_object(obj: ObjItf) → None[source]#

Add object to panel

abstractmethod remove_all_objects()[source]#

Remove all objects

class datalab.gui.panel.base.PasteMetadataParam(title: str | None = None, comment: str | None = None, icon: str = '', readonly: bool = False, skip_defaults: bool = False)[source]#

Paste metadata parameters

classmethod for_dialog() → PasteMetadataParam[source]#

Create parameters with the metadata paste dialog’s explanation.

class datalab.gui.panel.base.NonModalInfoDialog(parent: QWidget, title: str, text: str)[source]#

Non-modal information message box with selectable text.

This widget displays an information message in a message dialog box, allowing users to select and copy the text content.

class datalab.gui.panel.base.SaveToDirectoryGUIParam(objs: list[TypeObj] | None = None, extensions: list[str] | None = None, labels: list[str] | None = None)[source]#

Save to directory parameters

on_button_click(_item: ButtonItem, _value: None, parent: QWidget) → None[source]#

Help button callback.

get_extension_choices(_item=None, _value=None)[source]#

Return list of available extensions for choice item.

build_filenames(objs: list[TypeObj] | None = None) → list[str][source]#

Build filenames according to current parameters.

generate_filepath_obj_pairs(objs: list[TypeObj]) → Generator[tuple[str, TypeObj], None, None][source]#

Iterate over (filepath, object) pairs to be saved.

update_preview(_item=None, _value=None) → None[source]#

Update preview.

class datalab.gui.panel.base.AddMetadataParam(objs: list[TypeObj] | None = None, known_keys: Sequence[tuple[str, str]] | None = None)[source]#

Add metadata parameters

Parameters:
  • objs – objects receiving the metadata item

  • known_keys – suggested (key, description) pairs

on_help_button_click(_item: ButtonItem, _value: None, parent: QWidget) → None[source]#

Help button callback.

get_known_key_choices(_item=None, _value=None)[source]#

Return the suggested metadata keys.

on_known_key_changed(_item=None, value=None) → None[source]#

Copy the selected suggestion into the metadata key.

get_conversion_choices(_item=None, _value=None)[source]#

Return list of available conversion choices.

build_values(objs: list[TypeObj] | None = None) → list[str | float | int | bool | None][source]#

Build values according to current parameters.

Returns:

One value per object; None for objects left unchanged because

the extraction pattern does not match.

Raises:

ValueError – If the extraction pattern is invalid or does not match (when asked to report it), or if a value cannot be converted.

update_preview(_item=None, _value=None) → None[source]#

Update preview.

class datalab.gui.panel.base.BaseDataPanel(parent: QWidget)[source]#

Object handling the item list, the selected item properties and plot

abstractmethod static get_roi_class() → Type[TypeROI][source]#

Return ROI class

abstractmethod static get_roieditor_class() → Type[TypeROIEditor][source]#

Return ROI editor class

closeEvent(event)[source]#

Reimplement QMainWindow method

plot_item_parameters_changed(item: CurveItem | MaskedXYImageItem | LabelItem) → None[source]#

Plot items changed: update metadata of all objects from plot items

plot_item_moved(item: LabelItem, x0: float, y0: float, x1: float, y1: float) → None[source]#

Plot item moved: update metadata of all objects from plot items

Parameters:
  • item – Plot item

  • x0 – new x0 coordinate

  • y0 – new y0 coordinate

  • x1 – new x1 coordinate

  • y1 – new y1 coordinate

serialize_object_to_hdf5(obj: TypeObj, writer: NativeH5Writer) → None[source]#

Serialize object to HDF5 file

serialize_to_hdf5(writer: NativeH5Writer) → None[source]#

Serialize whole panel to a HDF5 file

deserialize_from_hdf5(reader: NativeH5Reader, reset_all: bool = False) → H5ImportBatch[source]#

Deserialize whole panel from a HDF5 file

Parameters:
  • reader – HDF5 reader

  • reset_all – If True, preserve original UUIDs (workspace reload). If False, regenerate only UUIDs that conflict with existing objects (object import).

create_object() → TypeObj[source]#

Create object (signal or image)

Returns:

SignalObj or ImageObj object

add_object(obj: TypeObj, group_id: str | None = None, set_current: bool = True) → None[source]#

Add object

Parameters:
  • obj – SignalObj or ImageObj object

  • group_id – group id to which the object belongs. If None or empty string, the object is added to the current group.

  • set_current – if True, set the added object as current

add_objects(objects: Sequence[TypeObj], group_id: str | None = None, set_current: bool = True) → None[source]#

Add multiple objects atomically.

Parameters:
  • objects – Objects to add, in insertion order

  • group_id – Group ID to which the objects belong. If None or empty, the objects are added to the current group.

  • set_current – If True, set the last added object as current

set_object(obj: TypeObj) → None[source]#

Update an existing object in-place with data from obj.

The existing object is identified by UUID (carried by obj from a previous get_object() call). All data attributes are copied from obj to the existing object while preserving internal metadata (number, group membership).

Parameters:

obj – SignalObj or ImageObj with the same UUID as an existing object.

Raises:

KeyError – if no object with matching UUID is found

remove_all_objects() → None[source]#

Remove all objects

setup_panel() → None[source]#

Setup panel

refresh_plot(what: str, update_items: bool = True, force: bool = False, only_visible: bool = True, only_existing: bool = False) → None[source]#

Refresh plot.

Parameters:
  • what – string describing the objects to refresh. Valid values are “selected” (refresh the selected objects), “all” (refresh all objects), “existing” (refresh existing plot items), or an object uuid.

  • update_items – if True, update the items. If False, only show the items (do not update them). Defaults to True.

  • force – if True, force refresh even if auto refresh is disabled. Defaults to False.

  • only_visible – if True, only refresh visible items. Defaults to True. Visible items are the ones that are not hidden by other items or the items except the first one if the option “Show first only” is enabled. This is useful for images, where the last image is the one that is shown. If False, all items are refreshed.

  • only_existing – if True, only refresh existing items. Defaults to False. Existing items are the ones that have already been created and are associated to the object uuid. If False, create new items for the objects that do not have an item yet.

Raises:

ValueError – if what is not a valid value

manual_refresh() → None[source]#

Manual refresh

get_category_actions(category: ActionCategory) → list[QAction][source]#

Return actions for category

get_context_menu() → QMenu[source]#

Update and return context menu

add_group(title: str, select: bool = False, group_uuid: str | None = None) → ObjectGroup[source]#

Add group

Parameters:
  • title – group title

  • select – if True, select the group in the tree view. Defaults to False.

  • group_uuid – optional group UUID. If None, a new UUID is generated.

Returns:

Created group object

duplicate_object() → None[source]#

Duplication signal/image object

copy_metadata() → None[source]#

Copy object metadata

paste_metadata(param: PasteMetadataParam | None = None) → None[source]#

Paste metadata to selected object(s)

get_known_metadata_keys(objs: Sequence[TypeObj]) → list[tuple[str, str]][source]#

Return the metadata keys suggested by the Add metadata dialog.

Parameters:

objs – selected objects

Returns:

the keys found on the objects, then the

keys expected by the methods of application plugins

Return type:

(key, description) pairs

add_metadata(param: AddMetadataParam | None = None) → None[source]#

Add metadata item to selected object(s)

Parameters:

param – Add metadata parameters

copy_roi(roi_data=None) → None[source]#

Copy regions of interest

Parameters:

roi_data – ROI snapshot kept for legacy session replay compatibility. When None (interactive use), the ROI is read from the currently selected object.

paste_roi(roi_data=None) → None[source]#

Paste regions of interest

Parameters:

roi_data – ROI snapshot kept for legacy session replay compatibility. When None (interactive use), the clipboard populated by copy_roi() is used.

remove_object(force: bool = False) → None[source]#

Remove signal/image object

Parameters:

force – if True, remove object without confirmation. Defaults to False.

delete_all_objects() → None[source]#

Confirm before removing all objects

delete_metadata(refresh_plot: bool = True, keep_roi: bool | None = None) → None[source]#

Delete metadata of selected objects

Parameters:
  • refresh_plot – Refresh plot. Defaults to True.

  • keep_roi – Keep regions of interest, if any. Defaults to None (ask user).

add_annotations_from_items(items: list, refresh_plot: bool = True) → None[source]#

Add object annotations (annotation plot items).

Parameters:
  • items – annotation plot items

  • refresh_plot – refresh plot. Defaults to True.

update_metadata_view_settings() → None[source]#

Update metadata view settings

copy_titles_to_clipboard() → None[source]#

Copy object titles to clipboard (for reproducibility)

new_group() → None[source]#

Create a new group

rename_selected_object_or_group(new_name: str | None = None) → None[source]#

Rename selected object or group

Parameters:

new_name – new name (default: None, i.e. ask user)

abstractmethod get_newparam_from_current(newparam: NewSignalParam | NewImageParam | None = None) → NewSignalParam | NewImageParam | None[source]#

Get new object parameters from the current object.

Parameters:

newparam – new object parameters. If None, create a new one.

Returns:

New object parameters

abstractmethod new_object(param: NewSignalParam | NewImageParam | None = None, edit: bool = False, add_to_panel: bool = True) → TypeObj | None[source]#

Create a new object (signal/image).

Parameters:
  • param – new object parameters

  • edit – Open a dialog box to edit parameters (default: False). When False, the object is created with default parameters and creation parameters are stored in metadata for interactive editing.

  • add_to_panel – Add object to panel (default: True)

Returns:

New object

set_current_object_title(title: str) → None[source]#

Set current object title

edit_import_parameters(filenames: list[str], param: DataSet | None = None) → list[tuple[str, DataSet | None]] | None[source]#

Return files to import with their optional format-specific parameters.

Parameters:
  • filenames – File names to import.

  • param – Optional import parameters applied to every file requiring parameters, without showing any dialog.

Returns:

File names with aligned import parameters, without the files whose parameter dialog was cancelled, or None if the whole import was cancelled.

Raises:

TypeError – If param is given, as this panel has no import parameters.

apply_import_parameters(objs: list[SignalObj] | list[ImageObj], param: DataSet | None) → None[source]#

Apply optional import parameters to newly read objects.

Parameters:
  • objs – Imported objects.

  • param – Optional format-specific import parameters.

edit_export_parameters(obj: TypeObj, filename: str) → tuple[bool, ImageExportParam | None][source]#

Edit optional object export parameters.

Parameters:
  • obj – Object to export

  • filename – File name

Returns:

A tuple containing the confirmation state and optional export parameters

write_object_to_file(obj: TypeObj, filename: str, param: ImageExportParam | None = None) → None[source]#

Save object to file (signal/image).

Parameters:
  • obj – object

  • filename – file name

  • param – optional image export parameters

load_from_directory(directory: str | None = None, import_filenames: list[str] | None = None, import_params: list[DataSet] | None = None, param: DataSet | None = None, skipped_filenames: list[str] | None = None) → list[TypeObj][source]#

Open objects from directory (signals or images, depending on the panel), add them to DataLab and return them. If the directory is not specified, ask the user to select a directory.

Parameters:
  • directory – directory name

  • import_filenames – Optional file names, relative to directory, of the files imported with format-specific parameters. Recorded by history so that replay does not reopen import dialogs.

  • import_params – Optional format-specific parameters aligned with import_filenames.

  • param – Optional format-specific parameters applied to every file requiring import parameters (e.g. RAW images), without showing any dialog.

  • skipped_filenames – Optional file names, relative to directory, of the files whose import dialog was cancelled. Recorded by history so that replay skips them without reopening their dialog.

Returns:

list of new objects

load_from_files(filenames: list[str] | None = None, create_group: bool = False, add_objects: bool = True, ignore_errors: bool = False, import_params: list[DataSet | None] | None = None, param: DataSet | None = None) → list[TypeObj][source]#

Open and return objects from files, optionally adding them to DataLab.

Parameters:
  • filenames – File names

  • create_group – if True, create a new group if more than one object is loaded for a single file. Defaults to False: all objects are added to the current group.

  • add_objects – if True, add objects to the panel. Defaults to True.

  • ignore_errors – if True, ignore errors when loading files. Defaults to False.

  • import_params – Optional format-specific parameters aligned with file names. When provided by history replay, import dialogs are not reopened.

  • param – Optional format-specific parameters applied to every file requiring import parameters (e.g. RAW images), without showing any dialog. Cannot be combined with import_params.

Returns:

list of new objects

save_to_files(filenames: list[str] | str | None = None, export_params: list[ImageExportParam | None] | None = None, object_uuids: list[str] | None = None) → None[source]#

Save selected objects to files (signal/image).

Parameters:
  • filenames – File names

  • export_params – Optional image export parameters aligned with file names

  • object_uuids – Optional object UUIDs aligned with file names

save_to_directory(param: SaveToDirectoryParam | None = None) → None[source]#

Save signals or images to directory using a filename pattern.

Opens a dialog to select the output directory, the basename pattern and the extension.

Parameters:

param – parameters.

handle_dropped_files(filenames: list[str] | None = None) → None[source]#

Handle dropped files

Parameters:

filenames – File names

Returns:

None

exec_import_wizard() → None[source]#

Execute import wizard

import_metadata_from_file(filename: str | None = None) → None[source]#

Import metadata from file (JSON).

Parameters:

filename – File name

export_metadata_from_file(filename: str | None = None) → None[source]#

Export metadata to file (JSON).

Parameters:

filename – File name

copy_annotations() → None[source]#

Copy annotations from selected object

paste_annotations() → None[source]#

Paste annotations to selected object(s)

import_annotations_from_file(filename: str | None = None) → None[source]#

Import annotations from file (JSON).

Parameters:

filename – File name

export_annotations_from_file(filename: str | None = None) → None[source]#

Export annotations to file (JSON).

Parameters:

filename – File name

delete_annotations() → None[source]#

Delete all annotations from selected object(s)

import_roi_from_file(filename: str | None = None) → None[source]#

Import regions of interest from file (JSON).

Parameters:

filename – File name

export_roi_to_file(filename: str | None = None) → None[source]#

Export regions of interest to file (JSON).

Parameters:

filename – File name

refresh_after_reference_remap() → None[source]#

Refresh cached presentation after imported references are remapped.

selection_changed(update_items: bool = False) → None[source]#

Object selection changed: update object properties, refresh plot and update object view.

Parameters:

update_items – Update plot items (default: False)

properties_changed() → None[source]#

The properties ‘Apply’ button was clicked: update object properties, refresh plot and update object view.

recompute_selected() → None[source]#

Recompute/rerun selected objects or group with stored parameters.

This method handles both single objects and groups. For each object, it recomputes, on demand:

  • the processing that produced it (1-to-1, 2-to-1 or n-to-1, as restored by datalab.processingcall.resolve_processing_call(): from the provenance ledger, else from the processing metadata), in place, and

  • 1-to-0 analysis operations (statistics, measurements, detections, etc.).

Analysis results are not recomputed automatically when data, ROIs or object properties change: this manual action is the single, explicit entry point to refresh them. Objects without recomputable parameters are skipped.

recompute_1_to_1_objects(objects: list[SignalObj | ImageObj]) → tuple[set[str], bool][source]#

Recompute in-place 1-to-1 processing operations for the given objects.

Parameters:

objects – Objects with stored 1-to-1 processing parameters

Returns:

  • Set of object UUIDs successfully recomputed

  • True if operation was interrupted (progress canceled or user chose to stop after a failure), False otherwise

Return type:

Tuple containing

recompute_1_to_0_objects(objects: list[SignalObj | ImageObj]) → tuple[set[str], bool][source]#

Recompute 1-to-0 analysis operations for the given objects.

Parameters:

objects – Objects with stored 1-to-0 analysis parameters

select_source_objects() → None[source]#

Select source objects associated with the selected object’s processing.

This method retrieves the source object UUIDs from the selected object’s processing parameters and selects them in the object view.

add_plot_items_to_dialog(dlg: PlotDialog, oids: list[str]) → None[source]#

Add plot items to dialog

Parameters:
  • dlg – Dialog

  • oids – Object IDs

open_separate_view(oids: list[str] | None = None, edit_annotations: bool = False) → PlotDialog | None[source]#

Open separate view for visualizing selected objects

Parameters:
  • oids – Object IDs (default: None)

  • edit_annotations – Edit annotations (default: False)

Returns:

Instance of PlotDialog

view_images_side_by_side(oids: list[str] | None = None) → None[source]#

View selected images side-by-side in a grid layout

Parameters:

oids – Object IDs (default: None, uses selected objects)

get_dialog_size() → tuple[int, int][source]#

Get dialog size (minimum and maximum)

create_new_dialog(edit: bool = False, toolbar: bool = True, title: str | None = None, name: str | None = None, options: dict[str, Any] | None = None) → PlotDialog | None[source]#

Create new pop-up signal/image plot dialog.

Parameters:
  • edit – Edit mode

  • toolbar – Show toolbar

  • title – Dialog title

  • name – Dialog object name

  • options – Plot options

Returns:

Plot dialog instance

get_roi_editor_output(mode: Literal['apply', 'extract', 'define'] = 'apply') → tuple[TypeROI, bool] | None[source]#

Get ROI data (array) from specific dialog box.

Parameters:

mode – Mode of operation, either “apply” (define ROI, then apply it to selected objects), “extract” (define ROI, then extract data from it), or “define” (define ROI without applying or extracting).

Returns:

A tuple containing the ROI object and a boolean indicating whether the dialog was accepted or not.

get_objects_with_dialog(title: str, comment: str = '', nb_objects: int = 1, parent: QWidget | None = None) → TypeObj | None[source]#

Get object with dialog box.

Parameters:
  • title – Dialog title

  • comment – Optional dialog comment

  • nb_objects – Number of objects to select

  • parent – Parent widget

Returns:

Object(s) (signal(s) or image(s), or None if dialog was canceled)

show_results() → None[source]#

Show results

toggle_result_label_visibility(state: bool) → None[source]#

Toggle the visibility of the merged result label on the plot.

Parameters:

state – True to show the label, False to hide it

plot_results(kind: str | None = None, xaxis: str | None = None, yaxis: str | None = None) → None[source]#

Plot results

Parameters:
  • kind – Plot kind. Either “one_curve_per_object” or “one_curve_per_title”. If None, show dialog to get parameters.

  • xaxis – X axis column name. If None, show dialog to get parameters.

  • yaxis – Y axis column name. If None, show dialog to get parameters.

delete_results() → None[source]#

Delete results

add_label_with_title(title: str | None = None, ignore_msg: bool = True) → None[source]#

Add a label with object title on the associated plot

Parameters:
  • title – Label title. Defaults to None. If None, the title is the object title.

  • ignore_msg – If True, do not show the information message. Defaults to True. If False, show a message box to inform the user that the label has been added as an annotation, and that it can be edited or removed using the annotation editing window.

Signal panel#

datalab.gui.panel.signal.LEGACY_AUTOMATIC_LINE_WIDTH = 1.0#

Line width stored by DataLab 1.3 or earlier for curves drawn with the default line width, or with a line width clamped for curves with many points

class datalab.gui.panel.signal.SignalAnnotatedSegmentTool(manager, setup_shape_cb: Callable | None = None, handle_final_shape_cb: Callable | None = None, shape_style: tuple[str, str] | None=None, toolbar_id: str = <class 'plotpy.tools.base.DefaultToolbarID'>, title: str | None = None, icon: str | None = None, tip: str | None = None, switch_to_default_tool: bool | None = None)[source]#

Annotated segment tool for signals

The length and the angle of a segment combine its X and Y extents, whose units generally differ on a signal: unlike on images, they are not displayed.

create_shape() → tuple[AnnotatedSegment, int, int][source]#

Create an annotated segment without computations

Returns:

Annotated segment and the indices of its handles

class datalab.gui.panel.signal.SignalPanel(parent: QW.QWidget, dockableplotwidget: DockablePlotWidget, panel_toolbar: QW.QToolBar)[source]#

Object handling the item list, the selected item properties and plot, specialized for Signal objects

PARAMCLASS#

alias of SignalObj

IO_REGISTRY#

alias of SignalIORegistry

static get_roi_class() → Type[SignalROI][source]#

Return ROI class

static get_roieditor_class() → Type[SignalROIEditor][source]#

Return ROI editor class

deserialize_object_from_hdf5(reader: NativeH5Reader, name: str, reset_all: bool = False) → SignalObj[source]#

Deserialize object from a HDF5 file

DataLab 1.3 and earlier stored automatic curve styles in signal metadata: when loading a file saved by these versions, the colors and line styles of their automatic style cycle are removed, so that curves are given the current automatic styles. Other stored styles are kept. These versions also stored the line width of every curve: a line width of 1.0 (the default width, also used for curves with many points) is removed, so that curves are given the configured line width; other widths were chosen by the user and are kept.

Parameters:
  • reader – HDF5 reader

  • name – Object name in HDF5 file

  • reset_all – If True, preserve original UUIDs (workspace reload). If False, regenerate only UUIDs that conflict with existing objects (object import).

get_newparam_from_current(newparam: NewSignalParam | None = None, title: str | None = None) → NewSignalParam | None[source]#

Get new object parameters from the current object.

Parameters:
  • newparam (guidata.dataset.DataSet) – new object parameters. If None, create a new one.

  • title – new object title. If None, use the current object title, or the default title.

Returns:

New object parameters

new_object(param: NewSignalParam | None = None, edit: bool = False, add_to_panel: bool = True) → SignalObj | None[source]#

Create a new object (signal).

Parameters:
  • param (guidata.dataset.DataSet) – new object parameters

  • edit (bool) – Open a dialog box to edit parameters (default: False). When False, the object is created with default parameters and creation parameters are stored in metadata for interactive editing.

  • add_to_panel (bool) – Add the new object to the panel (default: True)

Returns:

New object

toggle_anti_aliasing(state: bool) → None[source]#

Toggle anti-aliasing on/off

Parameters:

state – state of the anti-aliasing

reset_curve_styles() → None[source]#

Reset the curve styles of the selected signals

Colors and line styles chosen by the user are removed from the metadata of the selected signals, whose curves are given automatic styles again.

Image panel#

datalab.gui.panel.image.get_image_export_dtype_choices(param: ImageExportGUIParam, _item: ChoiceItem, _value: str) → list[tuple[str, str, None]][source]#

Return target dtype choices supported by the selected image format.

class datalab.gui.panel.image.ImageExportGUIParam(title: str | None = None, comment: str | None = None, icon: str = '', readonly: bool = False, skip_defaults: bool = False)[source]#

Image export parameters restricted to the selected file format.

is_item_active(name: str) → bool[source]#

Return True if the item named name is taken into account.

get_format_options() → dict[str, object][source]#

Return writer options exposed by this format parameter class.

Inactive options are replaced by their default value, as they are not taken into account for the current values of the other options.

to_export_param() → ImageExportParam[source]#

Return backend export parameters from the current GUI values.

Inactive parameters (e.g. gamma without normalization) are reset to their default value, as they are not taken into account.

Returns:

Backend image export parameters

Raises:

ValueError – If a format option value is invalid

datalab.gui.panel.image.get_image_export_choice_label(value: object) → str[source]#

Return a translated human-readable label for an option choice.

datalab.gui.panel.image.serialize_image_export_sequence(value: object, spec: ImageExportOptionSpec) → tuple[int, int] | tuple[float, float] | list[float] | None[source]#

Serialize a pair or list option from its editable GUI representation.

datalab.gui.panel.image.create_image_export_option_item(spec: ImageExportOptionSpec, extension: str = '') → DataItem[source]#

Create a guidata item for an image export capability option.

Parameters:
  • spec – Option specification

  • extension – Canonical format extension, used for format-specific help

Returns:

Data item editing the option

datalab.gui.panel.image.get_image_export_param_class(filename: str) → type[ImageExportGUIParam][source]#

Return the cached GUI parameter class for an export format.

datalab.gui.panel.image.is_raw_image_file(filename: str) → bool[source]#

Return True if the file is a headerless RAW image requiring parameters.

Parameters:

filename – File name.

Returns:

True if the file has a .raw extension.

datalab.gui.panel.image.create_image_export_gui_param(obj: ImageObj, filename: str) → ImageExportGUIParam[source]#

Create format-aware image export parameters with practical defaults.

Parameters:
  • obj – Source image

  • filename – Destination file name

Returns:

Image export GUI parameters

datalab.gui.panel.image.compute_image_export_preview(source: ImageObj, param: ImageExportParam, filename: str) → ImageObj[source]#

Return the image as it will be read back from the exported file.

This function runs in the preview process, so its arguments must be picklable.

Parameters:
  • source – Image to export

  • param – Image export parameters

  • filename – Destination file name

Returns:

Copy of the source image holding the exported data, displayed in gray levels

datalab.gui.panel.image.format_image_export_error(message: str) → str[source]#

Return only the error message of an expected export validation error.

Validation errors raised by Sigima (ValueError/TypeError) explain the invalid configuration: the traceback is only kept for unexpected errors.

Parameters:

message – Error message or formatted traceback

Returns:

Message to display

class datalab.gui.panel.image.ImageExportDialog(parent: QWidget | None, obj: ImageObj, filename: str, param: ImageExportGUIParam, controller_factory: Callable = <class 'datalab.gui.processor.preview.PreviewController'>)[source]#

Format-aware image export dialog with a live preview of the exported data.

static to_export_param(guiparam: ImageExportGUIParam) → ImageExportParam[source]#

Return backend export parameters from GUI parameters.

Parameters:

guiparam – Format-specific GUI parameters

Returns:

Backend image export parameters

Raises:

ValueError – If a format option value is invalid

get_export_param() → ImageExportParam[source]#

Return backend parameters from the current GUI values.

accept() → None[source]#

Validate the export configuration before accepting.

class datalab.gui.panel.image.ImagePanel(parent: QW.QWidget, dockableplotwidget: DockablePlotWidget, panel_toolbar: QW.QToolBar)[source]#

Object handling the item list, the selected item properties and plot, specialized for Image objects

PARAMCLASS#

alias of ImageObj

IO_REGISTRY#

alias of ImageIORegistry

static get_roi_class() → Type[ImageROI][source]#

Return ROI class

static get_roieditor_class() → Type[ImageROIEditor][source]#

Return ROI editor class

edit_import_parameters(filenames: list[str], param: DataSet | None = None) → list[tuple[str, DataSet | None]] | None[source]#

Return files to import with their RAW image import parameters.

When several RAW files are imported, the user first chooses whether the same parameters apply to all of them (a single dialog) or not (one dialog per file).

Parameters:
  • filenames – File names to import.

  • param – Optional RAW image import parameters applied to every RAW file without showing any dialog (e.g. remote control).

Returns:

File names with aligned import parameters, without the RAW files whose dialog was cancelled, or None if the whole import was cancelled.

Raises:

TypeError – If param is not a RAW image import parameter set.

edit_raw_import_parameters(raw_files: list[str]) → dict[str, RawImageImportParam] | None[source]#

Edit RAW image import parameters, once for all files or per file.

Parameters:

raw_files – RAW file names.

Returns:

Parameters of the confirmed files, or None if the import was cancelled.

apply_import_parameters(objs: list[ImageObj], param: DataSet | None) → None[source]#

Apply RAW display semantics without changing imported values.

Parameters:
  • objs – Imported image objects.

  • param – Optional format-specific import parameters.

edit_export_parameters(obj: ImageObj, filename: str) → tuple[bool, ImageExportParam | None][source]#

Edit image export parameters for the selected file format.

Parameters:
  • obj – Image to export

  • filename – Destination file name

Returns:

A tuple containing the confirmation state and export parameters

write_object_to_file(obj: ImageObj, filename: str, param: ImageExportParam | None = None) → None[source]#

Write an image with optional format-aware export parameters.

Parameters:
  • obj – Image to export

  • filename – Destination file name

  • param – Optional image export parameters

register_contrast_editor(obj: ImageObj, editor: ImageROIEditor) → None[source]#

Register an image ROI editor for contrast synchronization.

apply_shared_contrast(obj: ImageObj, zmin: float, zmax: float, source: ImageROIEditor | None = None) → None[source]#

Apply a contrast change coming from another view.

plot_lut_changed(plot: BasePlot) → None[source]#

The LUT of the plot has changed: updating image objects accordingly

Parameters:

plot – Plot object

get_newparam_from_current(newparam: NewImageParam | None = None, title: str | None = None) → NewImageParam | None[source]#

Get new object parameters from the current object.

Parameters:
  • newparam (guidata.dataset.DataSet) – new object parameters. If None, create a new one.

  • title – new object title. If None, use the current object title, or the default title.

Returns:

New object parameters

new_object(param: NewImageParam | None = None, edit: bool = False, add_to_panel: bool = True) → ImageObj | None[source]#

Create a new object (image).

Parameters:
  • param (guidata.dataset.DataSet) – new object parameters

  • edit (bool) – Open a dialog box to edit parameters (default: False). When False, the object is created with default parameters and creation parameters are stored in metadata for interactive editing.

  • add_to_panel (bool) – Add the object to the panel (default: True)

Returns:

New object

toggle_show_contrast(state: bool) → None[source]#

Toggle show contrast option

Macro panel#

class datalab.gui.panel.macro.MacroTabs(parent=None)[source]#

Macro tabwidget

Parameters:

parent (QWidget) – Parent widget

clear() → None[source]#

Override Qt method

contextMenuEvent(event)[source]#

Override Qt method

add_tab(macro: Macro) → int[source]#

Add tab

Parameters:

macro – Macro object

Returns:

Number of the tab (starting at 1)

Return type:

int

remove_tab(number: int) → None[source]#

Remove tab

Parameters:

number – Number of the tab (starting at 1)

get_widget(number: int) → CodeEditor[source]#

Return macro editor widget at number

Parameters:

number – Number of the tab (starting at 1)

Returns:

Macro editor widget

set_current_number(number: int) → None[source]#

Set current tab number

Parameters:

number – Number of the tab (starting at 1)

get_current_number() → int[source]#

Return current tab number

Returns:

Number of the tab (starting at 1)

Return type:

int

set_tab_title(number: int, name: str) → None[source]#

Set tab title

Parameters:
  • number – Number of the tab (starting at 1)

  • name – Macro name

class datalab.gui.panel.macro.MacroPanel(parent: QMainWindow)[source]#

Macro Panel widget

Parameters:

parent (QWidget) – Parent widget

update_color_mode() → None[source]#

Update color mode according to the current theme

get_serializable_name(obj: Macro) → str[source]#

Return serializable name of object

serialize_to_hdf5(writer: NativeH5Writer) → None[source]#

Serialize whole panel to a HDF5 file

Parameters:

writer – HDF5 writer

deserialize_from_hdf5(reader: NativeH5Reader, reset_all: bool = False) → None[source]#

Deserialize whole panel from a HDF5 file

Parameters:
  • reader – HDF5 reader

  • reset_all – If True, preserve original UUIDs (workspace reload). If False, regenerate UUIDs (importing objects).

create_object() → Macro[source]#

Create object.

Returns:

Macro object

add_object(obj: Macro) → None[source]#

Add object.

Parameters:

obj – Macro object

remove_all_objects() → None[source]#

Remove all objects

setup_actions() → None[source]#

Setup macro menu actions

get_macro(number_or_title: int | str | None = None) → Macro | None[source]#

Return macro at number (if number is None, return current macro)

Parameters:

number – Number of the macro (starting at 1) or title of the macro. Defaults to None (current macro).

Returns:

Macro object or None (if not found)

get_number_from_title(title: str) → int | None[source]#

Return macro number from title

Parameters:

title – Title of the macro

Returns:

Number of the macro (starting at 1) or None (if not found)

get_number_from_macro(macro: Macro) → int | None[source]#

Return macro number from macro object

Parameters:

macro – Macro object

Returns:

Number of the macro (starting at 1) or None (if not found)

get_macro_titles() → list[str][source]#

Return list of macro titles

macro_contents_changed() → None[source]#

One of the macro contents has changed

run_macro(number_or_title: int | str | None = None) → None[source]#

Run current macro

Parameters:

number – Number of the macro (starting at 1). Defaults to None (run current macro, or does nothing if there is no macro).

stop_macro(number_or_title: int | str | None = None) → None[source]#

Stop current macro

Parameters:

number – Number of the macro (starting at 1). Defaults to None (run current macro, or does nothing if there is no macro).

macro_state_changed(orig_macro: Macro, state: bool) → None[source]#

Macro state has changed (True: started, False: stopped)

Parameters:
  • orig_macro – Macro object

  • state – State of the macro

closeEvent(event) → None[source]#

Persist splitter state on close.

showEvent(event) → None[source]#

Trigger the macro-recovery prompt on first show.

Deferred to the first showEvent (and re-scheduled via singleShot) so the splash screen has been finished before the QMessageBox appears — otherwise the dialog can pop up behind the splash.

add_macro() → Macro[source]#

Add macro, optionally with name

Returns:

Macro object

add_macro_with_code(title: str, code: str, source: str | None = None) → Macro[source]#

Add a macro with a predefined title and code, without prompting.

This helper is used by the AI assistant to programmatically inject a generated macro into the panel.

Parameters:
  • title – Macro title (displayed in the tab).

  • code – Python source code of the macro.

  • source – Optional origin marker (e.g. "import", "ai", "template:simple_macro") recorded in the recent cache.

Returns:

The newly created macro.

add_blank_macro() → Macro[source]#

Add a new empty macro and return it.

add_macro_from_template(template: MacroTemplate) → Macro[source]#

Add a new macro initialised from template.

Parameters:

template – Macro template description.

Returns:

The newly created macro.

duplicate_macro(number_or_title: int | str | None = None) → Macro | None[source]#

Duplicate the given (or current) macro.

Parameters:

number_or_title – Number of the macro (starting at 1) or title. Defaults to None (current macro).

Returns:

The duplicated macro, or None if no source macro was found.

show_recent_dialog() → None[source]#

Open a dialog listing recent macros and allow reopening one.

macro_name_changed(name: str) → None[source]#

Macro name has been changed

Parameters:

name – New name of the macro

rename_macro(number: int | None = None, title: str | None = None) → None[source]#

Rename macro

Parameters:
  • number – Number of the macro (starting at 1). Defaults to None.

  • title – Title of the macro. Defaults to None.

export_macro_to_file(number_or_title: int | str | None = None, filename: str | None = None) → None[source]#

Export macro to file

Parameters:
  • number_or_title – Number of the macro (starting at 1) or title of the macro. Defaults to None.

  • filename – Filename. Defaults to None.

Raises:

ValueError – If title is not found

import_macro_from_file(filename: str | None = None) → int[source]#

Import macro from file

Parameters:

filename – Filename. Defaults to None.

Returns:

Number of the macro (starting at 1)

update_untitled_counter() → None[source]#

Update the untitled counter based on existing macro titles

This scans all macro titles to find the highest “macro_XX” number and updates the global counter to prevent duplicate names.

remove_macro(number_or_title: int | str | None = None) → None[source]#

Remove macro

Parameters:

number_or_title – Number of the macro (starting at 1) or title of the macro. Defaults to None.