Path graph: multilane-highway flow, bezier lane changes, no doubled edges

Every node now sits on a level platform: an edge leaves level, shifts
once, arrives level, so an off-lane relay reads as a flat-topped
trapezium instead of a pointed peak or valley. The shift itself is a
cubic-bezier S-curve with horizontal tangents at both ends, easing out
of one platform and settling into the next with no corner anywhere.

Every edge is keyed by its unordered node pair and drawn exactly once,
killing the doubled/offset lines that came from a pair walked in both
directions. That bidirectional pair is the sole edge drawn as a bare
straight segment (near-vertical when the layout stacks the markers) —
the one place an up-and-down line is the honest picture.

A direction arrow embeds in the trunk just before us, so the whole
graph reads as a directed run node → us.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Opus 4.8 committed 2026-07-21 21:06:26 -04:00
1 parent 9cf5a9cc78
commit 891487e928
5 files changed
+404 -307

No files matched your search

+4 -3
View File
@@ -11,7 +11,7 @@ detail read together:
right, and every relay in between gets its own node-type marker (``▲`` repeater, …)
plus the first byte of its hash — set straight above or below the marker, in the mesh
name's own colour, so the byte reads as that node and never crowds the line running
through it. A node-type key sits under the fan. The row list carries the full names,
through it. A node-type key sits under the graph. The row list carries the full names,
so the graph's labels stay two cells wide and a many-path graph stays readable.
* the **arrival list** beneath is one row per logged copy — time, reception SNR, and
the relay chain through the shared compact path widget, each named hop annotated
@@ -270,8 +270,9 @@ class MessagePathsScreen(Screen):
def _graph_lines(self, width: int) -> list[str]:
"""Draw every distinct path origin → us, the selected one white over gray.
The shared route-graph widget does the layout (a layered left-to-right graph,
each relay drawn once in its own column); this just maps each distinct path to a
The shared route-graph widget does the layout (a left-to-right flow of paths that
diverge and converge, each route its own lane and each relay drawn once); this just
maps each distinct path to a
:class:`~meshterm.ui.pathgraph.PathLayer` — the selected one white on top, the
rest gray beneath — and hands it the shared route-graph callbacks
(:func:`~meshterm.ui.widgets.route_graph_style`): endpoints named, relays their
+3 -3
View File
@@ -74,9 +74,9 @@ _MAP_ROWS = 7
#: Route-graph tuning for this page. It draws the contact on the left and us on the right
#: (node → us, so the graph reads left to right as the inbound direction its packets
#: travelled to reach us). A well-connected node offers several candidate paths at once, and
#: cramming them into a short box overlaps the lanes into an unreadable tangle — so this page
#: gives the fan a generous lane step and row budget, letting each path spread into its own
#: clearly separated track. The height is adaptive: it grows only with the number of distinct
#: cramming them into a short box compresses the lanes together — so this page gives each lane
#: a generous step and row budget, letting each route spread into its own clearly separated
#: track. The height is adaptive: it grows only with the number of distinct
#: lanes, so a node with one or two routes still draws compact while a busy one earns the room
#: it needs. The page scrolls (PgUp/PgDn), so a tall graph never crowds the action rows off.
_PATH_LANE_STEP = 15
+341 -299
View File
@@ -1,30 +1,47 @@
"""THE route-graph widget: hop sequences drawn as a tidy left-to-right layered graph.
"""THE route-graph widget: hop sequences drawn as a left-to-right flow of paths.
Extracted from the Message paths dialog so every screen that draws walked (or planned)
routes draws them the same way. A *layer* is one path — its relay hops, an edge colour,
and a draw priority — and the widget lays every distinct path out between a left and a
right endpoint marker.
and a draw priority — and the widget lays every distinct path out between a shared left
and right endpoint marker.
Rather than fanning the paths as free lanes and averaging shared relays (which pulls
lines into acute tangles wherever many paths meet the two endpoints), the widget draws
the paths as one **layered graph**, the way a subway map or a dependency chart reads:
Every path shares its two endpoints (an origin on the left, us on the right) and is walked
left to right, so the picture is a *flow*: routes that **diverge** out of the origin, run
their own course, and **converge** back into us, sharing a relay wherever their walks agree.
Earlier drawings tried a vertical *bus* the lanes tapped at right angles (a metro map you
wander around, the bare 90° turns hiding that A flows to B), then oblique branches straight
off each marker (which left every off-lane relay a pointed *peak* or *valley*). The widget
now draws the fan as a **multilane highway**: a node always sits on a level platform in its
lane, and a route changes lane only *between* nodes, easing across on a single gentle shift
the way a car drifts one lane over and then stays there. Concretely:
* **ranks** (columns) are hop distance from the left endpoint — a node sits in the column
of its *furthest* appearance across the paths, so every edge runs strictly left-to-right
and a relay shared by several routes is drawn **once**, in one place;
* **long edges** — a path that skips a column (a direct shot past where another route
stops to relay) — are routed through invisible waypoints at each column it crosses, so
the line bends around the intervening nodes instead of slicing through them;
* **within a column** the nodes are ordered to minimise crossings (a few barycentre
sweeps), then spread down the full available height with their vertical positions
pulled toward the average of their neighbours — straightening each route into a lane
while keeping the branches far enough apart to leave readable (~60°) angles;
* **shared cells** go to the highest-priority layer (drawn last), so e.g. the Message
paths dialog's selected path reads white over the unused grey;
* **lanes** — each distinct path owns one horizontal lane; the highest-priority (drawn last,
e.g. the selected or best-evidence) path takes the centre lane, running dead straight
through the two endpoints as the flow's spine, and the alternatives lie above and below it.
The lanes are ordered to seat routes that share relays near each other, so a shared hop
costs the shortest possible detour;
* **columns** (x) place each node by *balanced* rank — its distance from the origin over its
distance-plus-remaining-distance to us — so a path's relays spread evenly between the two
ends however long the other paths are, and a shared relay lands in one place;
* **platforms** — every node is entered and left along a level run in its own lane, so a
relay that sits off its neighbours' lane reads as a flat-topped *trapezium*, never a
pointed peak or valley. Between two nodes on different lanes the line stays level out of the
first, makes one oblique shift, and runs level into the second — the only corners are the
soft level→oblique bends of the shift, never a bare right angle in open canvas;
* **shared relays** draw as a single marker (a route re-using a hop is not a new node): the
marker sits on its highest-priority path's lane, and a lower path that also rides it leans
off its lane to meet the platform and back — which reads as the alternative *branching
through the shared node*, exactly the story the evidence tells;
* **diverge / converge** — the fan at each end is flow, not a switchboard: routes leave the
origin overlapping on the centre line and peel off one by one to their lanes (the
divergence), and mirror that back into us on the right (the convergence). Every edge draws
exactly once, however many routes share it; the one edge drawn as a bare vertical is a pair
of nodes walked in *both* directions — a genuine two-way hop, the sole place a straight
up-and-down line tells the truth;
* **labels** sit straight above or below their marker — pushed to the side away from the
graph's middle, a spot clear of the drawn lines preferred — and endpoints slide their
label inward from the canvas edge so a long name still lands by its marker. A caller
that wants a node unlabelled returns ``None`` for it.
label inward from the canvas edge so a long name still lands by its marker. A caller that
wants a node unlabelled returns ``None`` for it.
Everything renders onto a :class:`~meshterm.ui.mapcanvas.MapCanvas`; the caller supplies
the per-node glyph/label/colour callbacks, so the widget stays free of contact-list and
@@ -33,8 +50,8 @@ theme concerns.
from __future__ import annotations
from collections import defaultdict
from dataclasses import dataclass
from itertools import permutations
from math import ceil
from typing import Callable, Optional, Sequence
@@ -45,44 +62,59 @@ from .mapcanvas import RGB, MapCanvas, parse_hex
SRC_NODE = "\x00src"
DST_NODE = "\x00dst"
#: Prefix for the invisible waypoint ids a long edge is routed through — one per column
#: it crosses. Never handed to the caller's callbacks (waypoints draw line only).
_VIRTUAL_PREFIX = "\x00v"
#: Vertical dot separation aimed for between adjacent nodes sharing a column — the base
#: "lane" height one unit of the layout maps to. Wide enough to seat a marker and its
#: label row; a tall graph compresses it to fit, a sparse one stretches it (bounded by
#: :data:`_MAX_STRETCH`) to spend the height it has on airier, less acute branch angles.
#: Vertical dot separation aimed for between adjacent lanes — the base height one lane maps
#: to. Wide enough to seat a marker and its label row; a graph with many lanes compresses it
#: to fit the row budget, and a graph with few lanes never stretches *past* it (spreading the
#: lanes further apart would only reintroduce the empty space the layout exists to avoid), so
#: a sparse graph draws compact rather than splayed.
_LANE_STEP_DOTS = 14
#: How far the lane step may stretch beyond :data:`_LANE_STEP_DOTS` when a graph has few
#: rows to fill — enough to open the branch angles up without blowing a two-node fork out
#: to the full height.
_MAX_STRETCH = 1.8
#: Dots reserved beyond the outermost node at each end of the graph — a label row for
#: that node's marker, plus a little air. The box is sized and centred on the graph's
#: real vertical extent (which is rarely symmetric), so it spends its rows on the paths
#: rather than on a mirrored half that stays empty.
#: Dots reserved beyond the outermost lane at each end of the graph — a label row for that
#: lane's markers, plus a little air.
_GRAPH_END_DOTS = 8
#: The dot row within a character cell a horizontal edge line is aimed at — the
#: upper-middle of the cell's 2×4 pixel grid (rows 0..3 top-down), where a one-dot
#: line reads as running through the glyph rather than hugging its bottom edge. Every
#: node's y is snapped onto this row (see ``_mid_row``) so same-column runs stay level.
_CELL_MID_DOT = 1
#: The dot row within a character cell a horizontal edge line is aimed at — the upper-middle
#: of the cell's 2×4 pixel grid (rows 0..3 top-down), where a one-dot line reads as running
#: through the glyph rather than hugging its bottom edge. Every lane's y is snapped onto this
#: row (see :func:`_mid_row`) so a level run stays level and same-column markers align.
_CELL_MID_DOT = 2
#: Dot-space margin the endpoint markers keep from the canvas edges.
_GRAPH_PAD_DOTS = 6
#: Minimum vertical separation, in layout units, between two nodes in the same column —
#: one lane. The ordering/placement passes never seat two markers closer than this.
_MIN_LANE_GAP = 1.0
#: A lane change spends this many dots of horizontal run per dot of vertical offset — the
#: shift's aspect ratio. Above 1 the oblique lies flatter than 45°, drifting across the way a
#: car eases between highway lanes rather than cutting; the level platforms on either side
#: (where the node sits) take whatever span is left.
_SHIFT_RATIO = 1.0
#: The shortest horizontal run a lane change is given even for a one-lane hop, so a tight
#: column gap still bends across a few dots rather than snapping over in one abrupt step.
_MIN_SHIFT_DOTS = 4
#: How far (as a fraction of the shift's horizontal span) the bezier control points sit in
#: from each end — both placed level with their own end, so the curve leaves and enters the
#: platforms horizontally. Near ½ the S is at its roundest; lower tightens it toward a
#: straight diagonal with only its corners eased.
_BEND_K = 0.5
#: Dots left of our marker the flow arrow sits — one cell, so it embeds in the trunk as ``▶★``
#: and marks the node → us direction without crowding the endpoint.
_ARROW_GAP_DOTS = 2
#: Most distinct paths the lane order is optimised over by exhaustive search. Beyond it the
#: search space (``(n-1)!`` orders of the non-central lanes) is too large, so a barycentre
#: heuristic seats the lanes instead. The widget's real inputs sit far under this.
_MAX_EXACT_LANES = 8
#: Sweeps of the barycentre lane-ordering heuristic used past :data:`_MAX_EXACT_LANES`.
_ORDER_SWEEPS = 8
#: The glyph used for the flow arrow embedded in the trunk just before us,
#: so the whole flow reads better as a directed run node → us (not a map you wander).
#_ARROW_GLYPH = "▶"
_ARROW_GLYPH = ""
#: Sweeps of the crossing-minimisation and vertical-straightening relaxations. The graphs
#: are tiny (a handful of nodes over a handful of columns), so a few passes converge.
_ORDER_SWEEPS = 6
_PLACE_ITERS = 10
#: A node's graph marker: the glyph and its ``#rrggbb`` colour (the shared node-glyph
#: tuples from :mod:`~meshterm.ui.map_render` / :mod:`~meshterm.ui.widgets` fit as-is).
@@ -104,7 +136,8 @@ class PathLayer:
path runs endpoint to endpoint straight across).
color: The edge colour the path draws in.
priority: Draw priority — where paths share a cell, the highest priority
keeps it (its edges are also drawn last).
keeps it (its edges are also drawn last), and the highest-priority path
takes the straight centre lane.
"""
hops: tuple[str, ...]
@@ -112,33 +145,13 @@ class PathLayer:
priority: int
@dataclass
class _LayoutNode:
"""A vertex the layout positions — a real node, an endpoint, or an edge waypoint.
Attributes:
node: The id handed to the caller's callbacks (``SRC_NODE``/``DST_NODE`` for the
endpoints, a hop hash for a relay), or a ``_VIRTUAL_PREFIX`` id for a waypoint.
rank: The column (hop distance from the left endpoint) the node sits in.
real: Whether the node carries a marker and label (waypoints are line-only).
order: Its position within the column, top to bottom (set by the ordering pass).
y: Its vertical coordinate — layout units during placement, canvas dots after.
"""
node: str
rank: int
real: bool
order: int = 0
y: float = 0.0
def _mid_row(y_dot: float) -> int:
"""Snap a dot row onto the upper-middle dot of its character cell.
A braille cell is four dot rows tall; a horizontal line drawn on the top or
bottom row hugs the glyph's edge and reads as sitting too high or too low.
Snapping every node's y to :data:`_CELL_MID_DOT` keeps markers — and the level
runs between same-column nodes — centred in the cell's pixel space.
A braille cell is four dot rows tall; a horizontal line drawn on the top or bottom row
hugs the glyph's edge and reads as sitting too high or too low. Snapping every lane's y
to :data:`_CELL_MID_DOT` keeps markers — and the level runs along a lane — centred in the
cell's pixel space.
"""
return round((y_dot - _CELL_MID_DOT) / 4) * 4 + _CELL_MID_DOT
@@ -234,43 +247,6 @@ def _is_hex(value: str) -> bool:
return bool(value) and all(char in _HEX_DIGITS for char in value)
def _pava(values: list[float]) -> list[float]:
"""Pool-adjacent-violators: the nearest non-decreasing sequence to ``values`` (L2).
The engine behind :func:`_pack` — it fits a monotone curve to the desired positions,
merging any run that would step backwards into its weighted mean.
"""
means: list[float] = []
counts: list[int] = []
for value in values:
means.append(value)
counts.append(1)
while len(means) > 1 and means[-2] > means[-1]:
m2, c2 = means.pop(), counts.pop()
m1, c1 = means.pop(), counts.pop()
means.append((m1 * c1 + m2 * c2) / (c1 + c2))
counts.append(c1 + c2)
out: list[float] = []
for mean, count in zip(means, counts):
out.extend([mean] * count)
return out
def _pack(desired: list[float], gap: float) -> list[float]:
"""Place ordered nodes as close to their desired ys as a minimum gap allows.
Given each node's preferred y (the average of its neighbours) in column order, return
ys that stay in that order with at least ``gap`` between neighbours and minimise the
total squared shift — the optimal one-dimensional separation, via isotonic regression:
subtract the running gap, fit a monotone curve (:func:`_pava`), add the gap back.
"""
if not desired:
return []
shifted = [value - i * gap for i, value in enumerate(desired)]
fitted = _pava(shifted)
return [value + i * gap for i, value in enumerate(fitted)]
def render_path_graph(
layers: Sequence[PathLayer],
width: int,
@@ -282,24 +258,25 @@ def render_path_graph(
max_rows: int = 15,
lane_step: int = _LANE_STEP_DOTS,
) -> list[str]:
"""Draw the layered route graph and return its ANSI lines.
"""Draw the diverge/converge route-flow graph and return its ANSI lines.
Args:
layers: The paths to draw, in draw order (later layers, and higher priorities,
win shared cells). Layers with identical hop sequences collapse to one drawn
path owned by the highest priority among them.
win shared cells; the highest priority takes the straight centre lane). Layers
with identical hop sequences collapse to one drawn path owned by the highest
priority among them.
width: Canvas width in character cells.
glyph_of: Marker glyph + colour per node id (endpoints keyed by
:data:`SRC_NODE` / :data:`DST_NODE`).
label_of: Label text per node id (``None``/``""`` = bare marker). A label is
kept whole unless it is wider than the canvas, when it is ellipsized to fit.
label_rgb_of: Label colour per node id.
min_rows: The fewest canvas rows to draw, however flat the graph.
max_rows: The most canvas rows to spend; a taller graph compresses its lane
spacing to fit.
lane_step: Vertical dot separation aimed for between column-mates. A smaller step
packs the graph into a shallower band; a larger one opens the branch angles
up. Bounded by the row budget either way. Defaults to :data:`_LANE_STEP_DOTS`.
min_rows: The fewest canvas rows to draw, however few the lanes.
max_rows: The most canvas rows to spend; a graph with more lanes than fit
compresses its lane spacing rather than growing past this.
lane_step: Vertical dot separation aimed for between lanes. A larger step opens the
lanes apart; the row budget compresses it when there are many lanes, and never
stretches past it when there are few. Defaults to :data:`_LANE_STEP_DOTS`.
Returns:
One ANSI string per canvas row (empty when there are no layers to draw).
@@ -310,229 +287,294 @@ def render_path_graph(
drawn = _collapse(_coalesce_prefixes(layers))
seqs = [(SRC_NODE, *layer.hops, DST_NODE) for layer in drawn]
# First-appearance order for every node and edge, so the layout is identical on every
# repaint: a set of hash-seeded string ids would iterate in a run-varying order and let
# the ordering pass settle differently each time, making the graph jump between frames.
# First-appearance order for every node, so the layout is identical on every repaint: a
# set of hash-seeded string ids would iterate in a run-varying order and let the passes
# settle differently each time, making the graph jump between frames.
ordered_nodes: list[str] = []
ordered_edges: list[tuple[str, str]] = []
seen_nodes: set[str] = set()
seen_edges: set[tuple[str, str]] = set()
seen: set[str] = set()
edges: set[tuple[str, str]] = set()
for seq in seqs:
for node in seq:
if node not in seen_nodes:
seen_nodes.add(node)
if node not in seen:
seen.add(node)
ordered_nodes.append(node)
for u, v in zip(seq, seq[1:]):
if (u, v) not in seen_edges:
seen_edges.add((u, v))
ordered_edges.append((u, v))
edges.update(zip(seq, seq[1:]))
# -- Ranks (columns): the longest path (in edges) from the source to each node. Ranking
# by longest path — not merely a node's furthest position in some one sequence — is what
# guarantees every edge steps strictly forward (``rank(v) ≥ rank(u) + 1``): a relay that
# one route reaches late is seated in the deeper column, so no edge ever doubles back or
# runs *within* a column (which would draw as a stray vertical bar). The right endpoint,
# the sink of every path, takes the deepest rank of all. Relaxed to a fixed point, capped
# at the node count so a pathological order-flipped pair can't spin it forever.
rank: dict[str, int] = {node: 0 for node in ordered_nodes}
for _ in range(len(ordered_nodes)):
changed = False
for u, v in ordered_edges:
if rank[v] < rank[u] + 1:
rank[v] = rank[u] + 1
changed = True
if not changed:
break
max_rank = max(rank.values())
xfrac = _balanced_x(ordered_nodes, edges)
# -- Edges routed. An edge that spans more than one column is broken over invisible
# waypoints, one per crossed column, so the drawn line bends around the nodes between its
# ends instead of cutting across them. ``route`` maps each directed edge to the full
# waypoint chain the drawing pass threads its line through.
route: dict[tuple[str, str], list[str]] = {}
nodes: dict[str, _LayoutNode] = {}
# A node draws on its highest-priority owning path — the first (by priority, then
# appearance) to carry it — so a shared relay sits once, on the strongest route through it,
# and weaker routes jog to meet it. A path that introduces no node of its own (every hop
# already owned by a stronger route) is *subsumed*: it earns no lane and simply threads the
# markers others placed, so it costs no empty band.
best = max(range(len(drawn)), key=lambda j: drawn[j].priority)
owner: dict[str, int] = {}
for i in sorted(range(len(drawn)), key=lambda j: -drawn[j].priority):
for node in seqs[i]:
owner.setdefault(node, i)
lane_of_path = _assign_lanes(drawn, seqs, owner, best)
def ensure(node: str, node_rank: int, real: bool) -> None:
if node not in nodes:
nodes[node] = _LayoutNode(node=node, rank=node_rank, real=real)
# The endpoints sit on the best path's lane, where the strongest route runs dead straight
# across as the graph's spine; the alternatives fan above and below it.
max_lane = max(lane_of_path.values())
centre_lane = float(lane_of_path[best])
node_lane: dict[str, float] = {
node: (centre_lane if node in (SRC_NODE, DST_NODE) else float(lane_of_path[owner[node]]))
for node in ordered_nodes
}
for node in ordered_nodes:
ensure(node, rank[node], real=True)
virtual = 0
for u, v in ordered_edges:
chain = [u]
for r in range(rank[u] + 1, rank[v]):
vid = f"{_VIRTUAL_PREFIX}{virtual}"
virtual += 1
ensure(vid, r, real=False)
chain.append(vid)
chain.append(v)
route[(u, v)] = chain
columns: dict[int, list[str]] = defaultdict(list)
for node in nodes.values():
columns[node.rank].append(node.node)
# -- Adjacency over the routed (waypoint-inclusive) graph, for ordering + straightening.
adjacent: dict[str, list[str]] = defaultdict(list)
for chain in route.values():
for a, b in zip(chain, chain[1:]):
adjacent[a].append(b)
adjacent[b].append(a)
_order_columns(columns, adjacent, nodes)
extent = _place_columns(columns, adjacent, nodes)
# -- Vertical sizing: fill the row budget with the graph's real extent, stretching a
# sparse graph (bounded) for airier angles and compressing a busy one to fit.
if extent <= 0:
# -- Vertical sizing: size the rows to the lanes, compressing the spacing (never
# stretching it past ``lane_step``) so a busy graph fits and a sparse one stays compact.
if max_lane <= 0:
step = 0.0
rows = min_rows
else:
ideal = extent * lane_step + 2 * _GRAPH_END_DOTS
ideal = max_lane * lane_step + 2 * _GRAPH_END_DOTS
rows = max(min_rows, min(max_rows, ceil(ideal / 4)))
avail = rows * 4 - 2 * _GRAPH_END_DOTS
step = min(avail / extent, lane_step * _MAX_STRETCH)
step = min(float(lane_step), avail / max_lane)
canvas = MapCanvas(width, rows)
dot_w = width * 2
span = dot_w - 2 * _GRAPH_PAD_DOTS
min_y = min(node.y for node in nodes.values())
band = extent * step
top = (rows * 4 - band) / 2 # centre the real extent in the chosen rows
band = max_lane * step
top = (rows * 4 - band) / 2 # centre the lane band in the chosen rows
def x_of(node_rank: int) -> int:
return _GRAPH_PAD_DOTS + round(node_rank / max_rank * span) if max_rank else dot_w // 2
def x_of(node: str) -> int:
return _GRAPH_PAD_DOTS + round(xfrac[node] * span)
pos: dict[str, tuple[int, int]] = {}
for node in nodes.values():
pos[node.node] = (x_of(node.rank), _mid_row(top + (node.y - min_y) * step))
mid_y = rows * 2 # canvas vertical middle, in dots — the side labels push away from
# -- Edges: ascending priority, so where paths share cells the top layer draws last
# and keeps them. Each layer threads its line through the waypoint chain of every edge.
pos: dict[str, tuple[int, int]] = {
node: (x_of(node), _mid_row(top + node_lane[node] * step)) for node in ordered_nodes
}
# -- Edges. Collect every edge once, keyed by its unordered node pair: an edge two routes
# share — or a pair walked in *both* directions — must draw a single time, else it silts up
# as a doubled line a dot off itself (two routes' Bresenham runs never land on the exact
# same dots). Each pair keeps the colour and priority of the strongest route through it; a
# two-way pair is flagged so it draws as the one honest vertical rather than a lane change.
bidir = {frozenset((u, v)) for (u, v) in edges if (v, u) in edges}
edge_style: dict[frozenset[str], tuple[int, RGB]] = {}
for layer, seq in sorted(zip(drawn, seqs), key=lambda ls: ls[0].priority):
for u, v in zip(seq, seq[1:]):
points = [pos[node] for node in route[(u, v)]]
canvas.draw_line(points, layer.color, layer.priority)
key = frozenset((u, v))
prev = edge_style.get(key)
if prev is None or layer.priority > prev[0]:
edge_style[key] = (layer.priority, layer.color)
# Draw ascending by priority so the strongest route's colour wins any cell two edges share.
for key, (priority, color) in sorted(edge_style.items(), key=lambda kv: kv[1][0]):
u, v = tuple(key)
canvas.draw_line(_route(u, v, pos, key in bidir), color, priority)
# -- Markers for every real node; waypoints stay line-only.
for node in nodes.values():
if not node.real:
continue
glyph, color_hex = glyph_of(node.node)
canvas.marker(*pos[node.node], glyph, parse_hex(color_hex))
# -- An arrow embedded in the trunk just before us, so the whole flow reads as a directed
# run node → us (not a map you wander). A single glyph in the spine's own colour: it reserves
# its cell, so the endpoint label routes around it rather than colliding with stray dots.
ax, ay = pos[DST_NODE]
canvas.marker(ax - _ARROW_GAP_DOTS, ay, _ARROW_GLYPH, drawn[best].color)
_place_labels(canvas, nodes, pos, width, mid_y, label_of, label_rgb_of)
# -- Markers for every node (endpoints and relays alike each draw once).
for node in ordered_nodes:
glyph, color_hex = glyph_of(node)
canvas.marker(*pos[node], glyph, parse_hex(color_hex))
_place_labels(canvas, ordered_nodes, pos, node_lane, width, rows * 2, label_of, label_rgb_of)
return canvas.to_ansi_lines()
def _order_columns(
columns: dict[int, list[str]],
adjacent: dict[str, list[str]],
nodes: dict[str, _LayoutNode],
) -> None:
"""Order the nodes within each column to reduce edge crossings (barycentre sweeps).
def _route(
u: str,
v: str,
pos: dict[str, tuple[int, int]],
bidir: bool,
) -> list[tuple[float, float]]:
"""The point chain for one edge (dot coordinates), drawn as multilane-highway flow.
Starting from first-appearance order, each node is repeatedly re-seated at the mean
position of its neighbours in the column just settled — down the ranks, then up —
which is the standard cheap crossing-minimiser. A node with no neighbour in the
reference column keeps its place. The results are written back as each node's
``order`` (its index within the column).
Two nodes on the same lane join with a level run; two on different lanes join with a
*trapezium* — level out of the first marker, one smooth **shift** across the intervening
lanes (a bezier lane change, level where it meets each platform; see :func:`_sbend`), then
level into the second — so both nodes sit on a flat platform and there is no corner
anywhere, only the eased level→curve→level of the shift. The shift is sized by
:data:`_SHIFT_RATIO` (a gentle drift, not a 45° cut) and centred in the span, so the
platforms flank it evenly; when the column gap is too tight to hold both platforms and the
shift, the bend simply spans the whole gap. The endpoints, sitting on the centre lane,
make the origin's diverging peels and us's converging merges fall out of this one rule —
no endpoint special case. The lone exception is ``bidir``: a pair walked both ways draws as
a single straight segment between the markers (a near-vertical when the layout stacks
them), the one place an up-and-down line is the honest picture.
"""
order: dict[str, int] = {}
for column in columns.values():
for i, node in enumerate(column):
order[node] = i
(xu, yu), (xv, yv) = pos[u], pos[v]
if bidir:
return [(xu, yu), (xv, yv)]
if xu > xv: # orient the trapezium left→right; balanced rank only ties, never inverts
(xu, yu), (xv, yv) = (xv, yv), (xu, yu)
if yu == yv:
return [(xu, yu), (xv, yv)]
dx = xv - xu
dy = abs(yv - yu)
shift = min(dx, max(round(dy * _SHIFT_RATIO), _MIN_SHIFT_DOTS))
stub = (dx - shift) // 2
# Level stub, a bezier S across the shift (level tangents at both ends, so it eases out of
# and back into the platforms with no corner), then the level stub into the far marker.
return [(xu, yu), *_sbend(xu + stub, yu, xv - stub, yv), (xv, yv)]
max_rank = max(columns)
def barycentre(node: str, ref_rank: int) -> float:
refs = [order[n] for n in adjacent[node] if nodes[n].rank == ref_rank]
return sum(refs) / len(refs) if refs else float(order[node])
def _sbend(
x0: float, y0: float, x1: float, y1: float
) -> list[tuple[float, float]]:
"""Sample a cubic-bezier S-curve from ``(x0, y0)`` to ``(x1, y1)``, level at both ends.
Both control points sit level with their own endpoint (:data:`_BEND_K` of the span in from
each side), so the curve's tangent is horizontal where it meets the platforms — the smooth
lane change that drifts across and settles rather than cutting a hard diagonal. Sampled
densely enough that the polyline rasterizes as a continuous curve; the convex hull keeps it
inside the ``(x0, y0)–(x1, y1)`` box, so it never overshoots its lane or column.
"""
cx0 = x0 + _BEND_K * (x1 - x0)
cx1 = x1 - _BEND_K * (x1 - x0)
samples = max(4, int(abs(x1 - x0) + abs(y1 - y0)))
pts: list[tuple[float, float]] = []
for i in range(samples + 1):
t = i / samples
mt = 1.0 - t
a, b, c, d = mt * mt * mt, 3 * mt * mt * t, 3 * mt * t * t, t * t * t
pts.append((a * x0 + b * cx0 + c * cx1 + d * x1, a * y0 + b * y0 + c * y1 + d * y1))
return pts
def _balanced_x(ordered_nodes: list[str], edges: set[tuple[str, str]]) -> dict[str, float]:
"""Each node's horizontal position in ``0..1`` — balanced rank from origin toward us.
A node's fraction is its longest-path distance from the origin over that distance plus
its longest remaining distance to us: the origin lands at ``0``, us at ``1``, and every
other node between them in proportion to how far along its route it sits. So a path's
relays spread *evenly* between the two ends however many hops the other paths take — a
lone relay on a one-hop route lands mid-canvas rather than jammed against the origin with
a long edge arcing across to us — and a relay shared by routes of different lengths still
resolves to one x. Because every edge steps the from-origin distance up and the
to-us distance down, the fraction rises strictly along each path: edges only ever run
left to right.
"""
up = _longest_paths(ordered_nodes, edges)
down = _longest_paths(ordered_nodes, {(v, u) for u, v in edges})
return {
node: (up[node] / (up[node] + down[node])) if (up[node] + down[node]) else 0.0
for node in ordered_nodes
}
def _longest_paths(ordered_nodes: list[str], edges: set[tuple[str, str]]) -> dict[str, int]:
"""Longest-path depth of each node over ``edges`` (relaxed to a fixed point).
Capped at the node count so a pathological cycle in the id set can't spin it forever;
the graphs are acyclic fans, so it settles in a couple of passes.
"""
depth = {node: 0 for node in ordered_nodes}
for _ in range(len(ordered_nodes)):
changed = False
for u, v in edges:
if depth[v] < depth[u] + 1:
depth[v] = depth[u] + 1
changed = True
if not changed:
break
return depth
def _assign_lanes(
drawn: Sequence[PathLayer],
seqs: Sequence[tuple[str, ...]],
owner: dict[str, int],
best: int,
) -> dict[int, int]:
"""Seat each lane-bearing path on a horizontal lane, best centred, sharing routes close.
Returns ``{path_index: lane}`` — only for the paths that own at least one node (a subsumed
path threads others' markers and needs no lane of its own) — with lanes ``0`` (top) up. The
best path is pinned to the centre lane, where it runs straight through the two endpoints as
the graph's spine; the rest are ordered to minimise the total *jog* — the vertical distance
a path travels to reach a relay another path owns — so routes that share hops sit near each
other and a shared relay costs the shortest detour. Small graphs
(``≤`` :data:`_MAX_EXACT_LANES` lanes) get the exact best order by search; larger ones fall
back to a barycentre heuristic.
"""
bearing = [i for i in range(len(drawn)) if any(owner[node] == i for node in seqs[i])]
n = len(bearing)
if n == 1:
return {bearing[0]: 0}
# Each bearing path's jog partners: the owning lanes of the hops it borrows from others.
shared_owners = {
i: [owner[node] for node in seqs[i] if owner[node] != i] for i in bearing
}
def jog(lane: dict[int, int]) -> int:
return sum(abs(lane[i] - lane[o]) for i in bearing for o in shared_owners[i])
centre_slot = (n - 1) // 2
others = [i for i in bearing if i != best]
if n - 1 <= _MAX_EXACT_LANES:
best_order: Optional[tuple[int, ...]] = None
best_cost: Optional[int] = None
for perm in permutations(others):
slots = list(perm)
slots.insert(centre_slot, best)
cost = jog({p: k for k, p in enumerate(slots)})
if best_cost is None or cost < best_cost:
best_cost, best_order = cost, tuple(slots)
assert best_order is not None
return {p: k for k, p in enumerate(best_order)}
return _barycentre_lanes(bearing, best, centre_slot, shared_owners)
def _barycentre_lanes(
bearing: list[int],
best: int,
centre_slot: int,
shared_owners: dict[int, list[int]],
) -> dict[int, int]:
"""Heuristic lane order for a graph too large to search: barycentre sweeps.
Each path is repeatedly re-seated at the average lane of the paths it shares relays with,
with the best path pinned to the centre lane. A handful of sweeps settles sharing routes
next to each other — the cheap crossing-minimiser, at the coarser grain of whole lanes.
"""
lane = {p: float(k) for k, p in enumerate(bearing)}
lane[best] = float(centre_slot)
others = [i for i in bearing if i != best]
for _ in range(_ORDER_SWEEPS):
for r in range(1, max_rank + 1):
columns[r].sort(key=lambda n: barycentre(n, r - 1)) # noqa: B023 - r is bound per loop
for i, node in enumerate(columns[r]):
order[node] = i
for r in range(max_rank - 1, -1, -1):
columns[r].sort(key=lambda n: barycentre(n, r + 1)) # noqa: B023 - r is bound per loop
for i, node in enumerate(columns[r]):
order[node] = i
for column in columns.values():
for i, node in enumerate(column):
nodes[node].order = i
def _place_columns(
columns: dict[int, list[str]],
adjacent: dict[str, list[str]],
nodes: dict[str, _LayoutNode],
) -> float:
"""Assign each node a vertical coordinate (layout units) and return the total extent.
Seeded from the column orders, every node is pulled toward the average height of its
neighbours and its column re-separated to the minimum lane gap (:func:`_pack`) — a few
passes each way. This straightens each route into a near-level lane while keeping
branches apart; an endpoint, being the lone node in its column, drifts to the centroid
of its own branches so the whole fan reads as leaving (or arriving at) one point.
Returns ``max_y - min_y`` across all nodes, the height the caller scales to the canvas.
"""
for column in columns.values():
for node in column:
nodes[node].y = float(nodes[node].order)
max_rank = max(columns)
ranks_desc = list(range(max_rank + 1))
def relax(order_of_ranks: list[int]) -> None:
for r in order_of_ranks:
column = columns[r]
desired = []
for node in column:
neighbours = adjacent[node]
if neighbours:
desired.append(sum(nodes[n].y for n in neighbours) / len(neighbours))
else:
desired.append(nodes[node].y)
for node, y in zip(column, _pack(desired, _MIN_LANE_GAP)):
nodes[node].y = y
for _ in range(_PLACE_ITERS):
relax(ranks_desc)
relax(ranks_desc[::-1])
ys = [node.y for node in nodes.values()]
return max(ys) - min(ys)
for i in others:
if shared_owners[i]:
lane[i] = sum(lane[o] for o in shared_owners[i]) / len(shared_owners[i])
order = sorted(others, key=lambda i: lane[i])
order.insert(centre_slot, best)
lane = {p: float(k) for k, p in enumerate(order)}
return {p: int(lane[p]) for p in order}
def _place_labels(
canvas: MapCanvas,
nodes: dict[str, _LayoutNode],
ordered_nodes: list[str],
pos: dict[str, tuple[int, int]],
node_lane: dict[str, float],
width: int,
mid_y: int,
label_of: LabelOf,
label_rgb_of: LabelRgbOf,
) -> None:
"""Write each real node's label above or below its marker, clear of the lines if it can.
"""Write each node's label above or below its marker, clear of the lines if it can.
Endpoints first, then relays column by column, so the named ends win any contest for a
Endpoints first, then relays down the lanes, so the named ends win any contest for a
cell. Each label is tried on the side away from the graph's middle first (spreading the
text outward off the busy centre), preferring a row the drawn lines don't already
occupy; an endpoint, hard against a canvas edge, slides its anchor inward far enough for
the whole name to land, and falls back to sitting beside its marker. A name is only
ever shortened when it is wider than the entire canvas.
text outward off the busy centre), preferring a row the drawn lines don't already occupy;
an endpoint, hard against a canvas edge, slides its anchor inward far enough for the whole
name to land, and falls back to sitting beside its marker. A name is only ever shortened
when it is wider than the entire canvas.
"""
endpoints = [n for n in (DST_NODE, SRC_NODE) if n in nodes]
relays = [
layout.node
for layout in sorted(nodes.values(), key=lambda n: (n.rank, n.order))
if layout.real and layout.node not in (SRC_NODE, DST_NODE)
]
endpoints = [n for n in (DST_NODE, SRC_NODE) if n in pos]
relays = sorted(
(n for n in ordered_nodes if n not in (SRC_NODE, DST_NODE)),
key=lambda n: (node_lane[n], pos[n][0]),
)
for node in [*endpoints, *relays]:
label = label_of(node)
if not label:
+1 -1
View File
@@ -893,7 +893,7 @@ def node_type_legend(indent: str = "") -> Text:
Every glyph in its shared map colour (see :data:`_NODE_GLYPHS`), each named muted after
it. THE legend for any surface that draws typed node markers — the contacts list under its
table, the route graph under its fan — so one glyph means one thing app-wide.
table, the route graph under its lanes — so one glyph means one thing app-wide.
Args:
indent: Leading spaces to sit the legend under a table or graph body.
+55 -1
View File
@@ -1,4 +1,4 @@
"""Unit tests for the shared route-graph widget (the fan-lane braille renderer)."""
"""Unit tests for the shared route-graph widget (the diverge/converge braille renderer)."""
from __future__ import annotations
@@ -9,6 +9,7 @@ from meshterm.ui.pathgraph import (
SRC_NODE,
PathLayer,
_coalesce_prefixes,
_route,
render_path_graph,
)
@@ -129,6 +130,59 @@ def test_a_shared_relay_draws_a_single_marker() -> None:
assert plain.count("aa") == 1 and plain.count("cc") == 1
def test_every_label_shows_on_a_busy_graph() -> None:
"""Four distinct routes lay out as separated lanes — every relay label lands, none dropped."""
names = {
"aa": "Alpha", "bb": "Bravo", "cc": "Charlie", "dd": "Delta",
"ee": "Echo", "ff": "Foxtrot", "gg": "Golf",
}
layers = [
PathLayer(("aa", "bb"), WHITE, 4),
PathLayer(("cc", "dd"), GREY, 2),
PathLayer(("ee", "ff"), GREY, 2),
PathLayer(("gg",), GREY, 2),
]
plain = _ANSI.sub("", "\n".join(_render(layers, label_of=lambda n: names.get(n[:2]))))
for name in names.values():
assert name in plain, f"{name} was dropped from the graph"
def test_a_subsumed_route_adds_no_duplicate_markers() -> None:
"""A route whose hops are all carried by a stronger one draws through them, not doubled."""
layers = [
PathLayer(("aa", "bb", "cc"), WHITE, 4), # the backbone owns aa, bb, cc
PathLayer(("aa", "cc"), GREY, 2), # a shortcut over the same relays — no new node
]
plain = _ANSI.sub("", "\n".join(_render(layers)))
for hop in ("aa", "bb", "cc"):
assert plain.count(hop) == 1 # each relay seated exactly once
def test_route_seats_each_node_on_a_level_platform() -> None:
"""A lane-changing edge leaves and enters level, so neither node is a pointed apex."""
pts = _route("u", "v", {"u": (0, 1), "v": (40, 9)}, bidir=False)
assert pts[0] == (0, 1) and pts[-1] == (40, 9) # the two markers are the ends
assert pts[0][1] == pts[1][1] # level out of u — u sits flat
assert pts[-1][1] == pts[-2][1] # level into v — v sits flat
def test_route_same_lane_is_one_level_run() -> None:
"""Two nodes on the same lane join with a single straight horizontal segment."""
assert _route("u", "v", {"u": (0, 5), "v": (40, 5)}, bidir=False) == [(0, 5), (40, 5)]
def test_route_orients_left_to_right() -> None:
"""A right-to-left node pair is flipped, so the trapezium always reads as forward flow."""
forward = _route("u", "v", {"u": (0, 1), "v": (40, 9)}, bidir=False)
reverse = _route("u", "v", {"u": (40, 9), "v": (0, 1)}, bidir=False)
assert reverse == forward # same picture whichever way the pair is handed in
def test_route_bidirectional_is_a_single_straight_segment() -> None:
"""A two-way pair is the sole straight (near-vertical) edge — never a trapezium."""
assert _route("u", "v", {"u": (20, 1), "v": (24, 30)}, bidir=True) == [(20, 1), (24, 30)]
def test_labels_ellipsize_only_when_wider_than_the_canvas() -> None:
"""A name shortens only when it physically cannot fit — wider than the whole canvas."""
name = "x" * 30