KiCadRoutingTools

# PCB Modification & Geometry API (`pcb_modification`, `geometry_utils`)

- **`pcb_modification.py`** — keeps the in-memory `PCBData` model in sync
  with routing: add a routed result (with cleanup), remove a net (for rip-up),
  swap pad nets. If you add copper here, every subsequent routing/obstacle
  call sees it.
- **`geometry_utils.py`** — the shared 2-D geometry primitives: distances,
  intersections, closest points, path simplification, and a `UnionFind`.

All coordinates are mm.

## `pcb_modification.py`

### `add_route_to_pcb_data`

```python
add_route_to_pcb_data(pcb_data: PCBData, result: dict,
                      debug_lines: bool = False) -> None
```

Appends a routed result's copper to `pcb_data.segments` / `pcb_data.vias`,
**after cleaning it**. `result` is a dict with `'new_segments'` (list of
`Segment`) and `'new_vias'` (list of `Via`). Mutates `pcb_data` in place and
also replaces `result['new_segments']` with the cleaned list, so the same
result dict can go straight to the writer.

Cleanup pipeline (per net):

1. **Self-intersection fixing** — short connector segments that cross the
   net's existing copper are trimmed to the crossing point; orphaned
   downstream pieces are removed.
2. **Appendix collapsing** — short dead-end segments left by grid snapping
   are collapsed to micro-stubs at their junction.
3. **Degenerate segment removal** — segments under 0.01 mm are dropped;
   micro-bridges between two chains are welded shut (neighbors moved to the
   midpoint) so no gap opens.

Call this after each successful route and before routing the next net, so
incremental obstacle maps stay truthful.

### `remove_route_from_pcb_data`

```python
remove_route_from_pcb_data(pcb_data: PCBData, result: dict) -> None
```

Inverse of `add_route_to_pcb_data` for rip-up: removes exactly the segments
and vias recorded in `result` (matched by normalized endpoints rounded to
`POSITION_DECIMALS`, direction-agnostic).

### `remove_net_from_pcb_data` / `restore_net_to_pcb_data`

```python
remove_net_from_pcb_data(pcb_data, net_id: int)
    -> Tuple[List[Segment], List[Via]]
restore_net_to_pcb_data(pcb_data, segments, vias) -> None
```

Blunter tools: strip **all** copper of a net (returning it so you can
restore on failure), and put it back.

```python
from kicad_parser import parse_kicad_pcb
from pcb_modification import remove_net_from_pcb_data, restore_net_to_pcb_data

pcb = parse_kicad_pcb('kicad_files/routed_output.kicad_pcb')
net = next(n for n in pcb.nets.values() if 'lvds' in n.name and len(n.pads) >= 2)

before = len(pcb.segments)
segs, vias = remove_net_from_pcb_data(pcb, net.net_id)
print(f"removed {len(segs)} segments, {len(vias)} vias of {net.name}")

restore_net_to_pcb_data(pcb, segs, vias)
assert len(pcb.segments) == before
```

### `swap_pad_nets_in_pcb_data`

```python
swap_pad_nets_in_pcb_data(pcb_data: PCBData, pad_a: Pad, pad_b: Pad) -> None
```

