feat(kicad9): snap 2-pin parts onto IC pins, post-route visual optimization

[lachlanfysh]

Summary

Post-route visual optimization for KiCad 9 schematic generation that snaps 2-pin parts (resistors, caps, LEDs) onto their connected IC pins, producing cleaner schematics with fewer floating labels.

Rebased onto development branch per review feedback on #297. Adopts the upstream hierarchical UUID path threading and 4-tuple return pattern from node_to_sexp_schematic.

Features (gen_schematic.py)

• Snap placement: Moves 2-pin parts onto connected IC/multi-pin part pins after routing succeeds
• Chain snapping: Iteratively snaps 2-pin parts onto already-snapped parts (e.g. IC ← R ← LED)
• Perpendicular stacking: Parts sharing an occupied IC pin get placed perpendicular
• T-junction staggering: Repeated patterns (e.g. input protection networks) get staggered outward from IC with connecting wires
• IC pre-shifting: When multiple ICs have stagger fans, ICs are shifted apart to prevent overlap
• Power cap offset: Decoupling caps get offset from IC power pins with explicit wire connections

Features (sexp_schematic.py)

• Label suppression: Pins physically connected by snap placement don't get redundant labels
• Power bus wires: Co-linear power net pins (3+) connected with wire segments
• No-connect flags: NCNet pins get proper no_connect markers
• Power-pin force labels: 2-pin parts with unStubbed power pins get labels when snap is active
• Overlap detection: Union-find clustering identifies overlapping pin positions

Safety

• All snap features guarded behind snap_ran detection — only activates when _snap_two_pin_parts actually modified the node
• Non-snap circuits produce identical output to upstream development
• Snap is called post-route only (never between place and route)
• 95 tests pass (63 auto_stub + 32 upstream schematic tests)

Test plan

• All 63 auto_stub tests pass (snap, power, stub, ERC)
• All 32 upstream schematic tests pass (no regressions)
• test_and_gate_erc_clean passes (0-2 fixable ERC errors)
• Non-auto_stub circuits produce identical output to upstream

🤖 Generated with Claude Code

[lachlanfysh]

Re: architecture feedback from #297 — on review the snap geometry was already backend-agnostic (operates on Point/Tx/orientation strings, no S-expression references), so I've moved it to schematics/snap.py as suggested.

The split is now:

• schematics/snap.py — snap_two_pin_parts(), T-junction staggering, IC pre-shift (pure geometry, reusable across backends)
• tools/kicad9/sexp_schematic.py — wireable-net detection, power bus wires, no-connect flags (produces KiCad S-expressions)
• tools/kicad9/gen_schematic.py — orchestration only (calls snap after route, passes node to sexp writer)

[devbisme]

Thanks for making the changes and rebasing onto the development branch. I do appreciate it! I've merged your code into a new branch called lachlanfysh-pr/kicad9-snap-v2. Please make any further changes against that branch.

[devbisme]

I'm going to close this PR. Eventually we'll merge code from your lachlanfysh-pr/kicad9-snap-v2 branch into development and then master when there's a new release.

[lachlanfysh]

Note: I'm currently debugging regressions in the v2 branch (pr/kicad9-snap-v2) that weren't present in the original #297 implementation. The deferred stubbing and rescue mechanisms I added for better wire/label balance are causing issues with label placement and broken wire connections in the generated schematics. Working to understand the root cause and get the output quality back to the #297 baseline before resubmitting.

[lachlanfysh]

Update: regressions resolved on pr/kicad9-snap-v3

