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 centreposition(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
The most nodes, edges and groups a diagram may have. |
|
Barycentre sweeps (each a down and an up pass) of the crossing reduction. |
Functions
|
The diagram as SVG, or PDF/PNG through the publication extra. |
|
Measure, lay out and check the diagram; the geometry before drawing. |
|
The diagram as standalone SVG (UTF-8), one unit per point unless |
|
A validated spec from JSON or TOML text (or a parsed mapping); errors are refusals. |
Classes
|
A directed connector from |
|
A labelled frame around the nodes that name it. |
|
One box. |
|
A workflow or taxonomy diagram; every choice is stated. |
Exceptions
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:
BaseModelA directed connector from
sourcetotarget, with an optional label.- Parameters:
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- style: Literal['solid', 'dashed']¶
- class vibesketcher.render.diagram.DiagramGroup(*, id, label=None, stroke='#666666', fill='#f4f4f4')[source]¶
Bases:
BaseModelA labelled frame around the nodes that name it.
- Parameters:
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- 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:
BaseModelOne box.
labelholds 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}$')])
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}$')])
bold (bool)
- model_config = {'extra': 'forbid'}¶
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
- 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']¶
- exception vibesketcher.render.diagram.DiagramRefused[source]¶
Bases:
RenderRefusedThe 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:
BaseModelA workflow or taxonomy diagram; every choice is stated.
- Parameters:
schema (Literal['vibesketcher.diagram/1'])
layout (Literal['layered', 'tree', 'manual'])
direction (Literal['down', 'right'])
nodes (Annotated[list[DiagramNode], MinLen(min_length=1), MaxLen(max_length=120)])
edges (Annotated[list[DiagramEdge], MaxLen(max_length=360)])
groups (Annotated[list[DiagramGroup], MaxLen(max_length=24)])
width_pt (Annotated[float | None, Ge(ge=20.0), Le(le=14400.0)])
- 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]¶
- vibesketcher.render.diagram.diagram(spec, fmt='svg', *, dpi=300)[source]¶
The diagram as SVG, or PDF/PNG through the publication extra.
- Parameters:
spec (DiagramSpec)
fmt (str)
dpi (int)
- Return type:
- 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: