vibe-sketcherDocumentation

vibesketcher.render.panels

Labelled multi-panel figures at a stated physical width (#247).

compose_panels() lays existing figure SVGs (periodic figures, the cyclic-topology schematic, powder overlays, scheme renders or any SVG that passes the checks below) out in a grid, row by row in the order given, labels them (a), (b), … in that order and writes one SVG, or PDF/PNG through the publication extra. The physical width is stated: a single column (85 mm), a double column (178 mm), or width_mm for a journal’s own measure. One SVG unit is one point (1/72 in), as in every vibe-sketcher figure, so the PDF has exactly that width.

Each panel keeps its own drawing: it is embedded as a nested <svg> with its viewBox, scaled by one factor, and nothing in it is redrawn. Its id attributes are prefixed per panel so two panels never share a clip path. Panel scaling is stated, not guessed:

  • fit: every panel fills its column width;

  • uniform: one factor for every panel, so relative sizes are kept;

  • angstrom: every panel shows one angstrom at the same length, from the panel’s stated angstrom_per_unit (or its root attribute data-vibe-angstrom-per-unit); a panel without one is refused, and an optional common scale bar is drawn.

Panel SVG is untrusted input and fails closed: a DOCTYPE or entity, an element outside the drawing subset (no script, foreignObject, image or animation), an event attribute, an external reference (href or url(...) not starting with #) or a style sheet other than an @font-face block (which is dropped; the publication font is supplied at conversion) is refused. Captions and the title may hold $...$ math (vibesketcher.render.mathtext).

Module Attributes

COLUMN_WIDTH_MM

Generic single- and double-column widths; give width_mm for a journal's own.

Functions

cell_width_pt([options, panels])

The width of one grid column in points: draw a panel at this width for true-size text.

compose_panels(panels[, options, fmt, dpi])

The labelled grid as SVG, or PDF/PNG through the publication extra.

compose_panels_svg(panels[, options])

The labelled grid as standalone SVG (UTF-8), one unit per point.

panel_labels(count[, style])

The labels of count panels in reading order: (a), (b), ...

Classes

Panel(*, svg[, caption, angstrom_per_unit])

One panel: its SVG and what is stated about it.

PanelOptions(*[, columns, column, width_mm, ...])

The grid, the physical width and the labels; every choice is stated.

Exceptions

PanelRefused

A panel or the layout cannot be composed as asked.

vibesketcher.render.panels.COLUMN_WIDTH_MM = {'double': 178.0, 'single': 85.0}

Generic single- and double-column widths; give width_mm for a journal’s own.

class vibesketcher.render.panels.Panel(*, svg, caption=None, angstrom_per_unit=None)[source]

Bases: BaseModel

One panel: its SVG and what is stated about it.

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

svg: str
caption: str | None

A caption under the panel; $...$ math is allowed.

angstrom_per_unit: float | None

Angstrom per SVG unit of this panel, for scale="angstrom".

class vibesketcher.render.panels.PanelOptions(*, columns=2, column='double', width_mm=None, gap_mm=3.0, labels='(a)', label_size_pt=9.0, label_bold=True, caption_size_pt=8.0, scale='fit', scale_bar_angstrom=None, max_height_mm=None, title=None)[source]

Bases: BaseModel

The grid, the physical width and the labels; every choice is stated.

Parameters:
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

columns: int
column: Literal['single', 'double']
width_mm: float | None

Overrides column with an exact width.

gap_mm: float
labels: LabelStyle
label_size_pt: float
label_bold: bool
caption_size_pt: float
scale: Literal['fit', 'uniform', 'angstrom']
scale_bar_angstrom: float | None

a scale bar of this many angstrom under the grid.

Type:

With scale="angstrom"

max_height_mm: float | None

The tallest a panel may be drawn; with fit and uniform a taller panel is scaled down to it (angstrom refuses instead, to keep the scale).

title: str | None
exception vibesketcher.render.panels.PanelRefused[source]

Bases: RenderRefused

A panel or the layout cannot be composed as asked.

vibesketcher.render.panels.compose_panels(panels, options=None, fmt='svg', *, dpi=300)[source]

The labelled grid as SVG, or PDF/PNG through the publication extra.

Parameters:
Return type:

bytes

vibesketcher.render.panels.compose_panels_svg(panels, options=None)[source]

The labelled grid as standalone SVG (UTF-8), one unit per point.

Parameters:
Return type:

bytes

vibesketcher.render.panels.cell_width_pt(options=None, panels=None)[source]

The width of one grid column in points: draw a panel at this width for true-size text.

Parameters:
Return type:

float

vibesketcher.render.panels.panel_labels(count, style='(a)')[source]

The labels of count panels in reading order: (a), (b), …

Parameters:
  • count (int)

  • style (Literal['(a)', 'a', 'a)', '(A)', 'A', 'none'])

Return type:

list[str]