traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/kicad/pcb.py

@@ -0,0 +1,787 @@
+"""Read KiCad boards (``.kicad_pcb``, KiCad 6 to 10) and compute connectivity.
+
+Handles every syntax variant in use: ``fp_text`` (KiCad 6/7) and ``property``
+(KiCad 8+) footprint fields, ``tstamp``/``uuid``, bare ``hide`` and ``(hide yes)``,
+net codes with a net table (KiCad 6-9) and net names only (KiCad 10), arcs, rule
+areas (keepout zones), component classes, jumper pad groups and embedded files.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge import sexpr
+from traceforge.kicad.edgegeom import EdgeGeometry, arc_points, circle_points
+from traceforge.kicad.formats import flag, is_hidden, major_for
+from traceforge.sexpr import Node, find, find_all, num, prop, value
+
+
+@dataclass
+class Pad:
+    number: str
+    kind: str  # smd | thru_hole | np_thru_hole | connect
+    shape: str
+    x: float  # absolute board coordinates
+    y: float
+    width: float
+    height: float
+    layers: list[str]
+    net: str
+    drill: float = 0.0
+    function: str = ""  # schematic pin name ("pinfunction"), when KiCad recorded it
+    castellated: bool = False  # half-cut plated hole on the board edge
+
+    def contains(self, x: float, y: float, slack: float = 0.0) -> bool:
+        dx, dy = abs(x - self.x), abs(y - self.y)
+        half_w, half_h = self.width / 2 + slack, self.height / 2 + slack
+        if dx > half_w or dy > half_h:
+            return False
+        if self.shape == "circle":
+            return math.hypot(dx, dy) <= min(half_w, half_h)
+        if self.shape == "oval":
+            # Capsule: a rectangle with semicircular ends along the long axis.
+            radius = min(half_w, half_h)
+            if half_w >= half_h:
+                return math.hypot(max(0.0, dx - (half_w - radius)), dy) <= radius
+            return math.hypot(dx, max(0.0, dy - (half_h - radius))) <= radius
+        return True
+
+    def on_layer(self, layer: str) -> bool:
+        for name in self.layers:
+            if name == layer or name == "*.Cu" or (name == "F&B.Cu" and layer in {"F.Cu", "B.Cu"}):
+                return True
+        return False
+
+
+@dataclass
+class Footprint:
+    lib_id: str
+    reference: str
+    value: str
+    x: float
+    y: float
+    angle: float
+    layer: str
+    pads: list[Pad]
+    uuid: str = ""
+    path: str = ""
+    attrs: list[str] = field(default_factory=list)
+    fields: dict[str, str] = field(default_factory=dict)
+    texts: list[tuple[str, str, float]] = field(default_factory=list)  # (layer, text, height)
+    courtyard: tuple[float, float, float, float] | None = None  # absolute bbox
+    # Edge-mount connectors: (outward direction, point on the line that belongs on the
+    # board edge), both in board coordinates. None for ordinary parts.
+    edge: tuple[tuple[float, float], tuple[float, float]] | None = None
+    sheetname: str = ""
+    sheetfile: str = ""
+    component_classes: list[str] = field(default_factory=list)  # KiCad 9+
+    jumper_pad_groups: list[list[str]] = field(default_factory=list)  # KiCad 10
+    duplicate_pads_are_jumpers: bool = False  # KiCad 10
+    locked: bool = False
+
+    @property
+    def dnp(self) -> bool:
+        return "dnp" in self.attrs or self.fields.get("dnp", "").lower() in {"yes", "true"}
+
+
+@dataclass
+class Track:
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    width: float
+    layer: str
+    net: str
+    mid: tuple[float, float] | None = None  # arcs: a point on the arc
+
+    @property
+    def length(self) -> float:
+        if self.mid is not None:
+            arc = _arc_length((self.x1, self.y1), self.mid, (self.x2, self.y2))
+            if arc is not None:
+                return arc
+        return math.hypot(self.x2 - self.x1, self.y2 - self.y1)
+
+
+def _arc_length(
+    start: tuple[float, float], mid: tuple[float, float], end: tuple[float, float]
+) -> float | None:
+    (ax, ay), (bx, by), (cx, cy) = start, mid, end
+    d = 2 * (ax * (by - cy) + bx * (cy - ay) + cx * (ay - by))
+    if abs(d) < 1e-12:
+        return None
+    ux = (
+        (ax**2 + ay**2) * (by - cy) + (bx**2 + by**2) * (cy - ay) + (cx**2 + cy**2) * (ay - by)
+    ) / d
+    uy = (
+        (ax**2 + ay**2) * (cx - bx) + (bx**2 + by**2) * (ax - cx) + (cx**2 + cy**2) * (bx - ax)
+    ) / d
+    radius = math.hypot(ax - ux, ay - uy)
+    angles = [math.atan2(py - uy, px - ux) for px, py in (start, mid, end)]
+    sweep = (angles[2] - angles[0]) % (2 * math.pi)
+    mid_sweep = (angles[1] - angles[0]) % (2 * math.pi)
+    if mid_sweep > sweep:  # the arc runs the other way round
+        sweep = 2 * math.pi - sweep
+    return radius * sweep
+
+
+@dataclass
+class Via:
+    x: float
+    y: float
+    size: float
+    drill: float
+    layers: list[str]
+    net: str
+
+
+@dataclass
+class Board:
+    path: Path
+    version: str
+    thickness: float
+    copper_layers: list[str]
+    nets: dict[int, str]
+    footprints: list[Footprint]
+    tracks: list[Track]
+    vias: list[Via]
+    zones: list[dict]
+    outline: tuple[float, float, float, float] | None  # min_x, min_y, max_x, max_y
+    texts: list[tuple[str, str, float]]  # board-level (layer, text, height)
+    rules: dict[str, float]
+    generator: str = ""
+    generator_version: str = ""
+    embedded_files: list[str] = field(default_factory=list)  # KiCad 9+
+    tables: int = 0  # KiCad 9+
+    rule_areas: list[dict] = field(default_factory=list)  # keepout / placement areas
+    variants: list[str] = field(default_factory=list)  # KiCad 10
+    edge_segments: list[tuple[float, float, float, float]] = field(default_factory=list)
+
+    @property
+    def edge_geometry(self) -> EdgeGeometry | None:
+        """The Edge.Cuts shapes (outline, cut-outs, slots) for inside/distance queries."""
+        if self.outline is None:
+            return None
+        if not self.edge_segments:
+            x0, y0, x1, y1 = self.outline
+            return EdgeGeometry(
+                [(x0, y0, x1, y0), (x1, y0, x1, y1), (x1, y1, x0, y1), (x0, y1, x0, y0)]
+            )
+        return EdgeGeometry(self.edge_segments)
+
+    @property
+    def kicad_major(self) -> int | None:
+        return major_for("board", int(num(self.version, 0)))
+
+    @property
+    def size_mm(self) -> tuple[float, float] | None:
+        if self.outline is None:
+            return None
+        return (self.outline[2] - self.outline[0], self.outline[3] - self.outline[1])
+
+    def footprint(self, reference: str) -> Footprint | None:
+        for item in self.footprints:
+            if item.reference == reference:
+                return item
+        return None
+
+
+def pin_function(raw: object, number: str) -> str:
+    """A pad's schematic pin name from KiCad's ``pinfunction`` field.
+
+    KiCad 10 appends the pin number to the name (``VCC_2`` for pin 2 named ``VCC``);
+    KiCad 8 and 9 write the plain name.
+    """
+    name = str(raw or "")
+    suffix = f"_{number}"
+    if number and name.endswith(suffix) and len(name) > len(suffix):
+        return name[: -len(suffix)]
+    return name
+
+
+def _rotate(dx: float, dy: float, angle_deg: float) -> tuple[float, float]:
+    """KiCad rotates counter-clockwise on screen; with Y pointing down that is -angle."""
+    if not angle_deg:
+        return dx, dy
+    rad = math.radians(-angle_deg)
+    return (dx * math.cos(rad) - dy * math.sin(rad), dx * math.sin(rad) + dy * math.cos(rad))
+
+
+_EDGE_LIBRARIES = (
+    "Connector_USB:",
+    "Connector_BarrelJack:",
+    "Connector_Audio:",
+    "Connector_RJ:",
+    "Connector_Coaxial:",
+    "Connector_Card:",
+)
+_EDGE_LAYERS = {"Dwgs.User", "Cmts.User", "F.Fab", "B.Fab"}
+
+
+def edge_marker(node: Node, lib_id: str = "") -> tuple[tuple[float, float], float] | None:
+    """Where an edge-mount connector meets the board edge, in footprint coordinates.
+
+    Returns ``(direction, offset)``: ``direction`` is the unit vector (axis-aligned)
+    pointing out of the board through the connector's opening, and the board edge
+    belongs on the line ``direction . p == offset``. KiCad's library footprints mark
+    this with a "PCB Edge" note and a line on a drawing layer; without that marker,
+    connectors from edge-mount libraries (USB, barrel, audio, RJ, coax, cards) use
+    the courtyard side furthest from the pads.
+    """
+    lib_id = lib_id or (str(node[1]) if len(node) > 1 else "")
+    pads = []
+    for pad in find_all(node, "pad"):
+        at = find(pad, "at")
+        if at is not None and len(at) > 2:
+            pads.append((num(at[1]), num(at[2])))
+    if not pads:
+        return None
+    cx = sum(p[0] for p in pads) / len(pads)
+    cy = sum(p[1] for p in pads) / len(pads)
+
+    marker = None
+    for child in node:
+        if (
+            isinstance(child, list)
+            and child
+            and child[0] in ("fp_text", "property")
+            and any(isinstance(a, str) and "pcb edge" in a.lower() for a in child[1:3])
+        ):
+            at = find(child, "at")
+            if at is not None and len(at) > 2:
+                marker = (num(at[1]), num(at[2]))
+                break
+    if marker is not None:
+        best = None
+        for line in find_all(node, "fp_line"):
+            if str(value(line, "layer", "")) not in _EDGE_LAYERS:
+                continue
+            start, end = find(line, "start"), find(line, "end")
+            if start is None or end is None:
+                continue
+            x0, y0, x1, y1 = num(start[1]), num(start[2]), num(end[1]), num(end[2])
+            if abs(y0 - y1) < 1e-3 and abs(x1 - x0) >= 2:
+                axis, coord = "y", y0
+                distance = abs(marker[1] - y0) + max(
+                    0.0, min(x0, x1) - marker[0], marker[0] - max(x0, x1)
+                )
+            elif abs(x0 - x1) < 1e-3 and abs(y1 - y0) >= 2:
+                axis, coord = "x", x0
+                distance = abs(marker[0] - x0) + max(
+                    0.0, min(y0, y1) - marker[1], marker[1] - max(y0, y1)
+                )
+            else:
+                continue
+            if best is None or distance < best[0]:
+                best = (distance, axis, coord)
+        if best is not None and best[0] < 3.0:
+            _, axis, coord = best
+            if axis == "y":
+                sign = 1.0 if coord >= cy else -1.0
+                return (0.0, sign), sign * coord
+            sign = 1.0 if coord >= cx else -1.0
+            return (sign, 0.0), sign * coord
+    if not lib_id.startswith(_EDGE_LIBRARIES) or "Vertical" in lib_id:
+        return None
+    xs: list[float] = []
+    ys: list[float] = []
+    for child in node:
+        if isinstance(child, list) and child and str(child[0]).startswith("fp_"):
+            if str(value(child, "layer", "")).endswith("CrtYd"):
+                for key in ("start", "end"):
+                    point = find(child, key)
+                    if point is not None:
+                        xs.append(num(point[1]))
+                        ys.append(num(point[2]))
+    if not xs:
+        return None
+    sides = [
+        ((1.0, 0.0), max(xs), max(xs) - cx),
+        ((-1.0, 0.0), -min(xs), cx - min(xs)),
+        ((0.0, 1.0), max(ys), max(ys) - cy),
+        ((0.0, -1.0), -min(ys), cy - min(ys)),
+    ]
+    direction, offset, _ = max(sides, key=lambda s: s[2])
+    return direction, offset
+
+
+def _net_name(node: Node, nets: dict[int, str]) -> str:
+    net = find(node, "net")
+    if net is None or len(net) < 2:
+        return ""
+    if len(net) >= 3:
+        return str(net[2])
+    # KiCad 9 can write (net "name"); older files write (net <code>) on tracks.
+    first = net[1]
+    if isinstance(first, sexpr.Sym):
+        return nets.get(int(num(first, -1)), "")
+    return str(first)
+
+
+def _footprint_text(node: Node) -> list[tuple[str, str, float]]:
+    texts: list[tuple[str, str, float]] = []
+    for child in [
+        *find_all(node, "fp_text"),
+        *find_all(node, "property"),
+        *find_all(node, "gr_text"),
+    ]:
+        layer = value(child, "layer")
+        if layer is None:
+            continue
+        effects = find(child, "effects")
+        font = find(effects, "font") if effects else None
+        size = find(font, "size") if font else None
+        if is_hidden(child):
+            continue
+        text = (
+            str(child[2])
+            if child[0] in {"fp_text", "property"} and len(child) > 2
+            else str(child[1])
+        )
+        texts.append((str(layer), text, num(size[2]) if size and len(size) > 2 else 1.0))
+    return texts
+
+
+def _read_footprint(node: Node, nets: dict[int, str]) -> Footprint:
+    at = find(node, "at") or [None, 0, 0]
+    fx, fy = num(at[1]), num(at[2])
+    angle = num(at[3]) if len(at) > 3 else 0.0
+    reference = prop(node, "Reference") or ""
+    footprint_value = prop(node, "Value") or ""
+    for text in find_all(node, "fp_text"):  # KiCad 6/7
+        if len(text) > 2 and text[1] == "reference":
+            reference = reference or str(text[2])
+        if len(text) > 2 and text[1] == "value":
+            footprint_value = footprint_value or str(text[2])
+    pads: list[Pad] = []
+    for pad in find_all(node, "pad"):
+        pad_at = find(pad, "at") or [None, 0, 0]
+        dx, dy = _rotate(num(pad_at[1]), num(pad_at[2]), angle)
+        size = find(pad, "size") or [None, 0, 0]
+        width, height = num(size[1]), num(size[2])
+        pad_angle = num(pad_at[3]) if len(pad_at) > 3 else angle
+        if round(pad_angle) % 180 == 90:
+            width, height = height, width
+        layers_node = find(pad, "layers")
+        drill = find(pad, "drill")
+        drill_size = 0.0
+        if drill is not None:
+            numbers = [num(a) for a in drill[1:] if isinstance(a, sexpr.Sym) and a != "oval"]
+            drill_size = min(numbers) if numbers else 0.0
+        pads.append(
+            Pad(
+                number=str(pad[1]),
+                kind=str(pad[2]) if len(pad) > 2 else "smd",
+                shape=str(pad[3]) if len(pad) > 3 else "rect",
+                x=fx + dx,
+                y=fy + dy,
+                width=width,
+                height=height,
+                layers=[str(a) for a in layers_node[1:]] if layers_node else [],
+                net=_net_name(pad, nets),
+                drill=drill_size,
+                function=pin_function(value(pad, "pinfunction", ""), str(pad[1])),
+                castellated=any(
+                    str(p[1]) == "pad_prop_castellated"
+                    for p in find_all(pad, "property")
+                    if len(p) > 1
+                ),
+            )
+        )
+    attrs_node = find(node, "attr")
+    fields = {str(c[1]): str(c[2]) for c in find_all(node, "property") if len(c) >= 3}
+    classes_node = find(node, "component_classes")
+    jumpers_node = find(node, "jumper_pad_groups")
+    courtyard = _courtyard(node, fx, fy, angle)
+    edge = None
+    marker = edge_marker(node)
+    if marker is not None:
+        (ux, uy), offset = marker
+        dx, dy = _rotate(ux, uy, angle)
+        px, py = _rotate(ux * offset, uy * offset, angle)
+        edge = ((round(dx, 6), round(dy, 6)), (fx + px, fy + py))
+    return Footprint(
+        lib_id=str(node[1]) if len(node) > 1 else "",
+        reference=reference,
+        value=footprint_value,
+        x=fx,
+        y=fy,
+        angle=angle,
+        layer=str(value(node, "layer", "F.Cu")),
+        pads=pads,
+        uuid=str(value(node, "uuid", value(node, "tstamp", ""))),
+        path=str(value(node, "path", "")),
+        attrs=[str(a) for a in attrs_node[1:]] if attrs_node else [],
+        fields=fields,
+        texts=_footprint_text(node),
+        courtyard=courtyard,
+        edge=edge,
+        sheetname=str(value(node, "sheetname", fields.get("Sheetname", ""))),
+        sheetfile=str(value(node, "sheetfile", fields.get("Sheetfile", ""))),
+        component_classes=[str(c[1]) for c in find_all(classes_node, "class") if len(c) > 1]
+        if classes_node
+        else [],
+        jumper_pad_groups=[
+            [str(a) for a in group] for group in jumpers_node[1:] if isinstance(group, list)
+        ]
+        if jumpers_node
+        else [],
+        duplicate_pads_are_jumpers=flag(node, "duplicate_pad_numbers_are_jumpers"),
+        locked=flag(node, "locked"),
+    )
+
+
+def _courtyard(node: Node, fx: float, fy: float, angle: float):
+    xs: list[float] = []
+    ys: list[float] = []
+    for child in node:
+        if not isinstance(child, list) or not child or not str(child[0]).startswith("fp_"):
+            continue
+        layer = str(value(child, "layer", ""))
+        if not layer.endswith("CrtYd"):
+            continue
+        for key in ("start", "end", "center", "mid"):
+            point = find(child, key)
+            if point is not None:
+                dx, dy = _rotate(num(point[1]), num(point[2]), angle)
+                xs.append(fx + dx)
+                ys.append(fy + dy)
+        pts = find(child, "pts")
+        if pts is not None:
+            for xy in find_all(pts, "xy"):
+                dx, dy = _rotate(num(xy[1]), num(xy[2]), angle)
+                xs.append(fx + dx)
+                ys.append(fy + dy)
+    if not xs:
+        return None
+    return (min(xs), min(ys), max(xs), max(ys))
+
+
+def _outline(root: Node) -> tuple[float, float, float, float] | None:
+    xs: list[float] = []
+    ys: list[float] = []
+    for child in root:
+        if not isinstance(child, list) or not child or not str(child[0]).startswith("gr_"):
+            continue
+        if str(value(child, "layer", "")) != "Edge.Cuts":
+            continue
+        if child[0] == "gr_circle":
+            center, end = find(child, "center"), find(child, "end")
+            if center and end:
+                radius = math.hypot(num(end[1]) - num(center[1]), num(end[2]) - num(center[2]))
+                xs += [num(center[1]) - radius, num(center[1]) + radius]
+                ys += [num(center[2]) - radius, num(center[2]) + radius]
+            continue
+        for key in ("start", "end", "mid"):
+            point = find(child, key)
+            if point is not None:
+                xs.append(num(point[1]))
+                ys.append(num(point[2]))
+        pts = find(child, "pts")
+        if pts is not None:
+            for xy in find_all(pts, "xy"):
+                xs.append(num(xy[1]))
+                ys.append(num(xy[2]))
+    if not xs:
+        return None
+    return (min(xs), min(ys), max(xs), max(ys))
+
+
+def _edge_segments(root: Node) -> list[tuple[float, float, float, float]]:
+    """Edge.Cuts lines, arcs, circles, rectangles and polygons as straight segments."""
+    segments: list[tuple[float, float, float, float]] = []
+
+    def path(points: list[tuple[float, float]], closed: bool = False) -> None:
+        if closed and points and points[0] != points[-1]:
+            points = [*points, points[0]]
+        segments.extend((a[0], a[1], b[0], b[1]) for a, b in zip(points, points[1:]))
+
+    def xy(node: Node | None) -> tuple[float, float]:
+        return (num(node[1]), num(node[2])) if node is not None and len(node) > 2 else (0.0, 0.0)
+
+    for child in root:
+        if not isinstance(child, list) or not child or not str(child[0]).startswith("gr_"):
+            continue
+        if str(value(child, "layer", "")) != "Edge.Cuts":
+            continue
+        kind = str(child[0])
+        if kind == "gr_line":
+            path([xy(find(child, "start")), xy(find(child, "end"))])
+        elif kind == "gr_arc":
+            path(
+                arc_points(xy(find(child, "start")), xy(find(child, "mid")), xy(find(child, "end")))
+            )
+        elif kind == "gr_circle":
+            center, end = xy(find(child, "center")), xy(find(child, "end"))
+            path(circle_points(center, math.hypot(end[0] - center[0], end[1] - center[1])))
+        elif kind == "gr_rect":
+            (ax, ay), (bx, by) = xy(find(child, "start")), xy(find(child, "end"))
+            path([(ax, ay), (bx, ay), (bx, by), (ax, by)], closed=True)
+        elif kind == "gr_poly":
+            pts = find(child, "pts")
+            if pts is not None:
+                path([xy(p) for p in find_all(pts, "xy")], closed=True)
+    return segments
+
+
+def _rules(root: Node) -> dict[str, float]:
+    rules: dict[str, float] = {}
+    setup = find(root, "setup")
+    if setup is not None:
+        for key in ("pad_to_mask_clearance", "solder_mask_min_width"):
+            item = value(setup, key)
+            if item is not None:
+                rules[key] = num(item)
+    return rules
+
+
+def read_board(path: str | Path) -> Board:
+    path = Path(path)
+    root = sexpr.parse(path.read_text(encoding="utf-8"))
+    if root[0] != "kicad_pcb":
+        raise ValueError(f"{path} is not a KiCad board (found {root[0]!r})")
+    nets: dict[int, str] = {}
+    for net in find_all(root, "net"):
+        if len(net) >= 3:
+            nets[int(num(net[1]))] = str(net[2])
+    if not nets:
+        # KiCad 10 stores net names on the items only; give them stable local codes.
+        names: set[str] = set()
+        for item in sexpr.walk(root):
+            if item and item[0] in {"pad", "segment", "arc", "via", "zone"}:
+                net = find(item, "net")
+                if net is not None and len(net) >= 2 and not isinstance(net[1], sexpr.Sym):
+                    names.add(str(net[1]))
+        nets = {0: ""}
+        for index, name in enumerate(sorted(names - {""}), start=1):
+            nets[index] = name
+    copper: list[str] = []
+    layers = find(root, "layers")
+    if layers is not None:
+        for layer in layers[1:]:
+            if isinstance(layer, list) and len(layer) >= 3 and str(layer[1]).endswith(".Cu"):
+                copper.append(str(layer[1]))
+    general = find(root, "general")
+    tracks: list[Track] = []
+    for seg in [*find_all(root, "segment"), *find_all(root, "arc")]:
+        start, end = find(seg, "start"), find(seg, "end")
+        if start is None or end is None:
+            continue
+        mid = find(seg, "mid")
+        tracks.append(
+            Track(
+                num(start[1]),
+                num(start[2]),
+                num(end[1]),
+                num(end[2]),
+                num(value(seg, "width", 0)),
+                str(value(seg, "layer", "")),
+                _net_name(seg, nets),
+                (num(mid[1]), num(mid[2])) if mid is not None else None,
+            )
+        )
+    vias: list[Via] = []
+    for via in find_all(root, "via"):
+        at = find(via, "at") or [None, 0, 0]
+        layers_node = find(via, "layers")
+        vias.append(
+            Via(
+                num(at[1]),
+                num(at[2]),
+                num(value(via, "size", 0)),
+                num(value(via, "drill", 0)),
+                [str(a) for a in layers_node[1:]] if layers_node else ["F.Cu", "B.Cu"],
+                _net_name(via, nets),
+            )
+        )
+    zones = []
+    rule_areas = []
+    for zone in find_all(root, "zone"):
+        layer_names = [str(value(zone, "layer", ""))] if find(zone, "layer") else []
+        multi = find(zone, "layers")
+        if multi is not None:
+            layer_names = [str(a) for a in multi[1:]]
+        keepout = find(zone, "keepout")
+        if keepout is not None or find(zone, "placement") is not None:
+            # A rule area: keepout and/or (KiCad 9+) placement rules, never copper.
+            rule_areas.append(
+                {
+                    "name": str(value(zone, "name", "")),
+                    "layers": layer_names,
+                    "keepout": {
+                        str(c[0]): str(c[1])
+                        for c in (keepout[1:] if keepout is not None else [])
+                        if isinstance(c, list) and len(c) > 1
+                    },
+                }
+            )
+            continue
+        zones.append(
+            {
+                "net": str(value(zone, "net_name", "")) or _net_name(zone, nets),
+                "name": str(value(zone, "name", "")),
+                "layers": layer_names,
+                "filled": find(zone, "filled_polygon") is not None,
+            }
+        )
+    texts = []
+    for text in find_all(root, "gr_text"):
+        effects = find(text, "effects")
+        font = find(effects, "font") if effects else None
+        size = find(font, "size") if font else None
+        texts.append(
+            (
+                str(value(text, "layer", "")),
+                str(text[1]),
+                num(size[2]) if size and len(size) > 2 else 1.0,
+            )
+        )
+    return Board(
+        path=path,
+        version=str(value(root, "version", "")),
+        thickness=num(value(general, "thickness", 1.6), 1.6) if general else 1.6,
+        copper_layers=copper or ["F.Cu", "B.Cu"],
+        nets=nets,
+        footprints=[
+            _read_footprint(fp, nets)
+            for fp in [*find_all(root, "footprint"), *find_all(root, "module")]
+        ],
+        tracks=tracks,
+        vias=vias,
+        zones=zones,
+        outline=_outline(root),
+        edge_segments=_edge_segments(root),
+        texts=texts,
+        rules=_rules(root),
+        generator=str(value(root, "generator", "")),
+        generator_version=str(value(root, "generator_version", "")),
+        embedded_files=_embedded_files(root),
+        tables=len(find_all(root, "table")),
+        rule_areas=rule_areas,
+        variants=[
+            str(value(v, "name", v[1] if len(v) > 1 and not isinstance(v[1], list) else ""))
+            for v in find_all(find(root, "variants") or [], "variant")
+        ],
+    )
+
+
+def _embedded_files(root: Node) -> list[str]:
+    """Names of files embedded in a KiCad 9+ board or schematic (fonts, datasheets, models)."""
+    files = find(root, "embedded_files")
+    if files is None:
+        return []
+    return [str(value(f, "name", "")) for f in find_all(files, "file")]
+
+
+# --------------------------------------------------------------------------- connectivity
+
+
+class _UnionFind:
+    def __init__(self) -> None:
+        self.parent: dict[int, int] = {}
+
+    def find(self, item: int) -> int:
+        self.parent.setdefault(item, item)
+        while self.parent[item] != item:
+            self.parent[item] = self.parent[self.parent[item]]
+            item = self.parent[item]
+        return item
+
+    def union(self, a: int, b: int) -> None:
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.parent[ra] = rb
+
+
+@dataclass
+class NetStatus:
+    net: str
+    pads: int
+    islands: int  # connected groups of pads; 1 means fully routed
+
+    @property
+    def unrouted(self) -> int:
+        return max(0, self.islands - 1)
+
+
+def connectivity(board: Board, tolerance: float = 0.005) -> list[NetStatus]:
+    """Approximate routing completeness per net.
+
+    Pads, track ends and vias of the same net are joined when they touch.
+    Zones with fill are treated as connecting every pad of their net on their
+    layers. This mirrors KiCad's ratsnest closely for typical boards; DRC from
+    ``kicad-cli`` remains the authority.
+    """
+    results: list[NetStatus] = []
+    by_net: dict[str, list[Pad]] = {}
+    for footprint in board.footprints:
+        for pad in footprint.pads:
+            if pad.net and pad.kind != "np_thru_hole":
+                by_net.setdefault(pad.net, []).append(pad)
+    zone_layers: dict[str, set[str]] = {}
+    for zone in board.zones:
+        if zone["net"] and zone["filled"]:
+            zone_layers.setdefault(zone["net"], set()).update(zone["layers"])
+
+    for net, pads in sorted(by_net.items()):
+        if len(pads) < 2:
+            results.append(NetStatus(net, len(pads), len(pads)))
+            continue
+        uf = _UnionFind()
+        tracks = [t for t in board.tracks if t.net == net]
+        vias = [v for v in board.vias if v.net == net]
+        # node ids: pads 0..P-1, track ends after, vias after
+        points: list[tuple[float, float, set[str], int]] = []
+        for i in range(len(pads)):
+            uf.find(i)
+        base = len(pads)
+        for j, track in enumerate(tracks):
+            a, b = base + 2 * j, base + 2 * j + 1
+            uf.union(a, b)
+            points.append((track.x1, track.y1, {track.layer}, a))
+            points.append((track.x2, track.y2, {track.layer}, b))
+        via_base = base + 2 * len(tracks)
+        for k, via in enumerate(vias):
+            layers = (
+                set(board.copper_layers) if via.layers[:2] == ["F.Cu", "B.Cu"] else set(via.layers)
+            )
+            points.append((via.x, via.y, layers, via_base + k))
+        for x, y, layers, node in points:
+            for i, pad in enumerate(pads):
+                if any(pad.on_layer(layer) for layer in layers) and pad.contains(x, y, tolerance):
+                    uf.union(node, i)
+        for index, (x1, y1, l1, n1) in enumerate(points):
+            for x2, y2, l2, n2 in points[index + 1 :]:
+                if l1 & l2 and abs(x1 - x2) <= tolerance and abs(y1 - y2) <= tolerance:
+                    uf.union(n1, n2)
+        # Track ends that land on the middle of another track (T-junctions).
+        for x, y, layers, node in points:
+            for j, track in enumerate(tracks):
+                if track.layer in layers and _on_segment(x, y, track, tolerance + track.width / 2):
+                    uf.union(node, base + 2 * j)
+        if net in zone_layers:
+            # A filled pour joins every pad, via and track end of its net on its layers.
+            # (Islands cut off by other copper are not detected; DRC reports those.)
+            zone_node = via_base + len(vias)
+            for i, pad in enumerate(pads):
+                if any(pad.on_layer(layer) for layer in zone_layers[net]):
+                    uf.union(zone_node, i)
+            for _, _, layers, node in points:
+                if layers & zone_layers[net]:
+                    uf.union(zone_node, node)
+        islands = len({uf.find(i) for i in range(len(pads))})
+        results.append(NetStatus(net, len(pads), islands))
+    return results
+
+
+def _on_segment(x: float, y: float, track: Track, tolerance: float) -> bool:
+    dx, dy = track.x2 - track.x1, track.y2 - track.y1
+    length_sq = dx * dx + dy * dy
+    if length_sq == 0:
+        return math.hypot(x - track.x1, y - track.y1) <= tolerance
+    t = max(0.0, min(1.0, ((x - track.x1) * dx + (y - track.y1) * dy) / length_sq))
+    px, py = track.x1 + t * dx, track.y1 + t * dy
+    return math.hypot(x - px, y - py) <= tolerance