traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/kicad/edgegeom.py

@@ -0,0 +1,191 @@
+"""Board edge geometry: the Edge.Cuts shapes as line segments, for inside and distance queries.
+
+Boards are rarely plain rectangles: L-shapes, circles, slots and cut-outs all end up as lines,
+arcs, circles and polygons on Edge.Cuts. Every loop, outer or inner, is flattened to segments, so
+"inside the board" is the even-odd rule over all of them and "room" is the signed distance to the
+nearest edge (positive inside). A plain rectangle takes a fast path, so the router and the checks
+cost nothing extra on the common board.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+Point = tuple[float, float]
+Segment = tuple[float, float, float, float]
+
+_SAGITTA = 0.02  # mm: how far a flattened arc may stray from the true curve
+
+
+def arc_points(start: Point, mid: Point, end: Point) -> list[Point]:
+    """Points along the arc through three points (both ends included)."""
+    (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 [start, end]
+    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)
+    a0, a1, a2 = (math.atan2(py - uy, px - ux) for px, py in (start, mid, end))
+    sweep = (a2 - a0) % (2 * math.pi)
+    if (a1 - a0) % (2 * math.pi) > sweep:  # the arc runs clockwise
+        sweep -= 2 * math.pi
+    step = 2 * math.acos(max(0.0, 1 - _SAGITTA / max(radius, _SAGITTA)))
+    count = max(2, int(math.ceil(abs(sweep) / max(step, 1e-3))))
+    pts = [
+        (
+            ux + radius * math.cos(a0 + sweep * i / count),
+            uy + radius * math.sin(a0 + sweep * i / count),
+        )
+        for i in range(count + 1)
+    ]
+    pts[0], pts[-1] = start, end
+    return pts
+
+
+def circle_points(center: Point, radius: float) -> list[Point]:
+    cx, cy = center
+    step = 2 * math.acos(max(0.0, 1 - _SAGITTA / max(radius, _SAGITTA)))
+    count = max(8, int(math.ceil(2 * math.pi / max(step, 1e-3))))
+    pts = [
+        (
+            cx + radius * math.cos(2 * math.pi * i / count),
+            cy + radius * math.sin(2 * math.pi * i / count),
+        )
+        for i in range(count)
+    ]
+    return [*pts, pts[0]]
+
+
+def _seg_dist(px: float, py: float, s: Segment) -> float:
+    ax, ay, bx, by = s
+    dx, dy = bx - ax, by - ay
+    n = dx * dx + dy * dy
+    t = 0.0 if n == 0 else max(0.0, min(1.0, ((px - ax) * dx + (py - ay) * dy) / n))
+    return math.hypot(px - ax - t * dx, py - ay - t * dy)
+
+
+def _cross(ox: float, oy: float, ax: float, ay: float, bx: float, by: float) -> float:
+    return (ax - ox) * (by - oy) - (ay - oy) * (bx - ox)
+
+
+def _seg_seg_dist(a: Segment, b: Segment) -> float:
+    ax, ay, bx, by = a
+    cx, cy, dx, dy = b
+    d1 = _cross(ax, ay, bx, by, cx, cy)
+    d2 = _cross(ax, ay, bx, by, dx, dy)
+    d3 = _cross(cx, cy, dx, dy, ax, ay)
+    d4 = _cross(cx, cy, dx, dy, bx, by)
+    if ((d1 > 0) != (d2 > 0)) and ((d3 > 0) != (d4 > 0)) and 0 not in (d1, d2, d3, d4):
+        return 0.0
+    return min(
+        _seg_dist(ax, ay, b), _seg_dist(bx, by, b), _seg_dist(cx, cy, a), _seg_dist(dx, dy, a)
+    )
+
+
+@dataclass
+class EdgeGeometry:
+    segments: list[Segment]
+    bbox: tuple[float, float, float, float] = field(init=False)
+    is_rect: bool = field(init=False)
+
+    def __post_init__(self) -> None:
+        xs = [v for s in self.segments for v in (s[0], s[2])]
+        ys = [v for s in self.segments for v in (s[1], s[3])]
+        self.bbox = (min(xs), min(ys), max(xs), max(ys)) if xs else (0.0, 0.0, 0.0, 0.0)
+        x0, y0, x1, y1 = self.bbox
+        eps = 1e-6
+        self.is_rect = all(
+            (abs(s[0] - s[2]) < eps and (abs(s[0] - x0) < eps or abs(s[0] - x1) < eps))
+            or (abs(s[1] - s[3]) < eps and (abs(s[1] - y0) < eps or abs(s[1] - y1) < eps))
+            for s in self.segments
+        )
+
+    # -- point queries
+    def inside(self, x: float, y: float) -> bool:
+        if self.is_rect:
+            x0, y0, x1, y1 = self.bbox
+            return x0 <= x <= x1 and y0 <= y <= y1
+        hit = False
+        for ax, ay, bx, by in self.segments:
+            if (ay > y) != (by > y) and x < ax + (y - ay) * (bx - ax) / (by - ay):
+                hit = not hit
+        return hit
+
+    def distance(self, x: float, y: float) -> float:
+        """Distance to the nearest edge segment."""
+        return min((_seg_dist(x, y, s) for s in self.segments), default=math.inf)
+
+    def room(self, x: float, y: float) -> float:
+        """Signed clearance to the edge: positive inside the board, negative outside."""
+        if self.is_rect:
+            x0, y0, x1, y1 = self.bbox
+            return min(x - x0, x1 - x, y - y0, y1 - y)
+        d = self.distance(x, y)
+        return d if self.inside(x, y) else -d
+
+    def segment_room(self, ax: float, ay: float, bx: float, by: float) -> float:
+        """Smallest clearance along a straight run (negative if it leaves the board)."""
+        if self.is_rect:
+            return min(self.room(ax, ay), self.room(bx, by))
+        room = min(self.room(ax, ay), self.room(bx, by))
+        probe = (ax, ay, bx, by)
+        lo = min(ax, bx) - max(room, 0.0)
+        for s in self.segments:
+            if max(s[0], s[2]) < lo or min(s[0], s[2]) > max(ax, bx) + max(room, 0.0):
+                continue
+            d = _seg_seg_dist(probe, s)
+            if d < room:
+                room = d if d > 0 else -1e-3
+        return room
+
+    # -- grid queries
+    def blocked_cells(
+        self, x0: float, y0: float, step: float, w: int, h: int, margin: float
+    ) -> bytearray:
+        """Grid cells (index ``gy * w + gx``) outside the board or closer than ``margin`` to an edge."""
+        out = bytearray(w * h)
+        if self.is_rect:
+            bx0, by0, bx1, by1 = self.bbox
+            for gy in range(h):
+                y = y0 + gy * step
+                for gx in range(w):
+                    x = x0 + gx * step
+                    if min(x - bx0, bx1 - x, y - by0, by1 - y) < margin:
+                        out[gy * w + gx] = 1
+            return out
+        for gy in range(h):
+            y = y0 + gy * step
+            xs = sorted(
+                ax + (y - ay) * (bx - ax) / (by - ay)
+                for ax, ay, bx, by in self.segments
+                if (ay > y) != (by > y)
+            )
+            gx = 0
+            row = gy * w
+            for lo, hi in zip(xs[0::2], xs[1::2]):
+                first = max(0, int(math.ceil((lo - x0) / step)))
+                last = min(w - 1, int(math.floor((hi - x0) / step)))
+                for cell in range(gx, min(first, w)):
+                    out[row + cell] = 1
+                gx = max(gx, last + 1)
+            for cell in range(gx, w):
+                out[row + cell] = 1
+        for ax, ay, bx, by in self.segments:
+            gx0 = max(0, int((min(ax, bx) - margin - x0) / step) - 1)
+            gx1 = min(w - 1, int((max(ax, bx) + margin - x0) / step) + 1)
+            gy0 = max(0, int((min(ay, by) - margin - y0) / step) - 1)
+            gy1 = min(h - 1, int((max(ay, by) + margin - y0) / step) + 1)
+            seg = (ax, ay, bx, by)
+            for gy in range(gy0, gy1 + 1):
+                y = y0 + gy * step
+                row = gy * w
+                for gx in range(gx0, gx1 + 1):
+                    if not out[row + gx] and _seg_dist(x0 + gx * step, y, seg) < margin:
+                        out[row + gx] = 1
+        return out

traceforge/kicad/edit.py

@@ -0,0 +1,405 @@
+"""Structured edits to KiCad files.
+
+The agent can always edit S-expressions as text, but these helpers make the
+common operations exact: they keep UUIDs unique, nets consistent and rotate
+pads along with their footprint.
+
+Edits keep the file's own format: new items use ``uuid`` or ``tstamp`` and net
+codes or (KiCad 10) net names, whichever the file uses. :func:`convert_file`
+rewrites a whole file for another KiCad release.
+"""
+
+from __future__ import annotations
+
+import uuid
+from pathlib import Path
+
+from traceforge import sexpr
+from traceforge.kicad import formats
+from traceforge.sexpr import Node, Sym, find, find_all, fmt, num, prop, set_prop, value
+
+
+class EditError(ValueError):
+    """The requested edit does not apply to this file."""
+
+
+def load(path: Path) -> Node:
+    return sexpr.parse(Path(path).read_text(encoding="utf-8"))
+
+
+def save(path: Path, root: Node) -> None:
+    Path(path).write_text(sexpr.dumps(root), encoding="utf-8")
+
+
+def _new_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+def _stamp_key(root: Node) -> str:
+    # KiCad 7 boards use (tstamp ...); KiCad 8+ use (uuid ...).
+    return formats.stamp_key(root)
+
+
+def _footprint_ref(node: Node) -> str:
+    reference = prop(node, "Reference")
+    if reference:
+        return reference
+    for text in find_all(node, "fp_text"):
+        if len(text) > 2 and text[1] == "reference":
+            return str(text[2])
+    return ""
+
+
+def footprints(root: Node) -> dict[str, Node]:
+    return {
+        _footprint_ref(fp): fp for fp in [*find_all(root, "footprint"), *find_all(root, "module")]
+    }
+
+
+def net_codes(root: Node) -> dict[str, int]:
+    """Net name -> code. KiCad 10 boards have no codes; their nets get local numbers."""
+    codes = {str(n[2]): int(num(n[1])) for n in find_all(root, "net") if len(n) >= 3}
+    if codes:
+        return codes
+    return {name: i for i, name in enumerate(formats.board_net_names(root), start=1)}
+
+
+def _net_node(root: Node, net: str) -> Node:
+    try:
+        return formats.board_net_node(root, net)
+    except KeyError:
+        raise EditError(f"net {net!r} does not exist on the board") from None
+
+
+def _item_net(root: Node, item: Node, codes: dict[str, int]) -> str | None:
+    net = find(item, "net")
+    if net is None or len(net) < 2:
+        return None
+    if len(net) >= 3 or not isinstance(net[1], Sym):
+        return str(net[-1])
+    by_code = {code: name for name, code in codes.items()}
+    return by_code.get(int(num(net[1], -1)))
+
+
+def convert_file(path: Path, kicad_version: int | str, out: Path | None = None) -> dict:
+    """Rewrite a schematic, board, footprint or symbol library for another KiCad release."""
+    root = load(path)
+    before = formats.root_info(root)
+    target = formats.resolve_target(kicad_version)
+    formats.convert(root, target)
+    save(out or path, root)
+    return {"from": before.to_dict(), "to": formats.root_info(root).to_dict()}
+
+
+# ----------------------------------------------------------------------- schematic
+
+
+def sch_set_field(path: Path, reference: str, field_name: str, new_value: str) -> int:
+    """Set a field on every unit of a schematic symbol. Returns units changed."""
+    root = load(path)
+    changed = 0
+    for symbol in find_all(root, "symbol"):
+        if value(symbol, "lib_id") is None:
+            continue
+        ref = prop(symbol, "Reference")
+        if ref != reference:
+            instances = find(symbol, "instances")
+            refs = (
+                [str(value(p, "reference")) for p in sexpr.walk(instances, "path")]
+                if instances
+                else []
+            )
+            if reference not in refs:
+                continue
+        set_prop(symbol, field_name, new_value)
+        if field_name == "Reference":
+            instances = find(symbol, "instances")
+            if instances is not None:
+                for path_node in sexpr.walk(instances, "path"):
+                    ref_node = find(path_node, "reference")
+                    if ref_node is not None:
+                        ref_node[1] = new_value
+        changed += 1
+    if not changed:
+        raise EditError(f"no symbol with reference {reference!r} in {path.name}")
+    save(path, root)
+    return changed
+
+
+# --------------------------------------------------------------------------- board
+
+
+def pcb_place(
+    path: Path, reference: str, x: float, y: float, rotation: float | None = None
+) -> dict:
+    """Move (and optionally rotate) a footprint. Pads and texts rotate with it."""
+    root = load(path)
+    footprint = footprints(root).get(reference)
+    if footprint is None:
+        raise EditError(f"no footprint {reference!r} on the board")
+    at = find(footprint, "at")
+    if at is None:
+        at = [Sym("at"), Sym("0"), Sym("0")]
+        footprint.insert(2, at)
+    old_angle = num(at[3]) if len(at) > 3 else 0.0
+    new_angle = old_angle if rotation is None else rotation % 360
+    delta = (new_angle - old_angle) % 360
+    at[1:] = [fmt(x), fmt(y)] + ([fmt(new_angle)] if new_angle else [])
+    if delta:
+        for child in footprint:
+            if isinstance(child, list) and child and child[0] in {"pad", "fp_text", "property"}:
+                child_at = find(child, "at")
+                if child_at is None:
+                    continue
+                base = num(child_at[3]) if len(child_at) > 3 else 0.0
+                del child_at[3:]
+                angle = (base + delta) % 360
+                if angle:
+                    child_at.append(fmt(angle))
+    save(path, root)
+    return {"reference": reference, "x": x, "y": y, "rotation": new_angle}
+
+
+def pcb_add_track(
+    path: Path,
+    net: str,
+    points: list[tuple[float, float]],
+    layer: str = "F.Cu",
+    width: float = 0.25,
+) -> int:
+    if len(points) < 2:
+        raise EditError("a track needs at least two points")
+    root = load(path)
+    codes = net_codes(root)
+    if net not in codes:
+        raise EditError(f"net {net!r} does not exist on the board (nets: {sorted(codes)[:40]})")
+    stamp = _stamp_key(root)
+    added = 0
+    for (x1, y1), (x2, y2) in zip(points, points[1:]):
+        if (x1, y1) == (x2, y2):
+            continue
+        root.append(
+            [
+                Sym("segment"),
+                [Sym("start"), fmt(x1), fmt(y1)],
+                [Sym("end"), fmt(x2), fmt(y2)],
+                [Sym("width"), fmt(width)],
+                [Sym("layer"), layer],
+                _net_node(root, net),
+                [Sym(stamp), _new_uuid()],
+            ]
+        )
+        added += 1
+    save(path, root)
+    return added
+
+
+def pcb_add_via(
+    path: Path, net: str, x: float, y: float, size: float = 0.6, drill: float = 0.3
+) -> None:
+    root = load(path)
+    codes = net_codes(root)
+    if net not in codes:
+        raise EditError(f"net {net!r} does not exist on the board")
+    root.append(
+        [
+            Sym("via"),
+            [Sym("at"), fmt(x), fmt(y)],
+            [Sym("size"), fmt(size)],
+            [Sym("drill"), fmt(drill)],
+            [Sym("layers"), "F.Cu", "B.Cu"],
+            _net_node(root, net),
+            [Sym(_stamp_key(root)), _new_uuid()],
+        ]
+    )
+    save(path, root)
+
+
+def pcb_remove_routing(path: Path, net: str | None = None) -> int:
+    """Delete tracks and vias (for one net, or all). Returns the number removed."""
+    root = load(path)
+    codes = net_codes(root)
+    if net and net not in codes:
+        raise EditError(f"net {net!r} does not exist on the board")
+    keep: Node = []
+    removed = 0
+    for child in root:
+        if isinstance(child, list) and child and child[0] in {"segment", "via", "arc"}:
+            if net is None or _item_net(root, child, codes) == net:
+                removed += 1
+                continue
+        keep.append(child)
+    save(path, keep)
+    return removed
+
+
+def pcb_set_outline(path: Path, x: float, y: float, width: float, height: float) -> None:
+    """Replace the Edge.Cuts outline with a rectangle."""
+    root = load(path)
+    kept = [
+        c
+        for c in root
+        if not (
+            isinstance(c, list)
+            and c
+            and str(c[0]).startswith("gr_")
+            and value(c, "layer") == "Edge.Cuts"
+        )
+    ]
+    kept.append(
+        [
+            Sym("gr_rect"),
+            [Sym("start"), fmt(x), fmt(y)],
+            [Sym("end"), fmt(x + width), fmt(y + height)],
+            [Sym("stroke"), [Sym("width"), Sym("0.1")], [Sym("type"), Sym("default")]],
+            [Sym("fill"), Sym("none")],
+            [Sym("layer"), "Edge.Cuts"],
+            [Sym(_stamp_key(root)), _new_uuid()],
+        ]
+    )
+    save(path, kept)
+
+
+def pcb_add_zone(
+    path: Path,
+    net: str,
+    layer: str,
+    polygon: list[tuple[float, float]] | None = None,
+    clearance: float = 0.3,
+    min_thickness: float = 0.25,
+) -> None:
+    """Add a copper pour. Without a polygon it covers the board outline."""
+    from traceforge.kicad.pcb import read_board
+
+    root = load(path)
+    codes = net_codes(root)
+    if net not in codes:
+        raise EditError(f"net {net!r} does not exist on the board")
+    if polygon is None:
+        outline = read_board(path).outline
+        if outline is None:
+            raise EditError("the board has no Edge.Cuts outline; pass a polygon")
+        x0, y0, x1, y1 = outline
+        polygon = [(x0, y0), (x1, y0), (x1, y1), (x0, y1)]
+    net_node = _net_node(root, net)
+    root.append(
+        [
+            Sym("zone"),
+            net_node,
+            *([[Sym("net_name"), net]] if isinstance(net_node[1], Sym) else []),
+            [Sym("layer"), layer],
+            [Sym(_stamp_key(root)), _new_uuid()],
+            [Sym("hatch"), Sym("edge"), Sym("0.5")],
+            [Sym("connect_pads"), [Sym("clearance"), fmt(clearance)]],
+            [Sym("min_thickness"), fmt(min_thickness)],
+            [Sym("filled_areas_thickness"), Sym("no")],
+            [
+                Sym("fill"),
+                Sym("yes"),
+                [Sym("thermal_gap"), Sym("0.5")],
+                [Sym("thermal_bridge_width"), Sym("0.5")],
+            ],
+            [Sym("polygon"), [Sym("pts"), *[[Sym("xy"), fmt(px), fmt(py)] for px, py in polygon]]],
+        ]
+    )
+    save(path, root)
+
+
+def fill_zones(path: Path) -> bool:
+    """Fill zones with KiCad's own filler (needs a Python that can import pcbnew)."""
+    import os
+    import subprocess
+
+    from traceforge.kicad.cli import find_kicad_python
+
+    python = find_kicad_python()
+    if python is None:
+        return False
+    script = (
+        "import sys, pcbnew\n"
+        "b = pcbnew.LoadBoard(sys.argv[1])\n"
+        "pcbnew.ZONE_FILLER(b).Fill(b.Zones())\n"
+        "pcbnew.SaveBoard(sys.argv[1], b)\n"
+    )
+    completed = subprocess.run(  # noqa: S603
+        [python, "-c", script, str(Path(path).resolve())],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=600,
+        env={**os.environ, "QT_QPA_PLATFORM": "offscreen"},
+        check=False,
+    )
+    return completed.returncode == 0
+
+
+def pcb_add_routing(
+    path: Path,
+    tracks: list[tuple[str, str, float, list[tuple[float, float]]]],
+    vias: list[tuple[str, float, float]],
+    via_size: float = 0.6,
+    via_drill: float = 0.3,
+) -> int:
+    """Add many tracks ``(net, layer, width, points)`` and vias ``(net, x, y)`` in one write."""
+    root = load(path)
+    codes = net_codes(root)
+    stamp = _stamp_key(root)
+    for net in {t[0] for t in tracks} | {v[0] for v in vias}:
+        if net not in codes:
+            raise EditError(f"net {net!r} does not exist on the board")
+    added = 0
+    for net, layer, width, points in tracks:
+        for (x1, y1), (x2, y2) in zip(points, points[1:]):
+            if (x1, y1) == (x2, y2):
+                continue
+            root.append(
+                [
+                    Sym("segment"),
+                    [Sym("start"), fmt(x1), fmt(y1)],
+                    [Sym("end"), fmt(x2), fmt(y2)],
+                    [Sym("width"), fmt(width)],
+                    [Sym("layer"), layer],
+                    [Sym("net"), Sym(str(codes[net]))],
+                    [Sym(stamp), _new_uuid()],
+                ]
+            )
+            added += 1
+    for net, x, y in vias:
+        root.append(
+            [
+                Sym("via"),
+                [Sym("at"), fmt(x), fmt(y)],
+                [Sym("size"), fmt(via_size)],
+                [Sym("drill"), fmt(via_drill)],
+                [Sym("layers"), "F.Cu", "B.Cu"],
+                [Sym("net"), Sym(str(codes[net]))],
+                [Sym(stamp), _new_uuid()],
+            ]
+        )
+    save(path, root)
+    return added
+
+
+def pcb_set_pad_zone_connect(path: Path, pads: list[tuple[str, str]], mode: int = 2) -> int:
+    """Override how zones connect to the given ``(reference, pad number)`` pads.
+
+    ``mode`` follows KiCad: 0 none, 1 thermal relief, 2 solid. Returns the pads changed.
+    """
+    wanted = {(str(r), str(n)) for r, n in pads}
+    if not wanted:
+        return 0
+    root = load(path)
+    changed = 0
+    for ref, fp in footprints(root).items():
+        for pad in find_all(fp, "pad"):
+            if (ref, str(pad[1])) not in wanted:
+                continue
+            existing = find(pad, "zone_connect")
+            if existing is not None:
+                existing[1] = Sym(str(mode))
+            else:
+                pad.append([Sym("zone_connect"), Sym(str(mode))])
+            changed += 1
+    save(path, root)
+    return changed