Add report-quality figure export for DataLab objects

[PierreRaybaut]

Summary

DataLab should provide a dedicated way to generate high-quality, report-ready figures from selected signal and image objects, suitable for direct integration into reports, technical notes and presentations.

Motivation

DataLab currently relies on PlotPy-based widgets that are very well suited to interactive scientific data exploration: zooming, panning, ROI manipulation, contrast adjustment, measurements, annotations and object inspection. However, these widgets are not designed primarily as a final figure composition engine. As a result, direct PNG exports from the interactive view may produce figures that are not suitable for inclusion in formal reports or presentations without additional manual rework.

Scientists and engineers would need not simply to export the current interactive view, but to produce clean, reproducible and configurable figures from DataLab objects, with control over layout, labels, units, legends, titles, colorbars, figure size, resolution and visual style.

Proposed user-facing feature

Add a new action in the View menu, tentatively named Create report-quality figure....

The term publication-ready should probably be avoided in the user interface because it may be too ambitious and may imply a level of typographic or editorial quality that depends on the target journal, report template or corporate presentation style. Alternative labels could be:

• Create report-quality figure...
• Create presentation figure...
• Create export figure...
• Create formatted figure...
• Create figure for report...

Proposed workflow

When the user selects one or several signal or image objects, the View > Create report-quality figure... action opens a dialog showing a Matplotlib rendering of the selected objects.

The dialog contains a preview area and a parameter panel based on a guidata.dataset.DataSet, allowing the user to customize the figure presentation.

The figure can then be exported to common formats such as PNG and SVG, and possibly PDF depending on the implementation effort and platform constraints.

The feature should support both signals and images, with parameters adapted to the selected object type.

Initial scope

The first implementation should focus on a robust and useful subset rather than attempting to reproduce all PlotPy interactive display features.

For signal objects, the feature should support rendering one or several selected curves with configurable title, axis labels, units, legend, line style, marker style, grid, figure size, DPI and output format.

For image objects, the feature should support rendering one selected image with configurable title, axis labels, units, colormap, colorbar, contrast range, interpolation, aspect ratio, figure size, DPI and output format.

A later extension may support multi-panel layouts, overlays, ROI rendering, annotations, image profiles, mixed signal/image layouts and batch figure generation.

Proposed technical approach

Introduce a dedicated figure-generation layer rather than trying to improve direct exports from PlotPy widgets.

The rendering backend may initially rely on Matplotlib, reusing or adapting the implementation already introduced in sigima.viz.

This layer should convert DataLab objects (SignalObj, ImageObj) and their display metadata into Matplotlib figures.

A guidata.dataset.DataSet should define the user-configurable figure parameters.

The dialog should expose these parameters, update the preview, and export the resulting Matplotlib figure.

The selected figure parameters should be serializable into the object metadata so that the same object can later be reopened with the same report-quality figure settings.

Relationship with existing PlotPy display metadata

DataLab already stores part of the standard PlotPy display configuration in object metadata. For example, object metadata is used to synchronize display parameters between the object and its PlotPy item representation.

The new Matplotlib rendering should reuse relevant existing metadata when possible, rather than introducing an entirely separate visual state.

For example, image contrast limits, colormap-related settings, axis labels, units, object titles, selected display ranges and existing annotations or ROI-related metadata may be used as initial values for the Matplotlib figure.

The new report-quality figure parameters should be stored in a dedicated metadata namespace, for example report_figure or formatted_figure, to avoid mixing Matplotlib-specific options with PlotPy-specific display options.

Possible metadata structure

A possible object metadata structure could be:

obj.metadata["report_figure"] = {
    "schema_version": 1,
    "backend": "matplotlib",
    "figure_size": [6.4, 4.8],
    "dpi": 150,
    "title": "Object title",
    "show_title": True,
    "show_grid": True,
    "show_legend": True,
    "x_label": "Time",
    "y_label": "Amplitude",
    "style": "default",
    "export_format": "png"
}

For images, additional options may include:

obj.metadata["report_figure"] = {
    "schema_version": 1,
    "backend": "matplotlib",
    "figure_size": [6.4, 4.8],
    "dpi": 150,
    "title": "Image title",
    "show_title": True,
    "show_colorbar": True,
    "colormap": "viridis",
    "contrast_range": [0.0, 4095.0],
    "interpolation": "nearest",
    "aspect": "equal",
    "export_format": "png"
}

