spacr.figures.headless

Render pyqtgraph figures without an interactive window.

Regression plots are rendered with pyqtgraph in the graphical interface. This module renders the same plot specification through the same renderer in an offscreen widget, allowing interactive and pipeline-generated figures to share one implementation.

spacr.figures.scene.pyqtgraph_ready() supplies a QApplication on Qt’s offscreen platform when no display is available. If Qt cannot create a scene safely, rendering returns an explanatory refusal instead of reporting a nonexistent output. Output format and resolution follow spacr.plot.figure_output_preferences(), and completed files are published through spacr.figure_sink.publish_file() for inclusion in the run gallery.

Functions

application()

The QApplication to render under, or (None, reason).

render_bundle(→ Optional[str])

Render spec and write the whole folder beside it.

render_offscreen(→ Optional[str])

Draw spec offscreen and write it to path.

Module Contents

spacr.figures.headless.application()[source]

The QApplication to render under, or (None, reason).

DELEGATED TO spacr.figures.scene.pyqtgraph_ready(), which is the one place that answers “can a scene be built here and now”. It knows two things this module must not get wrong on its own:

  • pyqtgraph binds its Qt library on FIRST import, and this environment also has PyQt6 – so a bare import pyqtgraph can leave PySide6 unloadable. It sets PYQTGRAPH_QT_LIB before anything imports it.

  • a QWidget must be built on the GUI thread. The regression QC suite runs on the run’s worker thread under a live application, and a widget built there lives on a thread that is about to end – traced from two segfaults that landed nowhere near the cause.

A second answer to that question is how one of those two rules gets forgotten, so there is only one.

Returns:

(app, "") on success, (None, reason) when rendering is impossible. The reason is a sentence for the user, not a traceback.

spacr.figures.headless.render_bundle(spec, folder: str, name: str, **kwargs) → str | None[source]

Render spec and write the whole folder beside it.

The same bundle FastPlot.export_bundle() writes from the screen – figure, data, statistics, settings – produced by a run that has no screen, so a generated figure and a saved one are the same thing.

Parameters:
Returns:

the bundle directory, or None when there is no Qt.

spacr.figures.headless.render_offscreen(spec, path: str, *, size: Tuple[int, int] | None = None, fmt: str | None = None, title: str = '', x_label: str = '', y_label: str = '', publish: bool = True) → str | None[source]

Draw spec offscreen and write it to path.

Parameters:

  • spec – a spacr.qt.widgets.grouped_plot.PlotSpec.

  • path – destination. The extension is rewritten to the user’s figure-format preference unless fmt names one.

  • size – layout size in pixels; RENDER_SIZE by default.

  • fmt – "pdf", "png" or "svg" to override the preference.

  • title – plot title. spec.title is used when empty.

  • x_label – horizontal axis label. spec.x_label when empty.

  • y_label – vertical axis label. spec.y_label when empty.

  • publish – announce the file to the figure sink. True by default, because saved and visible are the same event.

Returns:

the path written, or None with the reason logged at WARNING when there is no Qt to render under.