enginehall 2.0.0__py3-none-any.whl

pcba/parsers/altium/_sheet.py

@@ -0,0 +1,293 @@
+"""The sheet resolver shared by the pin-map and netlist extractors.
+
+Both extractors must agree on the format traps from `records.py`: the designator child
+record, the multi-part filter, the pin's electrical end, and point-to-segment wire contact.
+They must also agree on what joins and names a net: net labels, power ports, ports and
+junctions, and which name wins when a net carries several. All of it lives here once, in
+`resolve`, so `enginehall altium netlist` and the pin map the rules trust cannot name the same
+pin's net differently.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Hashable, Iterable
+from pathlib import Path
+
+from pcba.parsers.altium.geometry import Point, PointIndex, UnionFind, key
+from pcba.parsers.altium.records import (
+    PIN_DIRECTION,
+    REC_COMPONENT,
+    REC_DESIGNATOR,
+    REC_JUNCTION,
+    REC_NET_LABEL,
+    REC_PIN,
+    REC_PORT,
+    REC_POWER_PORT,
+    REC_WIRE,
+    SchDocError,
+    coord,
+    text_of,
+)
+
+# Naming precedence when one net carries several names; lower wins. A rail's identity is not
+# up for debate, so a power port beats a net label, and a port names a net only when nothing
+# else on it does.
+RANK_POWER_PORT, RANK_NET_LABEL, RANK_PORT = 0, 1, 2
+
+# Port `Style` 4-7 (None, Top, Bottom, Top & Bottom) run vertically; 0-3 horizontally.
+_VERTICAL_PORT_STYLES = frozenset(range(4, 8))
+
+Key = tuple[float, float]  # a quantized point, as `geometry.key` returns it
+
+
+def components(records: list[dict[str, str]]) -> dict[int, dict[str, str]]:
+    """Component records keyed by their index in the record stream."""
+    return {i: f for i, f in enumerate(records) if f.get("RECORD") == REC_COMPONENT}
+
+
+def designators(records: list[dict[str, str]]) -> dict[int, str]:
+    """Component index -> designator. "U1" lives in a child record; see records.py."""
+    out: dict[int, str] = {}
+    for fields in records:
+        if fields.get("RECORD") == REC_DESIGNATOR and "OwnerIndex" in fields:
+            out.setdefault(int(fields["OwnerIndex"]) + 1, text_of(fields))
+    return out
+
+
+def _part_id(fields: dict[str, str], name: str) -> int:
+    """A part number as an integer; 0 when the field is absent or blank.
+
+    Compared as integers, not strings: `" 1"` is part 1. `validate_fields` has already
+    refused anything but a blank-padded plain integer, as the TypeScript decoder does.
+    """
+    value = fields.get(name, "").strip(" \t")
+    return int(value) if value else 0
+
+
+def placed_pins(
+    records: list[dict[str, str]],
+    comps: dict[int, dict[str, str]],
+    names: dict[int, str],
+) -> list[dict]:
+    """Every pin actually placed on the sheet, with its electrical (hot) end.
+
+    Keys: `ci` (component index), `num` (pad designator), `name`, `hot`, `lib`, `designator`.
+    """
+    pins = []
+    for fields in records:
+        if fields.get("RECORD") != REC_PIN or "OwnerIndex" not in fields:
+            continue
+        # OwnerIndex is 0-based over the records; the component index is OwnerIndex + 1.
+        ci = int(fields["OwnerIndex"]) + 1
+        if ci not in comps:
+            continue
+        # The instance places part `CurrentPartId`; a pin of another part shares its
+        # coordinates but is not on this sheet. Part 0, a negative id, or none at all is
+        # Altium's part zero: shared by every part, so always placed. An instance without a
+        # positive CurrentPartId places every pin. The extension's parser agrees; both run
+        # fixtures/conformance/schdoc-placed-pins.json.
+        current = _part_id(comps[ci], "CurrentPartId")
+        owner = _part_id(fields, "OwnerPartId")
+        if current > 0 and owner > 0 and owner != current:
+            continue  # a different part of this multi-part symbol; not placed here
+        x, y = coord(fields, "Location.X"), coord(fields, "Location.Y")
+        length = int(fields.get("PinLength", 0) or 0)
+        dx, dy = PIN_DIRECTION[int(fields.get("PinConglomerate", 0) or 0) & 3]
+        pins.append(
+            {
+                "ci": ci,
+                # A pad designator, kept as text: BGA parts use "A1", "B12", and an int()
+                # here took the whole review down on the first BGA schematic it met.
+                "num": fields.get("Designator", "").strip(),
+                "name": fields.get("Name", ""),
+                # The electrical end, not the body-attach end.
+                "hot": (x + dx * length, y + dy * length),
+                "lib": comps[ci].get("LibReference", ""),
+                "designator": names.get(ci, ""),
+            }
+        )
+    return pins
+
+
+def wire_segments(records: list[dict[str, str]]) -> list[tuple[Point, Point]]:
+    """Every wire (RECORD=27) as consecutive vertex pairs."""
+    wires = []
+    for fields in records:
+        if fields.get("RECORD") != REC_WIRE:
+            continue
+        n = int(fields.get("LocationCount", "0") or 0)
+        verts = [(coord(fields, f"X{k}"), coord(fields, f"Y{k}")) for k in range(1, n + 1)]
+        wires += list(zip(verts, verts[1:]))
+    return wires
+
+
+def connect(
+    wires: list[tuple[Point, Point]], points: set[tuple[float, float]]
+) -> tuple[UnionFind, set[tuple[float, float]]]:
+    """Union every wire with the (quantized) points that touch it, point-to-segment.
+
+    Returns the union-find and the set of points that lie on some wire.
+    """
+    uf = UnionFind()
+    index = PointIndex(points)
+    wire_contacts: set[tuple[float, float]] = set()
+    for a, b in wires:
+        ka = key(a)
+        uf.union(ka, key(b))
+        for q in index.near_segment(a, b):
+            uf.union(q, ka)
+            wire_contacts.add(q)
+    return uf, wire_contacts
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Anchors:
+    """Everything on a sheet, besides wires and pins, that joins or names a net."""
+
+    names: list[tuple[Point, str, int]]  # (anchor, text, rank); the text may be blank
+    junctions: list[Point]
+    ports: list[tuple[Point, Point]]  # one object, two hotspots
+
+
+def _location(fields: dict[str, str]) -> Point:
+    return (coord(fields, "Location.X"), coord(fields, "Location.Y"))
+
+
+def anchors(records: list[dict[str, str]]) -> Anchors:
+    """Net labels, power ports, ports and junctions, with each name's rank.
+
+    A port touches at both ends: `Location`, and `Width` further along +X for the horizontal
+    styles 0-3 or along +Y for the vertical styles 4-7. Its name is anchored at `Location`;
+    the two ends are joined by `resolve`. Raises ValueError on a port `Width` or `Style` that
+    is not an integer: `validate_fields` does not cover them.
+    """
+    names: list[tuple[Point, str, int]] = []
+    junctions: list[Point] = []
+    ports: list[tuple[Point, Point]] = []
+    for fields in records:
+        kind = fields.get("RECORD")
+        if kind == REC_JUNCTION:
+            junctions.append(_location(fields))
+        elif kind in (REC_NET_LABEL, REC_POWER_PORT):
+            rank = RANK_POWER_PORT if kind == REC_POWER_PORT else RANK_NET_LABEL
+            names.append((_location(fields), text_of(fields), rank))
+        elif kind == REC_PORT:
+            a = _location(fields)
+            width = coord(fields, "Width")
+            if int(fields.get("Style", 0) or 0) in _VERTICAL_PORT_STYLES:
+                b = (a[0], a[1] + width)
+            else:
+                b = (a[0] + width, a[1])
+            name = (fields.get("%UTF8%Name") or fields.get("Name", "")).strip()
+            names.append((a, name, RANK_PORT))
+            ports.append((a, b))
+    return Anchors(names, junctions, ports)
+
+
+def precedence(name: str, rank: int) -> tuple[int, str]:
+    """Sort key for the names on one net: the lowest rank, then the smallest text, wins.
+
+    Text, not record order, breaks a tie, so the answer does not depend on which label was
+    drawn first. Two names on one net are a conflict either way; the netlist lists them.
+    """
+    return (rank, name)
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Sheet:
+    """One sheet resolved: its placed pins, the clusters its geometry forms, the names on them."""
+
+    components: dict[int, dict[str, str]]
+    designators: dict[int, str]
+    pins: list[dict]  # `placed_pins`
+    uf: UnionFind
+    wire_contacts: set[Key]  # points that lie on some wire
+    names: list[tuple[Key, str, int]]  # (cluster root, text, rank); blank names dropped
+
+    def root(self, point: Point) -> Key:
+        """The cluster a point belongs to."""
+        return self.uf.find(key(point))
+
+    def named(self) -> dict[Key, str]:
+        """Cluster root -> the name that wins on its net, for every named cluster on this sheet.
+
+        Clusters carrying the same identifier type and name are one net, so each takes
+        the winner over that net's names: a pin wired only to port `P` is on `SIGNAL` when
+        another port `P` on the sheet also carries that label.
+        """
+        nets = join_by_name(self.names)
+        winners = {net: nets.winner(net) for net in nets.carried()}
+        return {root: winners[nets.uf.find(root)] for root, _, _ in self.names}
+
+
+def chosen(names: Iterable[tuple[str, int]]) -> str:
+    """The winning name among `(text, rank)` pairs on one net; see `precedence`."""
+    return min(names, key=lambda item: precedence(*item))[0]
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Nets:
+    """Clusters joined by matching identifier types and names."""
+
+    uf: UnionFind  # over the callers' cluster keys and ("name", rank, text)
+    rank_of: dict[Hashable, dict[str, int]]  # each net's own names and best ranks
+
+    def carried(self) -> dict[Hashable, set[str]]:
+        """Net (its union-find root) -> every name on it."""
+        return {root: set(names) for root, names in self.rank_of.items()}
+
+    def winner(self, root: Hashable) -> str:
+        """The name that wins among names on one net."""
+        return chosen(self.rank_of[self.uf.find(root)].items())
+
+
+def join_by_name(named: Iterable[tuple[Hashable, str, int]]) -> Nets:
+    """Join clusters sharing the same identifier type and text, never text alone.
+
+    The pin map joins the clusters of one sheet; the netlist joins those of every sheet,
+    keyed `("sheet", index, root)`. Rank also identifies the anchor type (power, label,
+    port). Different types meet only through a shared geometric cluster. A cluster key
+    must not look like `("name", rank, text)`.
+    """
+    uf = UnionFind()
+    identifiers: set[tuple[str, int]] = set()
+    for cluster, name, rank in named:
+        uf.union(cluster, ("name", rank, name))
+        identifiers.add((name, rank))
+    rank_of: dict[Hashable, dict[str, int]] = {}
+    for name, rank in identifiers:
+        names = rank_of.setdefault(uf.find(("name", rank, name)), {})
+        names[name] = min(rank, names.get(name, rank))
+    return Nets(uf, rank_of)
+
+
+def resolve(path: Path | str, records: list[dict[str, str]]) -> Sheet:
+    """Resolve one sheet's connectivity: the one resolver both extractors use.
+
+    Wires join point-to-segment; a junction joins every wire passing through it, so two
+    crossing wires connect only where a junction sits; a port joins its two ends; pins whose
+    electrical ends coincide join without a wire. Every pin takes part in the geometry, even
+    one that cannot be a node: an end lying on two crossing wires still joins them.
+    """
+    comps = components(records)
+    names = designators(records)
+    pins = placed_pins(records, comps, names)
+    wires = wire_segments(records)
+    try:
+        found = anchors(records)
+    except ValueError as exc:
+        raise SchDocError(f"{path}: invalid field value ({exc})") from exc
+
+    # One flat point set: wire vertices, pin hot ends, anchors, junctions and port ends.
+    points = {key(v) for seg in wires for v in seg}
+    points |= {key(p["hot"]) for p in pins}
+    points |= {key(at) for at, _, _ in found.names}
+    points |= {key(j) for j in found.junctions}
+    points |= {key(v) for port in found.ports for v in port}
+    uf, wire_contacts = connect(wires, points)
+    for a, b in found.ports:
+        uf.union(key(a), key(b))
+
+    named = [(uf.find(key(at)), text, rank) for at, text, rank in found.names if text]
+    return Sheet(comps, names, pins, uf, wire_contacts, named)

pcba/parsers/altium/geometry.py

@@ -0,0 +1,103 @@
+"""Connectivity primitives for schematic geometry.
+
+Why geometric rather than text
+------------------------------
+A design that encodes the pin in the net label ("PA5_SPI1_SCK") invites a text scan. On a
+real 176-pin draft, four labels did not match the pin they attach to — so a text scan
+silently produces a wrong map, and produces it *confidently*. Connectivity is resolved from
+geometry; the label supplies only the name. The mislabel rule then reports the disagreement
+instead of hiding it.
+
+The subtle part is that connectivity is point-to-**segment**, not point-to-point. A net-label
+anchor normally lies in the INTERIOR of a wire segment, not on a vertex, so comparing labels
+against vertices needs a fudge radius — and a radius large enough to work will grab a
+neighbouring row.
+"""
+
+from __future__ import annotations
+
+import collections
+import math
+from collections.abc import Iterable
+
+Point = tuple[float, float]
+
+# Coordinates are integers on a 10-unit grid, so a sub-unit tolerance is exact in practice
+# while still absorbing the fractional sub-step.
+ON_SEGMENT = 0.5
+
+# A non-MCU hot end this close to an MCU hot end, without touching it, is a placement slip
+# rather than a connection. Altium's grid here is 10 units.
+NEAR_MISS = 15.0
+
+
+class UnionFind:
+    """Path-compressing union-find over hashable point keys."""
+
+    __slots__ = ("parent",)
+
+    def __init__(self) -> None:
+        self.parent: dict = {}
+
+    def find(self, x):
+        self.parent.setdefault(x, x)
+        while self.parent[x] != x:
+            self.parent[x] = self.parent[self.parent[x]]
+            x = self.parent[x]
+        return x
+
+    def union(self, a, b) -> None:
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.parent[ra] = rb
+
+
+def point_to_segment(p: Point, a: Point, b: Point) -> float:
+    """Distance from point `p` to the segment `a`-`b` (not to the infinite line)."""
+    (px, py), (ax, ay), (bx, by) = p, a, b
+    dx, dy = bx - ax, by - ay
+    length_sq = dx * dx + dy * dy
+    if length_sq == 0:
+        return math.hypot(px - ax, py - ay)
+    t = max(0.0, min(1.0, ((px - ax) * dx + (py - ay) * dy) / length_sq))
+    return math.hypot(px - (ax + t * dx), py - (ay + t * dy))
+
+
+def key(p: Point) -> tuple[float, float]:
+    """Quantize a point so two coordinates that differ only in float noise collide."""
+    return (round(p[0], 3), round(p[1], 3))
+
+
+class PointIndex:
+    """Points bucketed by row and by column, so a segment only tests its own row.
+
+    Testing every point against every wire segment is O(segments x points), and a dense
+    MCU sheet has a few thousand of each: measured at 9.5 s for 4,000 segments. Schematic
+    wires are axis-aligned almost without exception, and a point within `tolerance` of a
+    horizontal segment must lie in one of two unit-height rows. Bucketing by floor(y) and
+    floor(x) narrows the candidates to those rows; the distance test itself is unchanged,
+    so the result is identical. A diagonal segment falls back to the full scan.
+    """
+
+    __slots__ = ("points", "rows", "cols")
+
+    def __init__(self, points: Iterable[Point]) -> None:
+        self.points = list(points)
+        self.rows: dict[int, list[Point]] = collections.defaultdict(list)
+        self.cols: dict[int, list[Point]] = collections.defaultdict(list)
+        for p in self.points:
+            self.rows[math.floor(p[1])].append(p)
+            self.cols[math.floor(p[0])].append(p)
+
+    def near_segment(self, a: Point, b: Point, tolerance: float = ON_SEGMENT) -> list[Point]:
+        """Every indexed point closer than `tolerance` to the segment `a`-`b`."""
+        if a[1] == b[1]:
+            buckets, at = self.rows, a[1]
+        elif a[0] == b[0]:
+            buckets, at = self.cols, a[0]
+        else:
+            return [q for q in self.points if point_to_segment(q, a, b) < tolerance]
+        candidates: list[Point] = []
+        for bucket in range(math.floor(at - tolerance), math.floor(at + tolerance) + 1):
+            candidates += buckets.get(bucket, ())
+        return [q for q in candidates if point_to_segment(q, a, b) < tolerance]