Layout and routing¶
wxdiagram ships a small built-in spring layout and an injectable edge
router. Both are optional: the canvas works with hand-placed shapes and
straight edges, and pynsource keeps its own coordinate mapping and overlap
removal on top.
Positions use top-left coordinates, matching Shape.MoveTo.
Running a layout¶
canvas.ApplyLayout("spring", options={"spacing": 40, "seed": 1})
Or launch the playground: ./bin/run-layout (equivalent to
uv run python -m wxdiagram.layoutdemo).
Diagram.ApplyLayout works headless (no canvas): it positions nodes and
re-clips attached lines. ShapeCanvas.ApplyLayout additionally re-routes
edges, updates the virtual size and refreshes.
Standard options: spacing (gap between boxes), seed (deterministic
output), iterations, keep_positions (start from current positions),
direction (reserved for layered layouts), reduce_crossings (default on)
and crossing_passes (refinement sweeps). LayoutResult.metadata reports
crossings_before, crossings, refinement_moves, edge_length_before and
edge_length.
Edge crossings¶
Crossings are a layout property. The force layout minimises node overlap
and edge length; it does not understand line-line crossings. After the force
pass, SpringLayout runs a deterministic local refinement
(wxdiagram.layout_refine.reduce_crossings): movable nodes are nudged to
nearby positions when that reduces the number of straight centre-to-centre
edge crossings (or shortens edges without adding crossings). The router then
draws the edges; it avoids boxes, not other edges.
Not every crossing is removable: crossing minimisation is NP-hard, and
non-planar graphs always cross. The refinement is a local improvement, not a
global guarantee. Set reduce_crossings=False to compare the raw force
layout. wxdiagram.layout_metrics.count_crossings is available if an
application wants to report its own quality numbers.
Custom layout engine¶
import wxdiagram
class MyLayout:
name = "mine"
def layout(self, nodes, edges, *, options=None, on_step=None):
# nodes: list[LayoutNode], edges: list[LayoutEdge]
positions = {node.id: (node.x or 0.0, node.y or 0.0) for node in nodes}
return wxdiagram.LayoutResult(positions=positions)
wxdiagram.register_layout(MyLayout)
canvas.ApplyLayout("mine")
Return top-left positions keyed by node id. on_step(step, info) may return
False to abort early (progress dialogs, blackboard animation).
Custom edge router (experimental)¶
Experimental API
Router injection may change or be removed in a minor release. The stable
surface is LineShape.SetRouteMode, route_edge and
ShapeCanvas.RouteEdges. The playground does not expose custom routers.
from wxdiagram.routing import BaseRouter, RouteResult
class MidpointRouter(BaseRouter):
name = "midpoint"
def route(self, request):
(x1, y1), (x2, y2) = request.start, request.end
mid = ((x1 + x2) / 2.0, (y1 + y2) / 2.0 - 25.0)
return RouteResult(points=(request.start, mid, request.end), style="diagonal")
Attach per edge (line.SetRouter("midpoint") or an instance) or canvas-wide
(canvas.SetDefaultRouter("midpoint")). Override route_many(requests) when
the router needs to see all edges at once (lane occupancy, A*).
request.mode carries the edge's route mode (straight/auto/avoid/
curved/orthogonal), request.obstacles the foreign rectangles, and
request.lane_index/lane_count the parallel-edge position.
Route modes and persistence¶
LineShape.SetRouteMode("straight" | "auto" | "avoid" | "curved" |
"orthogonal") selects the built-in behaviour. The mode is saved in the
diagram JSON (routeMode) and restored without forcing a route; files
written before this feature load as straight. Experimental router names
are also persisted; unknown names on load fall back to the built-in router.
Appendix: pynsource heritage and variations¶
wxdiagram began life as the canvas inside
pynsource, and the spring layout shares
that ancestry. pynsource's GraphLayoutSpring was itself ported from
Graph::Layouter::Spring and a JavaScript version. When the canvas was
extracted into this library, the layout was reworked as a generic,
deterministic, node-size-aware engine rather than copied verbatim. The
wxdiagram module describes itself as a clean-room port; pynsource remains GPL3
and wxdiagram is MIT.
The two engines are deliberately separate, not an unfinished deduplication. pynsource still ships its original engine because its layout is only one stage of a larger application pipeline:
CoordinateMappermaps dimensionlesslayoutPosX/layoutPosYvalues to world pixels and drives the expand/contract commands.OverlapRemovalhandles node–node and line–node overlaps with margins.GraphSnapshotMgrandLayoutBlackboardrun deep layout, score several candidates and animate/snapshot the result.
How the implementations differ¶
| Aspect | pynsource GraphLayoutSpring |
wxdiagram SpringLayout |
|---|---|---|
| Purpose | pynsource application pipeline | generic library engine |
| Starting positions | all nodes at (0, 0) + random jitter |
sorted grid |
| Iterations | 1500 | 500 with early stopping |
| Output | unitless layout coordinates | top-left pixel positions |
| Node size | not used by the force kernel | used for scaling and spacing |
| Disconnected components | handled by the surrounding pipeline | packed into a grid |
| Overlap handling | separate, richer OverlapRemoval pass |
simple separation pass |
| Crossings | measured by pynsource's graph metrics | local reduce_crossings refinement |
| Determinism | random jitter, no seed | seeded and repeatable |
| Cancellation | gui.kill_layout polled during layout |
on_step callback returning False |
| Tests | pure layout tests need no wx import | importing wxdiagram.layout* imports the wx package |
Because of these differences, swapping pynsource's engine for this one is a
user-visible layout change, not a refactor. It also has consequences for
deep-layout candidate generation, overlap metrics and pure tests. The
decision record and the checks required before any future swap live in
pynsource/Admin/LAYOUT-WXDIAGRAM-CONSIDERATIONS.md.
If you are writing a generic diagram application, use SpringLayout as
documented above. If you need pynsource's exact historic layout behaviour,
use pynsource's own engine; it is intentionally application-specific.