vibe-sketcherDocumentation

vibesketcher.render.diagram

Workflow and taxonomy diagrams: boxes with text and attached connectors (#247).

A diagram is stated as a small spec (DiagramSpec, schema vibesketcher.diagram/1, written as JSON or TOML): nodes (boxes with $...$ math labels, optionally in a named group), directed edges with optional labels, and a layout. Nothing is drawn from a picture: every connector is computed from the boxes it joins, so it stays attached when a box moves, and the same spec always gives the same bytes.

Layouts:

  • layered (workflows): the layered drawing of K. Sugiyama, S. Tagawa and M. Toda, “Methods for visual understanding of hierarchical system structures”, IEEE Trans. Syst. Man Cybern. SMC-11, 109-125 (1981), doi:10.1109/TSMC.1981.4308636. Cycles are broken by reversing the back edges of a depth-first search in input order (they are drawn in their stated direction). Layers are the longest path from a source. An edge that spans several layers gets a dummy vertex per inner layer, so it is drawn as a polyline through the gaps between boxes. Crossings are reduced by the barycentre method (section IV of the paper) in alternating down and up sweeps, a fixed number of them (SWEEPS); the order with the fewest crossings is kept, so the result does not depend on timing. Positions along a layer follow the barycentres of the neighbours (the priority idea of section V, simplified to the average of a left-to-right and a right-to-left sweep, which keeps the stated separation).

  • tree (taxonomies): each node has at most one parent; children are placed side by side in the order their edges are stated and the parent is centred over them, the aesthetic rules of E. M. Reingold and J. S. Tilford, “Tidier drawings of trees”, IEEE Trans. Softw. Eng. SE-7, 223-228 (1981), doi:10.1109/TSE.1981.234519. Subtrees are packed by their bounding widths, not by their contours, so a tree may be wider than Reingold-Tilford’s.

  • manual: every node states its centre position (pt, y down).

In the other layouts a node’s position pins it there. The direction is down (layers are rows) or right (layers are columns).

The drawing fails closed: more than MAX_NODES nodes or MAX_EDGES edges, an unknown node or group, a self-loop, a duplicate edge, a second parent in a tree, unsupported math, two boxes that overlap and a group box that covers a node outside the group are refused with DiagramRefused. The bounds include every box, connector, arrowhead and label: text is measured with the publication font’s advance widths (vibesketcher.render.mathtext.measure()), so nothing is clipped in SVG, PDF or PNG. One SVG unit is one point; PDF and PNG go through the publication extra.

Module Attributes

MAX_NODES

The most nodes, edges and groups a diagram may have.

SWEEPS

Barycentre sweeps (each a down and an up pass) of the crossing reduction.

Functions

diagram(spec[, fmt, dpi])

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

diagram_layout(spec)

Measure, lay out and check the diagram; the geometry before drawing.

diagram_svg(spec)

The diagram as standalone SVG (UTF-8), one unit per point unless width_pt.

load_spec(data[, fmt])

A validated spec from JSON or TOML text (or a parsed mapping); errors are refusals.

Classes

DiagramEdge(*, source, target[, label, ...])

A directed connector from source to target, with an optional label.

DiagramGroup(*, id[, label, stroke, fill])

A labelled frame around the nodes that name it.

DiagramNode(*, id, label[, group, position, ...])

One box.

DiagramSpec(*[, schema, layout, direction, ...])

A workflow or taxonomy diagram; every choice is stated.

Exceptions

DiagramRefused

The spec cannot be drawn as stated.

vibesketcher.render.diagram.MAX_NODES = 120

The most nodes, edges and groups a diagram may have.

vibesketcher.render.diagram.SWEEPS = 12

Barycentre sweeps (each a down and an up pass) of the crossing reduction.

class vibesketcher.render.diagram.DiagramEdge(*, source, target, label=None, style='solid', arrow=True, colour='#000000')[source]

Bases: BaseModel

A directed connector from source to target, with an optional label.

Parameters:
  • source (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9_.:-]{1,64}$')])

  • target (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9_.:-]{1,64}$')])

  • label (Annotated[str | None, MaxLen(max_length=300)])

  • style (Literal['solid', 'dashed'])

  • arrow (bool)

  • colour (Annotated[str, _PydanticGeneralMetadata(pattern='^#[0-9a-fA-F]{6}$')])

model_config = {'extra': 'forbid'}

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

source: str
target: str
label: str | None
style: Literal['solid', 'dashed']
arrow: bool
colour: str
class vibesketcher.render.diagram.DiagramGroup(*, id, label=None, stroke='#666666', fill='#f4f4f4')[source]

Bases: BaseModel

A labelled frame around the nodes that name it.

Parameters:
  • id (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9_.:-]{1,64}$')])

  • label (Annotated[str | None, MaxLen(max_length=300)])

  • stroke (Annotated[str, _PydanticGeneralMetadata(pattern='^#[0-9a-fA-F]{6}$')])

  • fill (Annotated[str, _PydanticGeneralMetadata(pattern='^#[0-9a-fA-F]{6}$')])

model_config = {'extra': 'forbid'}

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

id: str
label: str | None
stroke: str
fill: str
class vibesketcher.render.diagram.DiagramNode(*, id, label, group=None, position=None, shape='rounded', fill='#ffffff', stroke='#000000', min_width=0.0, bold=False)[source]

Bases: BaseModel

One box. label holds up to four lines separated by newlines; math is allowed.

Parameters:
  • id (Annotated[str, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9_.:-]{1,64}$')])

  • label (Annotated[str, MinLen(min_length=1), MaxLen(max_length=600)])

  • group (Annotated[str | None, _PydanticGeneralMetadata(pattern='^[A-Za-z0-9_.:-]{1,64}$')])

  • position (tuple[float, float] | None)

  • shape (Literal['box', 'rounded', 'plain'])

  • fill (Annotated[str, _PydanticGeneralMetadata(pattern='^#[0-9a-fA-F]{6}$')])

  • stroke (Annotated[str, _PydanticGeneralMetadata(pattern='^#[0-9a-fA-F]{6}$')])

  • min_width (Annotated[float, Ge(ge=0.0), Le(le=1000.0)])

  • bold (bool)

model_config = {'extra': 'forbid'}

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

id: str
label: str
group: str | None
position: tuple[float, float] | None

The box’s centre in points (y down); required by the manual layout, a pin otherwise.

shape: Literal['box', 'rounded', 'plain']
fill: str
stroke: str
min_width: float

The smallest box width in points; the label widens it as needed.

bold: bool
exception vibesketcher.render.diagram.DiagramRefused[source]

Bases: RenderRefused

The spec cannot be drawn as stated.

class vibesketcher.render.diagram.DiagramSpec(*, schema='vibesketcher.diagram/1', layout='layered', direction='down', nodes, edges=<factory>, groups=<factory>, font_size=8.0, layer_gap=28.0, node_gap=14.0, padding=4.0, width_pt=None, title=None)[source]

Bases: BaseModel

A workflow or taxonomy diagram; every choice is stated.

Parameters:
model_config = {'extra': 'forbid', 'populate_by_name': True}

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

schema_: Literal['vibesketcher.diagram/1']
layout: Literal['layered', 'tree', 'manual']
direction: Literal['down', 'right']
nodes: list[DiagramNode]
edges: list[DiagramEdge]
groups: list[DiagramGroup]
font_size: float
layer_gap: float

Space between layers and between neighbouring boxes in a layer, in points.

node_gap: float
padding: float

Inner padding of a box, in points.

width_pt: float | None

Draw the figure this wide (pt), scaling the drawing; by default 1 unit = 1 pt.

title: str | None
vibesketcher.render.diagram.diagram(spec, fmt='svg', *, dpi=300)[source]

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

Parameters:
Return type:

bytes

vibesketcher.render.diagram.diagram_layout(spec)[source]

Measure, lay out and check the diagram; the geometry before drawing.

Parameters:

spec (DiagramSpec)

Return type:

_Layout

vibesketcher.render.diagram.diagram_svg(spec)[source]

The diagram as standalone SVG (UTF-8), one unit per point unless width_pt.

Parameters:

spec (DiagramSpec)

Return type:

bytes

vibesketcher.render.diagram.load_spec(data, fmt='json')[source]

A validated spec from JSON or TOML text (or a parsed mapping); errors are refusals.

Parameters:
Return type:

DiagramSpec