Visual & spatial

Diagramming & graphs

25 notations on one renderer, a NetworkX-tier graph engine and constraint-solved layout.

4 Strong · 5 Solid · 3 Partial · 0 Emerging

Measured against: Graphviz · Mermaid · D2 · NetworkX · Folders: base/graph(opens in a new tab) · For programmers: this area's reference

**a DRAKON diagram from the catalogue: cooking lunch.** rendered by the library's guard gg_drakon_catalogue and committed with it at 0e72e2e2c as cat_14_cook_lunch.png · the source(opens in a new tab)

Rethought from first principles

What Softanza kept from what works, and what it rethought, as the library wrote it down in its design documents and narrations.

The Softanza wayA diagram is a visual language, not a painting: every relation a reader can see in it must be one the graph actually contains.

Kept from the best practice

Layered drawings follow the classic Sugiyama pipeline: layers, helper nodes on long edges, crossing reduction, coordinates, then edge routing. source(opens in a new tab)
Graphviz's model is kept: the spacing between nodes is the contract, and the picture's size follows from its content, not the reverse. source(opens in a new tab)
Mathematical diagrams take Penrose's split: a domain declares types, a substance states the content, a style maps it to shapes, and optimisation finds the layout. source(opens in a new tab)

Rethought

The author edits meaning and the layout owns all geometry. Dragging a box only suggests an order, because a hand-placed position asserts something the graph cannot back. source(opens in a new tab)
BPMN, UML, state machines and circuits are declared profiles over one drawing foundation, never separate renderers, because a duplicate renderer had arrived broken. source(opens in a new tab)
Positions within a layer are solved exactly, by isotonic regression, not a median heuristic. Every layout is deterministic, so a test can check a picture byte for byte. source(opens in a new tab)
Two lines may run together only where they share an endpoint, because a reader takes merged lines as a shared relation the graph may not have. source(opens in a new tab)

One of the most complete planes in the library: 25 notations all rendered by one engine, over a native deterministic layout engine and a NetworkX-tier graph-algorithm suite; math and molecule diagrams are genuinely constraint-solved via autodiff. The old dot.exe dependency is demoted to an optional viewer — diagram layout is now engine-native. Guarded by ~1,790 assertions.

What a crafter does with it, and what stands out

25 notations as data profiles over one renderer
determinism as a guarantee: bit-identical layout across processes
constraint-solved layout via autodiff, which no mainstream tool does
NetworkX-core parity, compiled

What is owed

meet the dot kill criterion (spline routing, nested clusters)
live interactivity via the GUI plane
graph generators & isomorphism
PDF / PostScript export

The Softanza way, run

What Softanza does differently in this area, shown by code taken from its narrations and guards, and run for this page.

A declared notation that forbids self-links makes the editor refuse one, though no editor code knows that notation; a lawful link passes.

Softanza

# a notation declared as data: three kinds, a closed vocabulary, and no self-links
oFsm = new stzNotation("fsm51")
oFsm.AddKind("state", "circle")
oFsm.AddKind("final", "doublecircle")
oFsm.AddKind("task", "diamond")
oFsm.Close()
oFsm.Forbid(:SelfLink, "a state cannot transition to itself in fsm51; " +
	"model a stay as a guard on departure instead")
StzRegisterNotation(oFsm)

oDm = new stzDiagram("m51")
oDm.SetNotation("fsm51")
oDm.AddNodeXTT("a", "A", [ :type = "state" ])
oDm.AddNodeXTT("b", "B", [ :type = "task" ])
oDm.AddEdge("a", "b")
oDm.ToCanvasXT([ :NodeWidth = 96, :NodeHeight = 36 ])

nDnLog = len(oDm.EditLog())
bDnGot = oDm.Edit(:Link, [ "a", "a" ])
chk("a link the domain forbids is refused at the command",
    bDnGot = 0 and len(oDm.EditLog()) = nDnLog)
bDnGot = oDm.Edit(:Link, [ "b", "a" ])
chk("...while a lawful link passes the same gate",
    bDnGot = 1 and len(oDm.EditLog()) = nDnLog + 1)

Output

   ok   a link the domain forbids is refused at the command
   ok   ...while a lawful link passes the same gate

run on 2026-10-01 21:17 inside the library at commit 0e72e2e2c; taken from base/test/graphics/gg_adversarial.ring(opens in a new tab)

The articles of this area (12)

The lanes, one by one

Lanes and their notes are quoted as they were read at the source, on Read from the source on 2026-09-16, from a read-only main worktree.

Notation breadth

Strong

25 notations (DN0-DN24), ~21 Haro faces, all as profiles over one renderer (stzDiagram), not separate tools; the domain list is closed by designstzDiagram; SOFTANZA_GRAPH_PLANE_PLAN.md DN0-DN24

Deterministic layout engine

Strong

graph_layout.zig (GG1): barycentre crossing-reduction, seeded Fruchterman-Reingold force, bit-identical within and across processesgraph_layout.zig; determinism guard

Graph algorithms

Strong

graph.zig (CSR): BFS/DFS, Dijkstra, A*, SCC, bridges, toposort, betweenness/closeness/PageRank/k-core/Louvain, MST, max-flow/min-cut; engine-implementedgraph.zig; test/graph (158 files)

Constraint-solved diagrams

Strong

Math (DN7) and molecule (DN11) layouts are solved by the engine's autodiff solver (StzEngineGrad*), with DragTo/Pin interactive re-solvesolver/constraint/autodiff.zig

Rendering & output

Solid

One renderer, three outputs: ToSVG (no device), ToPNG (GPU-backed), an ASCII visualizer; 24 node shapes; DOT export; no PDF/PostScript

Diagram editing & interactivity

Solid

Command-based edit session: Edit, Undo/Redo, EditLog, PickAt, RewireAnchor; illegal edits refused at the gesture; not a visual WYSIWYG editor

Graph rules & governance

Solid

stzGraphRule and stzOrgRule feed the one CI gate (stzRuleReport): no-orphan-position, separation-of-duties; the rule catalogue is smallstzGraphRule / stzOrgRule / stzRuleReport

Export & interchange

Solid

stzGraph exports DOT, JSON, GraphML and YAML (Dot(), RenditionAs); import parity thinner, GEXF/adjacency round-trips not all presentstzGraph

Text & label placement

Solid

Notation-in-a-label (DN10), labels centred on cap-height not the em-box (DN12), curve clearance (DN13), solver-placed labels (SolveLabelsAfter)DN10 / DN12 / DN13

General graph layout & edge routing

Partial

Diagram layouts are engine-native; arbitrary large-graph visualization still leans on the optional dot.exe viewer: spline routing, nested clusters unmet

Graph generators & isomorphism

Partial

No standard graph generators (Erdos-Renyi, Barabasi-Albert, Watts-Strogatz) and no isomorphism / graph-edit-distance surfaced

Live / web interactivity

Partial

Diagrams emit interactive SVG and support programmatic re-layout (Relayout, DragTo); no built-in live pan/zoom/brush, the GUI plane's job