From ceab414ca9615c9b9c65d65e3d3c73e7bee0da8f Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sun, 26 Jul 2026 17:07:50 -0400 Subject: [PATCH] Path graph: bypass a skipped relay through a virtual waypoint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A route that skips a relay another route rides (the A-B-C-D spine beside the shorter A-C-D) drew its skip edge as a level run straight through the skipped marker's cell — and under emphasis the subset's white repainted the spine's own run, so the skipped relay read as selected (Furthur -> YUL-Cartierville lighting C14903). _bypass_vias now bends any edge that would run level through a marker strictly between its ends — by construction a node that edge skips — around it, through an unmarked via point in the skipped node's own column on the innermost genuinely free lane: no seated marker, no other route's level run through that cell, and a lane outside the band only while _band_rows still fits max_rows (the same budget the detour fold answers to). No room anywhere keeps the honest level pass-over. _route threads the vias with its usual level-or-shift grammar, so the bypass eases out, sits level dead over the marker it clears, and eases back. Co-Authored-By: Claude Fable 5 --- meshterm/ui/pathgraph.py | 180 +++++++++++++++++++++++++++++++++++---- tests/test_pathgraph.py | 108 +++++++++++++++++++++++ 2 files changed, 270 insertions(+), 18 deletions(-) diff --git a/meshterm/ui/pathgraph.py b/meshterm/ui/pathgraph.py index ff7b7de..bfecb4d 100644 --- a/meshterm/ui/pathgraph.py +++ b/meshterm/ui/pathgraph.py @@ -55,6 +55,14 @@ over and then settles. Concretely: that extra lane **folds** the relay onto the sibling's lane itself (weakest detours first, re-measuring after each), where the sibling's run passes over it — the legible-but-lossier last resort, never the default (see :func:`_layout_lanes`); +* **bypasses** — the detour's mirror: beside the spine's ``A → B → C`` lives the shorter route + that *skips* ``B``, and with ``A`` and ``C`` seated on one lane its ``A→C`` edge is a level + run straight through the marker of the one node it doesn't ride — drawn, it reads as *via* + ``B``, the story the evidence rules out. Where the skipped node's own column has room — a + free lane just off it, or one the row budget affords opening — the edge bends around instead, + arcing through an unmarked *virtual waypoint* in that column, the same wider-arc grammar a + nested detour draws, so skipping reads as skipping (see :func:`_bypass_vias`); only a graph + with genuinely no room left keeps the level pass-over; * **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 @@ -409,14 +417,24 @@ def render_path_graph( drawn, seqs, ordered_nodes, owner, best, col_of, max_rows, lane_pitch ) + # A pair walked in *both* directions draws as the one honest vertical (the edge pass + # below) — and is likewise never bent around anything. + bidir = {frozenset((u, v)) for (u, v) in edges if (v, u) in edges} + # An edge that would run level straight through a marker it *skips* bends around it + # instead, through a virtual waypoint in the skipped node's own column — wherever the + # column has room (see :func:`_bypass_vias`). The via lanes join the band extent below, + # so the vertical sizing affords any lane a bypass opens. + vias = _bypass_vias(seqs, bidir, signed, col_of, max_rows, lane_pitch) + via_lanes = [lane for hops in vias.values() for _m, lane in hops] + # The endpoints sit at the vertical centre of the compressed lane band, where the strongest # route runs through them as the graph's spine; the alternatives fan above and below. When the # flanks balance out evenly the spine's own lane *is* that centre and it runs dead straight; # when the band is lopsided (or even-numbered) the centre falls between lanes, and the best # path eases gently to reach the endpoints rather than seating the whole graph off-centre — # a lean the balancer keeps small by flattening the flanks first. - low = min(signed.values(), default=0) - high = max(signed.values(), default=0) + low = min([*signed.values(), *via_lanes], default=0) + high = max([*signed.values(), *via_lanes], default=0) max_lane = high - low centre_lane = max_lane / 2.0 node_lane: dict[str, float] = { @@ -466,15 +484,24 @@ def render_path_graph( node: (x_of(node), _mid_row(top + slot(node_lane[node]) * 4 * scale)) for node in ordered_nodes } + # Each bypass via becomes a dot point at the skipped marker's exact x, seated on its own + # lane row through the same slot/snap the real nodes ride — the arc's level peak sits dead + # over the node it clears. + via_pts: dict[frozenset[str], list[tuple[float, float]]] = { + key: [ + (float(pos[m][0]), float(_mid_row(top + slot(float(lane - low)) * 4 * scale))) + for m, lane in hops + ] + for key, hops in vias.items() + } # -- 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 draw rank of the strongest route through it — # by draw rank, so the *emphasised* (highlighted) route wins a shared edge over a merely # higher-priority spine, and the highlight paints the whole selected route rather than - # dropping out where it overlaps another. 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} + # dropping out where it overlaps another. A two-way pair (``bidir``, above) draws as the + # one honest vertical rather than a lane change. edge_style: dict[frozenset[str], tuple[int, RGB]] = {} for layer, seq in sorted(zip(drawn, seqs), key=lambda ls: _draw_rank(ls[0])): rank = _draw_rank(layer) @@ -487,7 +514,9 @@ def render_path_graph( # two edges share and sits on top. for key, (rank, 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, rank) + canvas.draw_line( + _route(u, v, pos, key in bidir, via_pts.get(key, ())), color, rank + ) # -- 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 @@ -509,6 +538,7 @@ def _route( v: str, pos: dict[str, tuple[int, int]], bidir: bool, + vias: Sequence[tuple[float, float]] = (), ) -> list[tuple[float, float]]: """The point chain for one edge (dot coordinates), drawn as multilane-highway flow. @@ -520,24 +550,34 @@ def _route( meet the climbing curve at a corner, and that corner draws a heavy braille *knee*, so the curve runs continuously node to node instead and the marker seats on the curve's own level end tangent. The endpoints, sitting at the centre of the lane band, 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. + us's converging merges fall out of this one rule — no endpoint special case. + + ``vias`` are an edge's bypass waypoints (:func:`_bypass_vias`), threaded between the two + markers in x order: the run applies the same level-or-shift grammar anchor to anchor — + marker to via to via to marker — so a bypass eases out, sits level for an instant dead + over the marker it clears, and eases back in, never cutting through it. 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 — and never a bent one. """ (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 - shift = min(dx, max(_MIN_SHIFT_DOTS, round(dx * _CURVE_SPAN))) - stub = (dx - shift) // 2 - # A bezier S across the whole gap (level tangents at both ends, so it eases out of and back - # into each marker with no corner — and no platform corner to pile a heavy knee). - return [(xu, yu), *_sbend(xu + stub, yu, xv - stub, yv), (xv, yv)] + anchors: list[tuple[float, float]] = [(xu, yu), *sorted(vias), (xv, yv)] + pts: list[tuple[float, float]] = [anchors[0]] + for (xa, ya), (xb, yb) in zip(anchors, anchors[1:]): + if ya == yb: + pts.append((xb, yb)) + continue + dx = xb - xa + shift = min(dx, max(_MIN_SHIFT_DOTS, round(dx * _CURVE_SPAN))) + stub = (dx - shift) // 2 + # A bezier S across the whole gap (level tangents at both ends, so it eases out of and + # back into each anchor with no corner — and no platform corner to pile a heavy knee). + pts.extend([*_sbend(xa + stub, ya, xb - stub, yb), (xb, yb)]) + return pts def _sbend( @@ -789,6 +829,110 @@ def _layout_lanes( _fold_detour(victim, nests.pop(victim), seqs, owner, col_of) +def _bypass_vias( + seqs: Sequence[tuple[str, ...]], + bidir: set[frozenset[str]], + signed: dict[str, int], + col_of: Callable[[str], int], + max_rows: int, + lane_pitch: int, +) -> dict[frozenset[str], list[tuple[str, int]]]: + """Bend each edge that runs level through a marker it skips — where the column has room. + + The subset pair is the trigger: beside an ``A → B → C → D`` route lives the shorter + ``A → C → D``, and with ``A`` and ``C`` seated on one lane the shorter route's ``A→C`` + edge is a level run straight through ``B``'s cell — drawn, it reads as *via B*, the one + story the evidence rules out (worse still under emphasis, where the subset's highlight + repaints the spine's own run and the skipped relay looks selected). Any marker sitting + between an edge's ends on their shared lane is by construction a node that edge skips: + had the route visited it, the walk would hold ``A→B`` and ``B→C``, never ``A→C``. So each + such edge is given a *virtual waypoint* — an unmarked via point in the skipped node's own + column, on the innermost lane above or below it that is genuinely free — and the edge arcs + through the via instead: out, level for an instant over the skipped marker's shoulder, and + back — the same wider-arc grammar a nested detour draws, so a skip reads as a skip. + + Room is measured, never assumed. A lane at that column is free when no marker seats there + and no route *runs level* through it across that column (a via on such a lane would peak + tangent on that route's line and read as touching it); and a via may open a lane *outside* + the current band only while the grown band still fits ``max_rows`` at full pitch + (:func:`_band_rows`) — the same budget the detour fold answers to. The innermost free lane + wins, the no-growth side breaking a depth tie (above on a dead heat); an edge whose skipped + column truly has no room — every lane taken, growth unaffordable — keeps today's level + pass-over, the honest last resort. Edges are visited in walk order (a set of string pairs + would iterate hash-seeded and let two runs claim a contested lane differently), so the + picture is identical on every repaint. + + Returns ``{edge pair: [(skipped node, via signed lane), …]}``, vias left to right, in the + signed-lane space of ``signed``. The caller folds the via lanes into the band extent — so + the vertical sizing affords any lane a bypass opened — and seats each via at the skipped + node's exact x on that lane's row. Bidirectional pairs draw as the one honest vertical and + are never bent. + """ + if not signed: + return {} + low = min(signed.values()) + high = max(signed.values()) + centre = (low + high) / 2.0 # the endpoints' lane — integral only when a lane truly is + + def lane_of(node: str) -> float: + return centre if node in (SRC_NODE, DST_NODE) else float(signed[node]) + + cols = {node: col_of(node) for node in (*signed, SRC_NODE, DST_NODE)} + + # Every drawn edge once, in walk order; the level ones keep their lane and column span. + level: list[tuple[frozenset[str], float, int, int]] = [] + seen: set[frozenset[str]] = set() + for seq in seqs: + for u, v in zip(seq, seq[1:]): + key = frozenset((u, v)) + if key in seen or key in bidir: + continue + seen.add(key) + if lane_of(u) == lane_of(v): + c0, c1 = sorted((cols[u], cols[v])) + level.append((key, lane_of(u), c0, c1)) + + # What a via must not land on: every seated marker, and every column a level run sweeps + # on its own lane (kissing another route's straight run reads as touching it). + taken: set[tuple[int, float]] = {(cols[n], float(seat)) for n, seat in signed.items()} + taken.add((cols[SRC_NODE], centre)) + taken.add((cols[DST_NODE], centre)) + for _key, lane, c0, c1 in level: + for col in range(c0 + 1, c1): + taken.add((col, lane)) + + vias: dict[frozenset[str], list[tuple[str, int]]] = {} + for key, lane, c0, c1 in level: + skipped = sorted( + (n for n, seat in signed.items() if float(seat) == lane and c0 < cols[n] < c1), + key=lambda n: cols[n], + ) + for m in skipped: + # The innermost free lane each side of the skipped node, then the better of the + # two: shallower first, the side that keeps the band's height on a depth tie. + pick: Optional[tuple[int, int, int, int]] = None + for side, sign in ((0, -1), (1, 1)): + for depth in range(1, high - low + 3): + cand = signed[m] + sign * depth + if (cols[m], float(cand)) in taken: + continue + grows = int(cand < low or cand > high) + if grows: + n_lanes = max(high, cand) - min(low, cand) + 1 + if _band_rows(n_lanes, lane_pitch) > max_rows: + break # deeper on this side only grows further — give it up + if pick is None or (depth, grows, side) < pick[:3]: + pick = (depth, grows, side, cand) + break # the innermost free lane on this side is found + if pick is None: + continue # no room anywhere — the level pass-over stands + via_lane = pick[3] + taken.add((cols[m], float(via_lane))) + low, high = min(low, via_lane), max(high, via_lane) + vias.setdefault(key, []).append((m, via_lane)) + return vias + + def _assign_lanes( drawn: Sequence[PathLayer], seqs: Sequence[tuple[str, ...]], diff --git a/tests/test_pathgraph.py b/tests/test_pathgraph.py index 852ea0e..b2e08e9 100644 --- a/tests/test_pathgraph.py +++ b/tests/test_pathgraph.py @@ -14,6 +14,7 @@ from meshterm.ui.pathgraph import ( PathLayer, _assign_lanes, _balanced_x, + _bypass_vias, _coalesce_prefixes, _collapse, _layout_lanes, @@ -493,6 +494,113 @@ def test_edge_pinned_relay_labels_are_not_dropped() -> None: assert name in plain, f"{name} was dropped near a canvas edge" +def _vias_for(layers, width=60, max_rows=15): # noqa: ANN001 + """Run the pre-render pipeline through the bypass pass, as ``render_path_graph`` does. + + Returns ``(vias, signed)``: the bypass via map keyed by unordered edge pair — each entry + ``[(skipped node, via signed lane), …]`` — and the packed signed lane per relay, so a test + can assert a via landed relative to the seated nodes. + """ + drawn = _collapse(_coalesce_prefixes(layers)) + seqs = [(SRC_NODE, *layer.hops, DST_NODE) for layer in drawn] + ordered: list[str] = [] + seen: set[str] = set() + edges: set[tuple[str, str]] = set() + for seq in seqs: + for node in seq: + if node not in seen: + seen.add(node) + ordered.append(node) + edges.update(zip(seq, seq[1:])) + xfrac = _balanced_x(ordered, edges) + 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) + span = width * 2 - 2 * _GRAPH_PAD_DOTS + col_of = lambda node: (_GRAPH_PAD_DOTS + round(xfrac[node] * span)) >> 1 # noqa: E731 + signed = _layout_lanes( + drawn, seqs, ordered, owner, best, col_of, max_rows, _LANE_PITCH_ROWS + ) + bidir = {frozenset((u, v)) for (u, v) in edges if (v, u) in edges} + vias = _bypass_vias(seqs, bidir, signed, col_of, max_rows, _LANE_PITCH_ROWS) + return vias, signed + + +def test_subset_route_bypasses_the_relay_it_skips() -> None: + """ABCD beside ACD: the skip edge arcs around the unridden relay via a free flank lane. + + The spine runs SRC → c1 → c2 → us with a balanced flank each side, so the endpoints ride + the spine's own lane and the subset route's SRC → c2 edge is a level run straight through + ``c1``'s marker — the Furthur → YUL-Cartierville shape, where the selected route lit the + spine's run through C14903 it never rides. The edge must bend around ``c1`` through a + virtual waypoint in its column — and on the flank ``x1`` does *not* occupy, since ``x1`` + shares ``c1``'s column and its lane there is taken. + """ + layers = [ + PathLayer(("c1", "c2"), WHITE, 4), # spine: SRC -> c1 -> c2 -> us + PathLayer(("x1", "c2"), GREY, 3), # swaps c1 (x1 shares c1's column, one flank) + PathLayer(("c1", "y2"), GREY, 2), # swaps c2 (the other flank — spine stays centred) + PathLayer(("c2",), GREY, 1), # the subset: skips c1, rides c2 + ] + vias, signed = _vias_for(layers) + [(skipped, lane)] = vias[frozenset((SRC_NODE, "c2"))] + assert skipped == "c1" # the bypass shields exactly the relay the route skips + assert lane == -signed["x1"] # x1 holds its flank of c1's column — the via takes the other + + +def test_bypass_opens_a_lane_when_the_rows_afford_it() -> None: + """With no flank to borrow, the bypass opens one — the band grows and the arc rides it.""" + layers = [ + PathLayer(("aa", "bb", "cc"), WHITE, 4), # the whole graph on one straight lane + PathLayer(("aa", "cc"), GREY, 2), # the shortcut skipping bb + ] + vias, _signed = _vias_for(layers) + [(skipped, lane)] = vias[frozenset(("aa", "cc"))] + assert skipped == "bb" + assert lane == -1 # a fresh lane just off the spine — above on a dead heat + # And the render truly opens it: the endpoints leave the relays' row for the band centre. + lines = _render(layers, label_of=lambda _n: None) + (star,) = _marker_rows(lines, "★") + (relay_row,) = _marker_rows(lines, "●") # all three relays still level on the spine + assert star < relay_row # endpoints sit between the opened bypass lane and the spine + + +def test_bypass_gives_up_when_the_rows_cannot_afford_a_lane() -> None: + """No free lane and no headroom: the honest level pass-over stands — never a taller band.""" + layers = [ + PathLayer(("aa", "bb", "cc"), WHITE, 4), + PathLayer(("aa", "cc"), GREY, 2), + ] + vias, _signed = _vias_for(layers, max_rows=5) # too short for a second lane at full pitch + assert vias == {} + + +def test_route_threads_bypass_vias_level_at_each_peak() -> None: + """A bent edge leaves level, peaks level on its via, and lands level — no corners.""" + pts = _route("u", "v", {"u": (0, 9), "v": (80, 9)}, bidir=False, vias=[(40, 1)]) + assert pts[0] == (0, 9) and pts[-1] == (80, 9) # the markers still anchor the ends + assert (40, 1) in pts # the via is an anchor the edge truly passes through + near_peak = [y for x, y in pts if 36 <= x <= 44] + assert near_peak and all(y <= 2.0 for y in near_peak) # level over the skipped marker + assert pts[0][1] == pts[1][1] and pts[-1][1] == pts[-2][1] # seated level at both ends + + +def test_bypass_render_keeps_every_label() -> None: + """The arcs a bypass adds never crowd a name off the canvas.""" + names = {"c1": "C14903", "c2": "Cartier", "x1": "Poly", "y2": "Upper"} + layers = [ + PathLayer(("c1", "c2"), GREY, 4), + PathLayer(("x1", "c2"), GREY, 3), + PathLayer(("c1", "y2"), GREY, 2), + PathLayer(("c2",), WHITE, 1, emphasis=1), # the subset selected, as on the node page + ] + plain = _ANSI.sub("", "\n".join(_render(layers, label_of=lambda n: names.get(n)))) + 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 = [