The exact key names should be aligned with existing DataLab metadata conventions.

Architectural considerations

The feature should remain independent from the interactive PlotPy widgets. PlotPy remains the primary interactive visualization layer, while Matplotlib would be used as a formatted figure rendering backend.

The implementation should avoid duplicating too much logic between signal and image rendering. A small internal abstraction may be useful, for example:

• FigureSettingsBase
• SignalFigureSettings
• ImageFigureSettings
• create_matplotlib_figure(objects, settings)
• ReportFigureDialog

The first implementation may live in DataLab, but the rendering logic should ideally remain sufficiently decoupled to be reusable from scripts, tests or future DataLab Web features.

Alternative or complementary idea: a plot grammar layer

A more ambitious direction would be to introduce a lightweight plot description layer, or "plot grammar", independent from the final rendering backend.

This layer would describe the intended figure semantically: curves, images, axes, labels, units, legends, colorbars, layout and style. A backend would then render this description using Matplotlib, or possibly another library in the future.

This could make the feature easier to reuse in DataLab Desktop, DataLab Web, scripts, notebooks and automated report generation.

However, this should probably not be part of the first implementation unless a very small and pragmatic design can be introduced without over-engineering the feature.

A reasonable compromise would be to start with Matplotlib-specific settings and keep the internal API clean enough to evolve later toward a backend-neutral figure specification.

Suggested implementation steps

1. Review the existing sigima.viz Matplotlib implementation and identify the reusable parts for signal and image rendering.

2. Define minimal figure settings as guidata.dataset.DataSet classes for signals and images.

3. Add a View > Create report-quality figure... action enabled when compatible objects are selected.

4. Implement a Qt dialog with a Matplotlib preview canvas and a parameter editor.

5. Initialize default figure settings from the selected object data and existing PlotPy-related metadata.

6. Serialize the report-quality figure settings into the selected object metadata.

7. Add export actions for PNG and SVG, with optional PDF support if straightforward.

8. Add tests for settings serialization, metadata round-trip and figure generation without requiring interactive GUI testing where possible.

9. Document the feature in the user documentation, including the distinction between interactive PlotPy visualization and formatted Matplotlib figure generation.

Acceptance criteria

• A user can select a signal object and create a formatted Matplotlib figure from it.

• A user can select an image object and create a formatted Matplotlib figure from it.

• The generated figure can be exported as a high-quality PNG.

• The generated figure can be exported as SVG if technically feasible in the first implementation.

• Figure size and DPI are configurable.

• Titles, axis labels and units are configurable.

• Relevant existing object display metadata is used as initial input for the Matplotlib rendering.

• Report-quality figure settings are saved in the object metadata and restored when the dialog is reopened.

• The implementation does not alter the behavior of the existing interactive PlotPy views.

• The feature is covered by unit tests for metadata serialization and non-interactive figure generation.

Out of scope for the first implementation

• Full reproduction of arbitrary PlotPy interactive views.

• Complex multi-panel publication layouts.

• Automatic corporate report generation.

• Full support for all annotations and ROI types.

• DataLab Web implementation, unless the design naturally exposes reusable settings or a backend-neutral figure specification.

Open questions

• Should the feature support multiple selected signals in one figure from the first version?

• Should multiple selected images be supported in a grid layout, or should image support initially be limited to one image at a time?

• Should the metadata namespace be named report_figure, formatted_figure, matplotlib_figure or something else?

• Should exported figures include ROI and annotations in the first implementation?

• Should the feature be implemented entirely in DataLab, or should part of the rendering logic be moved to or reused from sigima.viz?

• Should the long-term design remain Matplotlib-specific, or should we introduce a small backend-neutral plot specification from the beginning?

Notes

This feature is motivated by a practical customer need: DataLab should not only allow users to interactively explore scientific data, but also help them produce clean, reproducible figures that can be directly used in reports and presentations.

The proposed design deliberately separates interactive visualization from report-quality figure generation, which should make the implementation more maintainable and avoid forcing PlotPy widgets to solve a problem they were not primarily designed for.