spacr.qt.widgets.picture_export

Save a rendered picture as a PNG or a one-page PDF.

Exports use the supplied QImage or QPixmap rather than capturing the surrounding widget. PNG preserves the image’s pixel dimensions and records the selected resolution as dots-per-metre metadata. PDF embeds the raster image on a page; it does not convert pixels into vector artwork.

PDF page dimensions are computed from the image’s pixel dimensions and export DPI, with a minimum of one millimetre for each dimension. The image fills the page with zero margins. This sets the printed size without using microscope pixel calibration.

Default resolution and filename suffix come from spacr.qt.preferences.get_figure_png_dpi() and spacr.qt.preferences.get_figure_format(). The right-click menu’s explicit PNG or PDF choice determines the final export format.

Functions

as_image(→ Optional[PySide6.QtGui.QImage])	Whatever was handed over, as a QImage, or None.
ask_where_to_save(→ str)	Ask for an output path; return "" when the dialog is cancelled.
build_menu(parent, enabled)	The right-click menu: save as PNG, save as PDF.
choose_format(→ str)	Pop the menu at point and return the chosen suffix, or "".
install_picture_save(→ bool)	Give view a right-click menu that saves what it is showing.
picture_dpi(→ int)	The resolution a saved picture is written at.
preferred_suffix(→ str)	".pdf" or ".png", following the Figures format preference.
save_as(→ str)	Ask for a path and write picture there. "" if nothing was.
save_picture(→ bool)	Write picture to path, as a PNG or a PDF by its suffix.
suggested_name(→ str)	A file name for stem, with the preferred suffix on it.

Module Contents

spacr.qt.widgets.picture_export.as_image(picture) → PySide6.QtGui.QImage | None

Whatever was handed over, as a QImage, or None.

A caller may hold a QPixmap (what a view shows), a QImage (what a renderer produced) or nothing at all yet.

Parameters:

picture – a QPixmap, a QImage or None; a null image or any other type also gives None.

spacr.qt.widgets.picture_export.ask_where_to_save(parent, stem: str) → str

Ask for an output path; return "" when the dialog is cancelled.

If the chosen name has no suffix, append .pdf or .png according to the selected file filter. An existing suffix is retained here; save_as() subsequently enforces the format chosen in the menu.

Parameters:

• parent – the widget the save dialog is parented to.

• stem – the file name offered, without a suffix; cleaned by suggested_name().

spacr.qt.widgets.picture_export.build_menu(parent, enabled: bool)

The right-click menu: save as PNG, save as PDF.

Each action carries its suffix as its data, so the caller reads the choice off the action rather than comparing it against two references it had to keep.

Parameters:

• parent – the widget that owns the menu.

• enabled – False when there is no picture yet. The actions are SHOWN AND GREYED rather than left out, and a line underneath says why: a menu that is empty on one field and full on the next reads as a bug, not as a state.

spacr.qt.widgets.picture_export.choose_format(view, point, enabled: bool) → str

Pop the menu at point and return the chosen suffix, or "".

THE MODAL CALL IS ALONE IN HERE so everything around it can be driven by a test. QMenu.exec spins an event loop of its own, and a test that reached it would hang rather than fail; substituting this one function is how the rest of the gesture is checked at all.

Parameters:

• view – the widget the menu belongs to; point is mapped to global coordinates through it.

• point – where the right-click happened, in view coordinates.

• enabled – False greys out the save actions, as in build_menu().

spacr.qt.widgets.picture_export.install_picture_save(view, picture: Callable[[], object], stem: str = 'picture', unless: Callable[[], bool] | None = None) → bool

Give view a right-click menu that saves what it is showing.

Parameters:

• view – the widget the user right-clicks.

• picture – called before the context menu opens; returns the QPixmap or QImage to write. The returned image is used after the format and path dialogs; the callback is not called again immediately before writing.

• stem – the file name offered, without a suffix. A callable is called after the format is selected and before the path dialog opens.

• unless – asked first; True means the right button belongs to something else at this moment and no menu is shown. The live preview’s ruler is cleared with a right-click while it is active, and a menu appearing over that would take a tool away to add a file dialog nobody asked for.

Returns:

whether the menu was installed.

spacr.qt.widgets.picture_export.picture_dpi() → int

The resolution a saved picture is written at.

Returns:

the Figures preference, or FALLBACK_DPI.

spacr.qt.widgets.picture_export.preferred_suffix() → str

".pdf" or ".png", following the Figures format preference.

spacr.qt.widgets.picture_export.save_as(view, picture, stem: str, want: str) → str

Ask for a path and write picture there. "" if nothing was.

Parameters:

• view – the widget the save dialog and any warning are parented to.

• picture – the QPixmap or QImage to write.

• stem – the file name offered, without a suffix.

• want – the suffix the user picked in the menu. It WINS over what the file dialog came back with, so “save as PDF” followed by a name ending in .png still writes a PDF rather than quietly changing format because of a typed extension.

Returns:

the path written, or "".

spacr.qt.widgets.picture_export.save_picture(picture, path, dpi: int | None = None) → bool

Write picture to path, as a PNG or a PDF by its suffix.

Parameters:

• picture – a QPixmap or QImage.

• path – where to write. .pdf writes a page; anything else writes a PNG.

• dpi – resolution; picture_dpi() when omitted.

Returns:

whether a file was written.

spacr.qt.widgets.picture_export.suggested_name(stem: str) → str

A file name for stem, with the preferred suffix on it.

Parameters:

stem – the base name; whitespace runs become underscores, and an empty result (or None) becomes picture.

Nested helpers

install_picture_save._menu(point) → str

Offer the save menu at point; the path written, or "".

Parameters:

point – where the right-click landed, in view coordinates.

spacr/qt/widgets/picture_export.py:335