spacr.qt.widgets.save_figure_dialog

Preview and save a figure styled for the file rather than for the screen.

The figure displayed in spaCR is never changed. A Matplotlib figure is copied before it is styled; a pyqtgraph plot cannot be copied safely, so it is styled only for the length of one offscreen render and put back afterwards. Figures that can be neither copied nor rendered still use the ordinary save path without a styled preview.

The dialog offers what belongs to the FILE – its background, the colour and width of its lines, the colour of its text, the shape of its page, and what kind of file it is. Everything else a figure can be told belongs to the PLOT and lives on the plot’s own right-click menu, where it reaches the screen and every export at once; a value inherited from there is shown here rather than offered a second time. Matplotlib figures have no such plot menu, so their dialog also offers an export-only text scale to keep type proportional when the output page is resized.

Classes

SaveFigureDialog

Preview and save an independently styled figure copy.

Functions

copy_figure(figure)

Create a detached figure for export preview.

is_fast_plot(→ bool)

Return whether a plot supports spaCR's fast styled-export protocol.

style_for_file(figure, *[, ink, background, grid, ...])

Apply export-only styling to a Matplotlib figure.

Module Contents

class spacr.qt.widgets.save_figure_dialog.SaveFigureDialog(figure, parent: PySide6.QtWidgets.QWidget | None = None)[source]

Bases: PySide6.QtWidgets.QDialog

Preview and save an independently styled figure copy.

Parameters:

  • figure (matplotlib.figure.Figure or fast plot) – Source figure. Matplotlib figures are copied before preview styling; fast plots provide their own styled snapshot and export methods.

  • parent (QWidget, optional) – Parent widget for the modal dialog.

Notes

Export settings never modify the source displayed in the application.

WHAT IT OFFERS, AND WHY IT IS SHORT. For a fast plot, four setting groups change how the FILE looks – the background, the lines’ colour and width, the text colour, and the shape of the page – and three more say what the file IS: its format, resolution and page size. Everything else belongs on the plot’s own right-click menu, where it applies to the screen and every export at once. A Matplotlib figure has no equivalent live menu, so its dialog also offers an export-only text scale.

A SETTING INHERITED FROM THE PLOT IS SHOWN, NOT EXPLAINED. The page size a pyqtgraph plot writes onto is set on that menu; this dialog displays the size it will get and keeps the sentence about where it comes from as a quieter note beside the number.

Build the save dialog: the four style choices, the shape and the page.

Whether the figure is a fast plot is decided once here, because the two kinds are styled and written through different methods and every branch below reads the flag rather than re-sniffing the object.

The text-scale control is offered only for a matplotlib figure: reducing a wide on-screen figure to a journal column leaves its labels full size and crowding the axes, and a fast plot already owns one font-size setting on its own menu – a second answer here would contradict it.

Parameters:

  • figure – the figure to save.

  • parent – parent widget, or None.

eventFilter(watched, event) → bool[source]

Reserve the actual wrapped height of the page explanation labels.

Parameters:

  • watched (PySide6.QtCore.QObject) – Label receiving a width, font or style change.

  • event (PySide6.QtCore.QEvent) – Qt notification forwarded unchanged to the parent implementation.

Returns:

bool – Parent event-filter result; resizing a note never consumes input.

preview()[source]

Return the current detached preview.

Returns:

matplotlib.figure.Figure, QPixmap, or None – Matplotlib copy, fast-plot snapshot, or None when no preview can be rendered.

refresh(*_args)[source]

Rebuild and return the preview from the original figure.

Each refresh starts from a new copy so repeated text scaling or color changes do not accumulate. Fast plots delegate to _refresh_fast_plot().

save(path: str = '') → str[source]

Write the figure using the current export settings.

Parameters:

path (str, optional) – Destination path. When omitted, a file chooser is displayed.

Returns:

str – Written path, or an empty string when the chooser is cancelled or no figure can be saved.

spacr.qt.widgets.save_figure_dialog.copy_figure(figure)[source]

Create a detached figure for export preview.

Parameters:

figure (object) – Figure to copy through Python’s pickle protocol.

Returns:

object or None – Independent copy of figure. None is returned when the input is absent or contains state that cannot be serialized, such as a live canvas or closure.

Notes

The serialization round trip matches the one used by the figure queue. Returning None lets callers fall back to an ordinary save without altering the on-screen figure.

spacr.qt.widgets.save_figure_dialog.is_fast_plot(figure) → bool[source]

Return whether a plot supports spaCR’s fast styled-export protocol.

Parameters:

figure (object) – Candidate Matplotlib or pyqtgraph figure.

Returns:

bool – True when the object provides callable styled_snapshot and export_styled methods.

Notes

Capability detection allows new fast-plot classes to support this dialog without requiring a class registry.

spacr.qt.widgets.save_figure_dialog.style_for_file(figure, *, ink: str = '', background: str = '', grid: bool | None = None, width: float = 0.0, height: float = 0.0, dpi: int = 0, font_scale: float = 0.0, text_colour: str = '', line_colour: str = '')[source]

Apply export-only styling to a Matplotlib figure.

Parameters:

  • figure (matplotlib.figure.Figure or None) – Figure copy to modify. None is accepted for preview fallbacks.

  • ink (str, optional) – Color applied to titles, labels, ticks, spines, legends, and text – text and lines together, which is what a paper-or-slide preset means. An empty string preserves the existing colors.

  • text_colour (str, optional) – Color for TEXT only: the title, the axis labels, the tick numbers and the legend. Overrides ink for that half.

  • line_colour (str, optional) – Color for LINES only: the spines and the tick marks. Overrides ink for that half.

  • background (str, optional) – Figure and axes background color. An empty string makes both backgrounds transparent.

  • grid (bool or None, default None) – Draw major grid lines when True and disable them when False. None leaves the figure’s own grid alone, which is what a caller with no grid control of its own wants: a default of False turns off a grid the figure was drawn with and nobody asked about.

  • width (float, default 0) – Output dimensions in inches. The size changes only when both values are positive.

  • height (float, default 0) – Output dimensions in inches. The size changes only when both values are positive.

  • dpi (int, default 0) – Output resolution. Zero preserves the figure’s current resolution.

  • font_scale (float, default 0) – Multiplier applied to every text artist. Values at or below zero preserve the current text sizes.

Returns:

matplotlib.figure.Figure or None – The same figure object after styling, or None when figure was None.

Notes

This function is intended for detached export copies. It does not read or update live figure preferences.