Swaps two pads' net assignments in the in-memory model (`net_id`,
`net_name`, `pads_by_net`, `Net.pads`). The file-level counterpart is
[`kicad_writer.swap_pad_nets_in_content`](api-kicad-writer.md#swap_pad_nets_in_content);
the routing pipeline applies both so the model and the output file agree.

### Cleanup helpers (advanced)

> **Removed:** `collapse_appendices` and `fix_self_intersections` were deleted
> (issue #159). `fix_self_intersections` resolved a same-net self-crossing by
> *extending* a segment to a far off-grid endpoint, which created long
> non-orthonormal diagonals that crossed foreign copper. `collapse_appendices`
> was already a vestigial wrapper (its short-appendix trim was removed in #148,
> redundant with `sweep_dead_ends`). `add_route_to_pcb_data` now commits routed
> segments directly; connectivity cleanup is handled by `prune_redundant_cycles`
> and the whole-net dead-end trim `sweep_dead_ends` (#84). The residual same-net
> self-crossings are tracked in #162.

> **#1063 -- one removability predicate.** `collapse_strict_redundant(results,
> pcb_data, scope_net_ids, keep_input_copper=False, protect_segment_ids=None,
> stats=None)` deletes the copper `StrictRemovalModel` accepts, and
> `check_weird`'s `removable-segment` reports exactly what that model accepts,
> so the checker never calls copper removable that the cleanup keeps. The model
> grades a removal of segments (a single one, or an unbranched run) plus the
> vias it leaves joining nothing: every pad stays connected on the strict
> graph (track widths clamped; a via joins a pad only by its centre,
> `check_net_connectivity(..., via_in_pad_margin=...)`; on a layer a pad's
> unconnected-layer mode removes, only its hole joins,
> `check_net_connectivity(..., unflashed_hole_only=True)`) and on the physical
> graph, no copper island, dangling end or soft joint appears, and no via the
> pass may not drop -- anything but this run's own, unlocked vias -- is left
> dangling. In-pad / in-via wiggles (both ends in same-net pad or via copper),
> which #217 kept, are removed. A redundant loop through vias loses its via
> branch first. `run_post_route_cleanup(strict_collapse=True)` runs the
> collapse twice: after the cycle prune, and again after `close_soft_joints` on
> the nets smoothing or bridging changed, never removing the soft-joint bridges
> and web connectors close lays. **route.py passes `strict_collapse=False`**
> and collapses ONCE at the end of the outermost run
> (`route._late_strict_collapse1063`), after the plane finalize, the oracle
> legs and the reconciliation, on the board it ships (the written file on the
> CLI, the write model on the GUI); the finalize's in-process plane cleanups
> skip it too (`cleanup_pipeline.defer_strict_collapse`). Collapsing before
> those passes steered their rip/reroute (cparti_fpga: 6 open nets -> 15 from
> one input). Nets over `STRICT_REMOVAL_MAX_SEGS` (500)
> segments are skipped by both. `check_connected.analyze_conn_excluding` takes
> `excluded_via_indices` for this and now returns the `num_copper_components`
> it always computed.

> **#672 -- sub-cell slivers.** `sweep_dead_ends(..., sliver_eps=mm)` is the one
> exception to its `protect_net_ids` exemption (nets with unfinished pads keep
> every landing site, #473): a protected net still loses a dead-end piece
> SHORTER than `sliver_eps` when `check_net_connectivity` grades the net no
> worse without it. The cleanup pipeline passes one routing cell
> (`config.grid_step`) -- but **only under `KICAD_SLIVER_TRIM=1`; the default
> is 0.0, i.e. off**. The epsilon's rationale is sound (no A* span is shorter,
> so such a piece can only be rip/restore/prune debris, and a stub shorter
> than a cell offers no landing its root does not) and the motive is real
> (a 0.02 mm sliver of a net retried across an iteration ladder shipped
> 0.054 mm from a foreign track) -- but taking copper off a net the ladder is
> still retrying MEASURED AS A LOST NET: on orangecrab's recorded route step,
> paired from the same input board, `RAM_UDQS+` went from routed to
> `failed_single` (run verdict 9 -> 10, 14 DRC either way), while the
> self-pair half of this change alone reproduced the base copper EXACTLY
> (6097 segments and 625 vias compared, all identical). **The corpus A/B ran
> (2026-09-04, sets 1-5, 72 boards paired at one commit) and it does not pay:
> real DRC 21 vs 21 unchanged, unconnected nets 86 -> 87, one board worse
> (`core1106_cam` 0 -> 1) and none better.** It stays off. The same change
> teaches every soft-joint detector (`_soft_joint_pairs`, `close_soft_joints`,
> `check_drc`, `check_weird`) that the two ends of ONE segment are not a joint:
> a lone sub-cap sliver used to pair with itself, which made
> `_restore_soft_joint_bridges` put a just-removed dead neighbour back.

## `geometry_utils.py`

Pure functions; no PCB context needed.

### Distances and closest points

```python
point_to_segment_distance(px, py, x1, y1, x2, y2) -> float
point_to_segment_distance_seg(px, py, seg: Segment) -> float
closest_point_on_segment(px, py, x1, y1, x2, y2) -> Tuple[float, float]
segment_to_segment_distance(x1, y1, x2, y2, x3, y3, x4, y4) -> float
segment_to_segment_distance_seg(seg1, seg2) -> float
segment_to_segment_closest_points(seg1, seg2)
    -> Tuple[float, Tuple[float, float], Tuple[float, float]]
    # (distance, point_on_seg1, point_on_seg2)
```

Degenerate (zero-length) segments are handled; intersecting segments have
distance 0.

### Intersection tests

```python
segments_intersect(x1, y1, x2, y2, x3, y3, x4, y4) -> bool   # strict crossing
segments_intersect_tuple(p1, p2, p3, p4) -> bool             # tuple endpoints
segments_intersect_2d(s1_start, s1_end, s2_start, s2_end,
                      tolerance=0.001) -> bool   # also catches collinear overlap
```

`segments_intersect` detects proper interior crossings only (shared
endpoints don't count); `segments_intersect_2d` additionally reports
endpoint touches and collinear overlaps within `tolerance`.

### `UnionFind`

```python
from geometry_utils import UnionFind

uf = UnionFind()
uf.union('a', 'b')        # merge the sets containing 'a' and 'b'
uf.find('a')              # canonical representative (auto-creates singletons)
uf.connected('a', 'b')    # same set? -> True
```

Disjoint-set with path compression and union by rank; keys are any hashable
values. This is what connectivity grouping is built on.

### Other helpers

```python
simplify_path(path: List[Tuple[int, int, str]]) -> List[...]
```

Removes collinear intermediate points from an A* path. Note: operates on
**grid** coordinates `(gx, gy, layer)`, not mm.

### Example

```python
from geometry_utils import (point_to_segment_distance, closest_point_on_segment,
                            segments_intersect, UnionFind)

# How far is the point (5, 5) from the track (0,0)-(10,0)?
print(point_to_segment_distance(5, 5, 0, 0, 10, 0))     # 5.0
print(closest_point_on_segment(5, 5, 0, 0, 10, 0))      # (5.0, 0.0)

# Do two tracks cross?
print(segments_intersect(0, 0, 10, 10, 0, 10, 10, 0))   # True
print(segments_intersect(0, 0, 10, 0, 0, 1, 10, 1))     # False (parallel)

# Group endpoints into connected nets
uf = UnionFind()
uf.union('A', 'B'); uf.union('B', 'C'); uf.union('X', 'Y')
print(uf.connected('A', 'C'), uf.connected('A', 'X'))   # True False
```

## Gotchas

- **`add_route_to_pcb_data` is mandatory in routing loops** — skipping it
  means later nets route through copper they can't see, and the writer gets
  uncleaned geometry.
- **Per-net cleanup**: the dead-end / cycle cleanup helpers (`prune_redundant_cycles`,
  `sweep_dead_ends`) operate on **one net at a time** — never feed segments from
  multiple nets into one call.
- **`remove_route_from_pcb_data` must see the same coordinates it added** —
  if you transform geometry in between, use `remove_net_from_pcb_data`
  instead.
- **`simplify_path` is grid-space**; everything else in `geometry_utils` is
  mm.