Root cause identified: the sexp_schematic.py rewrite on the development branch (between #297 and #302) introduced two bugs:

1. Label orientation swap — orient_map had D↔U swapped ("D": 270, "U": 90 → should be "D": 90, "U": 270), displacing labels 17.78 units from pin endpoints
2. write_top_schematic restructure — broke UUID path threading and label positioning pipeline

Fix approach on pr/kicad9-snap-v3:

• Restored feat(kicad9): snap 2-pin parts onto IC pins, power bus wires, label deconfliction #297's working sexp_schematic.py output pipeline (correct orientations, label positioning)
• Cherry-picked the UUID path threading fix from development (needed for hierarchical sheet references)
• Added deferred stubbing for connectivity-aware placement (high-fanout nets stay connected during placement, then get stubbed as labels)
• Added child-node net classification — only large chain structures (switch→R→IC grids, LED→driver chains) get router wires; smaller subcircuits use clean labels at pins

Output now exactly matches #297 quality across all 14 hierarchical sheets (verified wire/label counts per sheet). 63 tests pass.

Branch: pr/kicad9-snap-v3 — ready for review when convenient.

[devbisme]

Which of my branches should I merge pr/kicad9-snap-v3 into?
master, development or lachlanfysh-pr/kicad9-snap-v2?

[lachlanfysh]

`lachlanfysh-pr/kicad9-snap-v2` would be cleanest — v3 is based on `development` (same ancestor as v2) so it should merge without conflicts, and it supersedes everything on v2.

v3 is 2 commits on `development`:

1. Snap placement + label suppression + UUID paths — the core feature from feat(kicad9): snap 2-pin parts onto IC pins, power bus wires, label deconfliction #297, fixed for the label orientation issue on `development`
2. Deferred stubbing + chain-aware classification — additive improvement for smarter wire/label decisions (can be dropped independently if you'd prefer to review it separately)

Both are self-contained against `development`, so merging into `development` directly would also work if you'd prefer to skip the intermediate branch.

[devbisme]

I've merged your v3 into development and created a new branch called lachlanfysh. I'll test it soon.

[devbisme]

I'm trying the lachlanfysh branch with your v3 changes on the following design:

from skidl import *

def test_interface_12():
    """Test nested subcircuits with fixed nets."""
    r = Part("Device", "R", dest=TEMPLATE)
    c = Part("Device", "C", dest=TEMPLATE)

    @subcircuit
    def sub1():
        # Create nets
        my_vin, my_gnd = Net(), Net()
        # Create resistor and capacitor
        r1 = r(tag="r1")
        c1 = c(tag="c1")
        # Connect resistor and capacitor between input and ground
        my_vin & r1 & c1 & my_gnd
        return Interface(my_vin=my_vin, my_gnd=my_gnd)

    @subcircuit
    def sub2(my_vin1, my_vin2, my_gnd):
        # Instantiate subcircuits
        s1 = sub1(tag="s1")
        s2 = sub1(tag="s2")
        # Connect the subcircuits to the nets
        s1.my_vin += my_vin1
        my_vin2 += s2.my_vin
        my_gnd += s1.my_gnd
        s2.my_gnd += my_gnd

    # Create nets
    vin1, vin2, gnd, vdd = Net("VIN1"), Net("VIN2", stub=True), Net("GND"), Net("VDD")
    # Instantiate the subcircuit
    sub = sub2(vin1, vin2, gnd, tag="sub")
    # Create resistor and connect between input and ground
    r1 = r()
    vdd & r1 & gnd

    # Assertions to verify the circuit
    assert len(gnd) == 3
    assert len(vin1) == 1
    assert len(vin2) == 1
    assert len(vdd) == 1

    hierarchy = default_circuit.active_node.to_tuple()
    hierarchy2 = default_circuit.active_node.to_tuple()
    assert str(hierarchy) == str(hierarchy2)
    print(str(default_circuit.active_node))
    generate_schematic(title="My Title", flatness=1)

test_interface_12()

The flattened schematic for this hierarchical design looks like this in EESCHEMA:

For comparison, this is the schematic generated by the current development branch:

Then I tried with this SKiDL code that tests part transformations with stub nets:

from skidl import *

# Create nets.
e, b, c = Net("ENET"), Net("BNET"), Net("CNET")
b.netio = "i"
e.stub, b.stub, c.stub = True, True, True

# Create part templates.
qt = Part(lib="Transistor_BJT", name="Q_PNP_CBE", dest=TEMPLATE)

# Instantiate parts having various rotations & mirroring.
# for q, tx in zip(qt(1), ["",]):
for q, tx in zip(qt(8), ["", "H", "V", "R", "L", "VL", "HR", "LV"]):
    q["E B C"] += e, b, c
    q.ref = "Q_" + tx
    q.symtx = tx

generate_schematic(filepath=".", flatness=1.0)

For the lachlanfysh branch I got:

And for the development branch the result was:

I also tested the esp32_audio_board design. The following portion of the schematic is from the lachlanfysh branch:

And this is from the development branch:

My assessment of these two branches is:

• The development branch has problems with net label orientations (on all examples) and missing/unknown components (on the esp32 example).
• The lachlanfysh branch has problems with net label orientation and stub label orientation (except on the esp32 example) and with leaving wire remnants after net stubs are applied. It also wires over a VBUS power symbol when connecting a bypass cap to the VBUS pin.
• The v3 PR when applied to the development branch to create lachlanfysh branch reverts most of the refactoring done to the sexp_schematic.py file.

At this point, here is what I'd like to see:

• Minimal changes to the refactored sexp_schematic.py already in the development branch. (I will need to fix the problems there with net labels and missing/unknown components.)
• Inclusion of your feature changes somewhere in the src/skidl/schematics directory where they can apply to all backends. (You mentioned that some of this was moved to the src/skidl/schematics/snap.py file, but I don't see that in the lachlanfysh branch.) If you really need to change wiring or component positions in the schematic at the sexp_schematic.py stage, please tell me why so maybe we can find a workaround.

I appreciate the work you've put in so far. I just want to move some of these features too a different part of the flow where they might make more sense and cut down on replicated code.

[lachlanfysh]

Hi Dave — first, an apology for the revert: I needed those lines somewhere, but dropping them in at that point in your flow was pigheaded and ran over your sequencing. I lean on AI for a lot of the coding; architecture is more my wheelhouse, and I should have respected your design intent there.

So I went back and did it properly. I wrote up the design — the snap work as tool-agnostic decisions behind a thin backend interface — and implemented it on a local branch: the snap feature now sits on top of your refactor rather than replacing it, verified on your esp32_audio_board example and on a larger board of my own. I've held off PRing until you've had a chance to weigh in on the direction: ARCHITECTURE-snap-backend-split.md.

The open problem is placement. The downstream routines paper over it — deconfliction nudges labels off bodies, a label-aware orientation pass rotates parts so their labels splay — but that's symptom treatment; the root is that the placer reserves space for part bodies + routing channels but not for net labels, so on denser boards labels collide. I've been chasing the root fix and want to flag the dead-ends so you don't spend time on them:

• Net-label facing is a false trail. The orient_map is correct in all four pin orientations — the tempting "swap U/D" just moves the breakage, since the map already compensates for the sheet Y-flip. (Committing a four-orientation render fixture to pin that down.)

  Correction — I had this backwards. Net-label facing was a real bug. I built that four-orientation render fixture and rotated + mirrored it: the vertical orient_map values currently on development make up/down-pin labels point into the body. The correct values are "D": 90, "U": 270 — the same ones I'd flagged earlier in this thread before talking myself out of them. It hid because deconflict_labels was nudging those inward labels off the body (which is itself the step-out), so tightening that nudge exposes the overprint. Fix: derive (angle, justify) per calc_pin_dir so the label always extends away from the pin (mirror included), plus a render-free regression test that asserts the away-invariant (it fails on the swapped values, passes on the fix). Happy to send that as a small isolated PR against development.

• Two-pass clearance: calc_hier_label_bbox already folds into lbl_bbox, but only for pins stubbed at preprocess time — and _classify_and_stub_complex_nets stubs by distance after placement, so those labels never get reserved space. I tried place → freeze the full stub set → re-preprocess so the new stub labels fold in → rebuild the node → re-place. The mechanism works (lbl_bbox grows) but the label-overlap metric didn't move. It's not attraction pulling stubbed parts together — fully-stubbed nets are already out of placement tension (get_internal_nets skips them). The real signal: the worst stacking is labels on a single IC's own pins, which is fixed pitch on the symbol — intra-part, so part spacing can't touch it.

• Next I'm looking at an intra-IC label fan-out, separate from placement. If you have a view on where that belongs — placement, backend emit, or a decisions layer — I'd take it.

Two small isolated things I also hit:

• _power_symbol_to_sexp hardcodes angle=0, so GND symbols on upward-facing pins render mis-oriented (net labels rotate via calc_pin_dir; power symbols don't).
• Wire emission skips only on net._stub while sibling paths also check net.stub, so a manually-stubbed multi-pin net still routes a bus and labels it.

I can send isolated PRs for those two, and for any of the snap/architecture work that's useful once you've had a look.

[devbisme]

Thanks for the detailed write-up. I think I need a little less detail and a little more high-level understanding. To wit: are net labels the cause of all this? In other words, if there were no net labels to deal with, would you be able to do your other optimizations (such as two-pin snapping) within the src/skidl/schematics code without overlaps and alignment issues? If so, then we need to handle net labels correctly in the src/skidl/schematics code. (Actually, I thought I
was already doing that since there weren't any obvious problems when I built that code, but maybe I was being too simple back then.)

[lachlanfysh]

Good timing — I was just prepping the message below when your question came through.

Mostly yes — and it maps onto the refactor. The label and wire decisions are now tool-agnostic in schematics/decisions.py, the snap geometry in schematics/snap.py, so the two-pin snapping places cleanly with no overlaps. The one piece that stays backend-side is the label's angle and justify — that's how KiCad justifies the text in the s-expr, not a placement call — and that's where the worst of it came from: the vertical labels' justify was pushing them back over their own body. Fixed in the kicad9 emit. It's done and running on your own two test cases:

Your 8-transistor rotation/mirror test:

Labels face away from the body in every rotation and mirror, sit on their pins, no stray cross-sheet wires.

esp32_audio_board (MCU region):

U3 renders fully, the decoupling caps fan to VCC, and the EN pull-up and reset cap tee off the EN pin cleanly.

The small fixes are below, one per commit. The bigger structural change — pulling the snap/label/wire work out of the backend into tool-agnostic decisions in schematics/, behind a thin interface — is laid out in the architecture doc I linked last time: ARCHITECTURE-snap-backend-split.md. That's the part I'd most want your read on before I open anything.

I've held off opening any PRs so you can get your head around it at your own pace — but it's all ready as isolated commits against development, so just say the word and how you'd like them grouped.

---

Each fix is its own commit, if it helps to see them mapped to what you flagged:

Finding	Fix
net-label orientation (both branches) — D/U swapped in orient_map (4bd527dc flipped the test-correct b3728d27 values)	d9c9b55b (derive (angle, justify) from one table keyed on calc_pin_dir) + regression test 41c5649a
stub-net labels dragged off their pins with long connecting wires	7d90ec58 — deconflict_labels was wire-relocating stub labels off a neighbour's body; since a stub net is connected by name, skip it in deconfliction (builds on your 2c7935b1 own-body guard)
missing/unknown components (esp32)	33afc28d (emit power-symbol defs from emitted instances)
wire remnants after stubs	67545e2a (dangling-wire purge)
wires over the VBUS power symbol	82e64115 (drop power-bus segments crossing a part body)
power-symbol angle=0	e080dd73 (shared angle table)

Two additive placement bits beyond your findings:

Feature	Commit
single-pin fan teeing — a pull-up + RC cap on one IC pin tee off cleanly instead of the cap landing on the body (shown in the esp32 render, the EN pin)	846d8999 (one IC pin with ≥2 two-pin parts now staggers; any pin, not just EN)
spacing independent groups apart on dense sheets — opt-in (not used in either render above)	5cbc486e (grid_blocks=True, size-aware shelf-pack; default off)

On grid_blocks — that overlaps the inter-group placement @rhaingenix is working in #306. I flagged the idea over there; what I landed on is a good deal simpler — it leans on SKiDL's existing place_blocks rather than their primitives — but credit to #306 for working the same ground. Happy to converge the two rather than ship competing versions — whichever shape you'd rather have in SKiDL.

[devbisme]

At this point, I think it's more efficient for you to issue a PR of your stuff against the development branch. It's probably quicker and easier for me to look at what you changed than to interpret a description of what you changed. I can also run your code and see the pretty schematics it creates (which is an incentive). Please check in any local examples you've used for testing so I can try them too.

As for dual visions of schematic generation enhancements, I hope you can come to an arrangement with @rhaingenix that gives us a PR with the best of both.

As always, I appreciate your efforts. There wouldn't be any schematic generation for KiCad 9 (or 6, 7, 8) without you.

[lachlanfysh]

Thanks Dave - I'm enjoying working through the problems and I've got a lot more ideas for PCBs I want to build than I do time to sit in Kicad hand doing them so effort here that gives me better throughput is selfishly very helpful, but glad to do so in a way that also helps others.

I was thinking the conceptual PRs were layering up a bit thick - I will do a clean up, most likely closing this PR and starting afresh with one or more.

Further on the topic of throughput of boards - in the last couple of days I've been playing out with some code to get to a decent starter on the layout stage of the actual PCB - It's always maddening to me when Kicad first just drops every part in the corner of the board sorted by component type and you need to unpick it (which decoupling cap goes with which IC?? which power pin did I want that one on?). I I've got quite a nice v1 going there to get initial layout to respect schematic structure also which I will share via PR - will value your architectural feedback there on how you'd like to see extensions of Skidl like that fit in.

[devbisme]

Here is one tool I built to quickly make a PCB from a netlist where the parts are arranged into nested groups by hierarchy. But it doesn't do anything to place parts to reduce the lengths of airwires.

[devbisme]

OK, I'm closing this again since we have all the other schematics generation PRs integrated into the development branch.