traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/altium/schematic.py

@@ -0,0 +1,400 @@
+"""Altium ``.SchDoc`` parser and connectivity extraction (nets from wires, pins and labels)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge.altium.cfb import AltiumError, length_prefixed, open_cfb, parse_properties
+
+SCALE = 100000  # coordinates are 10 mil units with a 1e-5 fraction
+MM_PER_UNIT = 0.254
+ELECTRICAL = {
+    0: "input",
+    1: "bidirectional",
+    2: "output",
+    3: "open_collector",
+    4: "passive",
+    5: "tri_state",
+    6: "open_emitter",
+    7: "power",
+}
+_DIRS = {0: (1, 0), 1: (0, 1), 2: (-1, 0), 3: (0, -1)}
+
+Point = tuple[int, int]
+
+
+def _int(props: dict[str, str], key: str, default: int = 0) -> int:
+    try:
+        return int(float(props.get(key, default)))
+    except ValueError:
+        return default
+
+
+def _pt(props: dict[str, str], prefix: str = "LOCATION.") -> Point:
+    def axis(a: str) -> int:
+        base = _int(props, f"{prefix}{a}")
+        return base * SCALE + _int(props, f"{prefix}{a}_FRAC")
+
+    return (axis("X"), axis("Y"))
+
+
+def _flag(props: dict[str, str], key: str) -> bool:
+    return props.get(key, "").upper() == "T"
+
+
+def natural_key(text: str):
+    return [int(p) if p.isdigit() else p for p in re.split(r"(\d+)", text)]
+
+
+@dataclass
+class AltPin:
+    number: str
+    name: str
+    electrical: str
+    x: float  # connection (hot) end, mm
+    y: float
+    hidden: bool = False
+    part: int = -1
+    point: Point = (0, 0)
+
+
+@dataclass
+class AltComponent:
+    designator: str
+    comment: str = ""
+    description: str = ""
+    lib_ref: str = ""
+    footprint: str = ""
+    params: dict[str, str] = field(default_factory=dict)
+    pins: list[AltPin] = field(default_factory=list)
+    sheet: str = ""
+    x: float = 0.0
+    y: float = 0.0
+    part_count: int = 1
+
+    def pin(self, number: str) -> AltPin | None:
+        for p in self.pins:
+            if p.number == str(number):
+                return p
+        return None
+
+    @property
+    def is_power(self) -> bool:
+        return self.designator.startswith("#")
+
+
+@dataclass
+class SheetSymbol:
+    name: str
+    file: str
+    entries: list[tuple[str, Point]] = field(default_factory=list)
+    point: Point = (0, 0)
+
+
+@dataclass
+class AltSheet:
+    path: Path
+    title: str = ""
+    components: list[AltComponent] = field(default_factory=list)
+    wires: list[list[Point]] = field(default_factory=list)
+    junctions: list[Point] = field(default_factory=list)
+    net_labels: list[tuple[str, Point]] = field(default_factory=list)
+    power_ports: list[tuple[str, Point]] = field(default_factory=list)
+    ports: list[tuple[str, Point]] = field(default_factory=list)
+    sheet_symbols: list[SheetSymbol] = field(default_factory=list)
+    no_erc: int = 0
+
+    @property
+    def name(self) -> str:
+        return self.path.name
+
+
+def parse_sheet(path: str | Path) -> AltSheet:
+    path = Path(path)
+    ole = open_cfb(path)
+    try:
+        if not ole.exists(["FileHeader"]):
+            raise AltiumError(f"{path.name}: no FileHeader stream (not a schematic document)")
+        data = ole.openstream(["FileHeader"]).read()
+    finally:
+        ole.close()
+    records = [parse_properties(p) for flag, p in length_prefixed(data) if flag == 0]
+    if not records or "HEADER" not in records[0]:
+        raise AltiumError(f"{path.name}: unexpected schematic header")
+    body = records[1:]  # OwnerIndex counts from the first record after the header
+    sheet = AltSheet(path=path)
+
+    owned: dict[int, list[tuple[int, dict[str, str]]]] = {}
+    for i, r in enumerate(body):
+        if "OWNERINDEX" in r:
+            owned.setdefault(_int(r, "OWNERINDEX"), []).append((i, r))
+
+    comps: dict[int, AltComponent] = {}
+    for i, r in enumerate(body):
+        if r.get("RECORD") != "1":
+            continue
+        x, y = _pt(r)
+        comp = AltComponent(
+            designator="",
+            lib_ref=r.get("DESIGNITEMID") or r.get("LIBREFERENCE", ""),
+            description=r.get("COMPONENTDESCRIPTION", ""),
+            sheet=path.name,
+            x=x / SCALE * MM_PER_UNIT,
+            y=y / SCALE * MM_PER_UNIT,
+            part_count=_int(r, "PARTCOUNT", 1),
+        )
+        comp.params["_part"] = r.get("CURRENTPARTID", "1")
+        comps[i] = comp
+    for i, comp in comps.items():
+        current = _int(body[i], "CURRENTPARTID", 1)
+        mode = _int(body[i], "CURRENTPARTDISPLAYMODE", 0)
+        for j, r in owned.get(i, []):
+            kind = r.get("RECORD")
+            if kind == "34":
+                comp.designator = r.get("TEXT", "")
+            elif kind == "41":
+                name = r.get("NAME", "")
+                if name and name != "CurrentTime":
+                    comp.params[name] = r.get("TEXT", "")
+            elif kind == "2":
+                part = _int(r, "OWNERPARTID", -1)
+                if part not in (-1, current) or _int(r, "OWNERPARTDISPLAYMODE", 0) != mode:
+                    continue
+                conglomerate = _int(r, "PINCONGLOMERATE")
+                dx, dy = _DIRS[conglomerate & 3]
+                length = _int(r, "PINLENGTH") * SCALE + _int(r, "PINLENGTH_FRAC")
+                px, py = _pt(r)
+                hot = (px + dx * length, py + dy * length)
+                comp.pins.append(
+                    AltPin(
+                        number=r.get("DESIGNATOR", ""),
+                        name=r.get("NAME", ""),
+                        electrical=ELECTRICAL.get(_int(r, "ELECTRICAL"), "passive"),
+                        x=hot[0] / SCALE * MM_PER_UNIT,
+                        y=hot[1] / SCALE * MM_PER_UNIT,
+                        hidden=_flag(r, "HIDDEN"),
+                        part=part,
+                        point=hot,
+                    )
+                )
+            elif kind == "44":  # implementation list: footprints hang below it
+                for _, impl in owned.get(j, []):
+                    if impl.get("RECORD") == "45" and impl.get("MODELTYPE") == "PCBLIB":
+                        if not comp.footprint or _flag(impl, "ISCURRENT"):
+                            comp.footprint = impl.get("MODELNAME", "")
+        comp.comment = _resolve(comp.params.get("Comment", ""), comp.params) or comp.lib_ref
+        comp.description = comp.description or comp.params.get("Description", "")
+        sheet.components.append(comp)
+
+    symbols: dict[int, SheetSymbol] = {}
+    for i, r in enumerate(body):
+        kind = r.get("RECORD")
+        if kind == "27":
+            n = _int(r, "LOCATIONCOUNT")
+            sheet.wires.append(
+                [
+                    (_int(r, f"X{k}") * SCALE + _int(r, f"X{k}_FRAC"),)
+                    + (_int(r, f"Y{k}") * SCALE + _int(r, f"Y{k}_FRAC"),)
+                    for k in range(1, n + 1)
+                ]  # noqa: E501
+            )
+        elif kind == "29":
+            sheet.junctions.append(_pt(r))
+        elif kind == "25":
+            sheet.net_labels.append((r.get("TEXT", ""), _pt(r)))
+        elif kind == "17":
+            sheet.power_ports.append((r.get("TEXT", ""), _pt(r)))
+        elif kind == "18":
+            sheet.ports.append((r.get("NAME", ""), _pt(r)))
+        elif kind == "22":
+            sheet.no_erc += 1
+        elif kind == "15":
+            symbols[i] = SheetSymbol(name="", file="", point=_pt(r))
+    for r in body:
+        kind = r.get("RECORD")
+        owner = _int(r, "OWNERINDEX", -1)
+        if owner in symbols:
+            if kind == "32":
+                symbols[owner].name = r.get("TEXT", "")
+            elif kind == "33":
+                symbols[owner].file = r.get("TEXT", "")
+            elif kind == "16":
+                sym = symbols[owner]
+                sx, sy = sym.point
+                w = _int(r, "DISTANCEFROMTOP") * SCALE + _int(r, "DISTANCEFROMTOP_FRAC")
+                side = _int(r, "SIDE")
+                # Sheet symbol origin is its top-left corner; entries sit on an edge.
+                size_x = _int(body[owner], "XSIZE") * SCALE
+                if side == 0:
+                    pos = (sx, sy - w)
+                elif side == 1:
+                    pos = (sx + size_x, sy - w)
+                else:
+                    pos = (sx + w, sy)
+                sym.entries.append((r.get("NAME", ""), pos))
+    sheet.sheet_symbols = list(symbols.values())
+    return sheet
+
+
+def _resolve(text: str, params: dict[str, str]) -> str:
+    """Comment values may be ``=ParameterName`` references."""
+    if text.startswith("="):
+        return params.get(text[1:], "")
+    return text
+
+
+# --- connectivity -----------------------------------------------------------------
+
+
+class _UF:
+    def __init__(self) -> None:
+        self.p: dict = {}
+
+    def find(self, a):
+        self.p.setdefault(a, a)
+        while self.p[a] != a:
+            self.p[a] = self.p[self.p[a]]
+            a = self.p[a]
+        return a
+
+    def union(self, a, b) -> None:
+        ra, rb = self.find(a), self.find(b)
+        if ra != rb:
+            self.p[rb] = ra
+
+
+def _on_segment(p: Point, a: Point, b: Point) -> bool:
+    (px, py), (ax, ay), (bx, by) = p, a, b
+    if (bx - ax) * (py - ay) - (by - ay) * (px - ax) != 0:
+        return False
+    return min(ax, bx) <= px <= max(ax, bx) and min(ay, by) <= py <= max(ay, by)
+
+
+@dataclass
+class Netlist:
+    nets: dict[str, list[tuple[str, str]]]  # name -> [(designator, pin number)]
+    warnings: list[str] = field(default_factory=list)
+
+
+def extract_nets(sheets: list[AltSheet], hierarchy: bool | None = None) -> Netlist:
+    """Union-find over wire geometry, labels, ports and power ports.
+
+    Power ports are global. Without sheet symbols (flat project) net labels and ports connect
+    across sheets by name; with sheet symbols, net labels are local to their sheet and ports
+    connect through sheet entries (the same sheet file used twice is read once) (a sheet file used twice is read once).
+    """
+    uf = _UF()
+    pin_node: dict[tuple[str, str], tuple] = {}
+    warnings: list[str] = []
+    by_file = {s.path.name.lower(): s for s in sheets}
+    if hierarchy is None:
+        hierarchy = any(s.sheet_symbols for s in sheets)
+    soft: list[
+        tuple[tuple, str]
+    ] = []  # port / sheet entry names: used when nothing else names a net
+    for sheet in sheets:
+        sid = sheet.path.name.lower()
+        points: dict[Point, list] = {}
+        wire_nodes: list[tuple[tuple, list[Point]]] = []
+
+        def add(point: Point, node, points=points) -> None:
+            points.setdefault(point, []).append(node)
+
+        for wi, wire in enumerate(sheet.wires):
+            node = ("wire", sid, wi)
+            uf.find(node)
+            wire_nodes.append((node, wire))
+            for pt in wire:
+                add(pt, node)
+        for comp in sheet.components:
+            if comp.is_power:
+                continue
+            for pin in comp.pins:
+                node = ("pin", comp.designator, pin.number)
+                uf.find(node)
+                pin_node[(comp.designator, pin.number)] = node
+                add(pin.point, node)
+                if pin.hidden and pin.name:
+                    uf.union(node, ("name", "g", pin.name))
+        for text, pt in sheet.net_labels:
+            node = ("label", sid, text, pt)
+            add(pt, node)
+            uf.union(node, ("name", sid if hierarchy else "g", text))
+        for text, pt in sheet.power_ports:
+            node = ("power", sid, text, pt)
+            add(pt, node)
+            uf.union(node, ("name", "g", text))
+            uf.union(("name", sid, text), ("name", "g", text))  # same-named labels on this sheet
+        for text, pt in sheet.ports:
+            node = ("port", sid, text, pt)
+            add(pt, node)
+            soft.append((node, text))
+            if not hierarchy:
+                uf.union(node, ("name", "g", text))
+                uf.union(("name", sid, text), ("name", "g", text))
+            else:
+                uf.union(node, ("port", sid, text))
+        for si, sym in enumerate(sheet.sheet_symbols):
+            for ename, pt in sym.entries:
+                node = ("entry", sid, si, ename)
+                add(pt, node)
+                soft.append((node, ename))
+                target = by_file.get(Path(sym.file.replace("\\", "/")).name.lower())
+                if target is None:
+                    warnings.append(f"sheet symbol {sym.name!r}: file {sym.file!r} not loaded")
+                else:
+                    uf.union(node, ("port", target.path.name.lower(), ename))
+        for nodes in points.values():
+            for other in nodes[1:]:
+                uf.union(nodes[0], other)
+        junctions = set(sheet.junctions)
+        for jpt in junctions:  # a junction joins every wire passing through or ending on it
+            first = None
+            for wnode, wire in wire_nodes:
+                if any(_on_segment(jpt, a, b) for a, b in zip(wire, wire[1:])):
+                    if first is None:
+                        first = wnode
+                    else:
+                        uf.union(first, wnode)
+        for wnode, wire in wire_nodes:
+            for a, b in zip(wire, wire[1:]):
+                for pt, nodes in points.items():
+                    if pt in (a, b) or not _on_segment(pt, a, b):
+                        continue
+                    for other in nodes:
+                        # A wire ending on another wire's side needs a junction; anything
+                        # else (pin, label, port) on a wire is connected to it.
+                        if other[0] != "wire" or pt in junctions:
+                            uf.union(wnode, other)
+    groups: dict = {}
+    for key in pin_node:
+        groups.setdefault(uf.find(pin_node[key]), []).append(key)
+    named: dict = {}
+    for node in list(uf.p):
+        if node[0] == "name":
+            named.setdefault(uf.find(node), []).append(node)
+    soft_names: dict = {}
+    for node, text in sorted(soft, key=lambda item: item[1]):
+        soft_names.setdefault(uf.find(node), text)
+    nets: dict[str, list[tuple[str, str]]] = {}
+    for root, pins in groups.items():
+        label = sorted(named.get(root, []), key=lambda n: (n[1] != "g", n[2] if len(n) > 2 else ""))
+        if label:
+            name = label[0][2]
+            if label[0][1] != "g" and len({sh for sh in (n[1] for n in label)}) > 1:
+                name = label[0][2]
+        elif root in soft_names:
+            name = soft_names[root]
+        elif len(pins) < 2:
+            continue  # an unconnected pin is not a net
+        else:
+            first = sorted(pins, key=lambda k: (natural_key(k[0]), natural_key(k[1])))[0]
+            name = f"Net{first[0]}_{first[1]}"
+        base, n = name, 2
+        while name in nets:
+            name = f"{base}_{n}"
+            n += 1
+        nets[name] = sorted(pins, key=lambda k: (natural_key(k[0]), natural_key(k[1])))
+    return Netlist(nets=dict(sorted(nets.items())), warnings=warnings)

traceforge/altium/tools.py

@@ -0,0 +1,166 @@
+"""Agent tools for Altium projects."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from traceforge.tools.base import Tool, ToolContext, ToolError, ToolKind
+
+
+def load_for_tool(args: dict[str, Any], ctx: ToolContext):
+    from traceforge.altium import AltiumError, load_project
+
+    raw = args.get("project")
+    path = ctx.resolve(raw, must_exist=True) if raw else ctx.workspace
+    try:
+        return load_project(path)
+    except AltiumError as exc:
+        raise ToolError(str(exc)) from exc
+
+
+def altium_project(args: dict[str, Any], ctx: ToolContext) -> dict:
+    return load_for_tool(args, ctx).summary()
+
+
+def altium_connections(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.altium.project import clean_pin_name
+
+    project = load_for_tool(args, ctx)
+    comps = project.components()
+    out: dict[str, Any] = {}
+
+    def pin_info(ref: str, number: str) -> dict:
+        found = project.find_pin(ref, number)
+        if found is None:
+            raise ToolError(f"{ref} has no pin {number!r}")
+        comp, pin = found
+        net = project.net_of(ref, pin.number)
+        info = {
+            "pin": f"{ref}.{pin.number}",
+            "name": clean_pin_name(pin.name),
+            "type": pin.electrical,
+            "part": f"{comp.comment} ({comp.footprint})",
+            "net": net or "(unconnected)",
+        }
+        if net:
+            info["connected_to"] = [
+                f"{r}.{n}" for r, n in project.netlist.nets[net] if (r, n) != (ref, pin.number)
+            ]
+        return info
+
+    if args.get("pin"):
+        ref, _, number = str(args["pin"]).partition(".")
+        out.update(pin_info(ref, number))
+    if args.get("part"):
+        ref = str(args["part"])
+        comp = comps.get(ref)
+        if comp is None:
+            raise ToolError(f"no part {ref!r}")
+        out["part"] = {
+            "ref": ref,
+            "value": comp.comment,
+            "footprint": comp.footprint,
+            "pins": [
+                {
+                    "pin": p.number,
+                    "name": clean_pin_name(p.name),
+                    "type": p.electrical,
+                    "net": project.net_of(ref, p.number) or "(unconnected)",
+                }
+                for p in sorted(comp.pins, key=lambda p: (len(p.number), p.number))
+            ],
+        }
+    if args.get("net"):
+        name = str(args["net"])
+        pins = project.netlist.nets.get(name)
+        if pins is None:
+            raise ToolError(f"no net {name!r}; nets: {', '.join(list(project.netlist.nets)[:40])}")
+        out["net"] = {"name": name, "pins": [f"{r}.{n}" for r, n in pins]}
+    if not out:
+        raise ToolError("give pin='U1.14', part='U1' or net='GND'")
+    return out
+
+
+def altium_bom(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.altium.project import bom_rows
+
+    return {"rows": bom_rows(load_for_tool(args, ctx))}
+
+
+def altium_review(args: dict[str, Any], ctx: ToolContext) -> dict:
+    """Run the built-in schematic and schematic-vs-board checks on the converted models."""
+    from traceforge import checks
+    from traceforge.altium.model import to_board, to_schematic
+
+    project = load_for_tool(args, ctx)
+    schematic = to_schematic(project)
+    findings = checks.schematic_checks(schematic)
+    board = to_board(project)
+    if board is not None:
+        findings += checks.parity_checks(schematic, board)
+    return {"project": project.name, **checks.summarize(findings)}
+
+
+def altium_convert(args: dict[str, Any], ctx: ToolContext) -> dict:
+    from traceforge.altium.outputs import convert
+
+    project = load_for_tool(args, ctx)
+    out = ctx.resolve(args.get("out_dir") or "outputs/altium", for_write=True)
+    return convert(project, out)
+
+
+_PROJECT = {"project": {"type": "string", "description": "a .PrjPcb, .SchDoc or folder"}}
+
+ALTIUM_TOOLS = [
+    Tool(
+        "altium_project",
+        "Overview of an Altium Designer / CircuitMaker project (.PrjPcb, .SchDoc, .PcbDoc): "
+        "sheets, parts, pins, nets, board layers, tracks, vias, outline. Use it when the "
+        "workspace has Altium files instead of KiCad.",
+        {"type": "object", "properties": _PROJECT},
+        altium_project,
+        ToolKind.READ,
+    ),
+    Tool(
+        "altium_connections",
+        "Connectivity of an Altium project: pin='U1.14' -> name, type, net and the other pins "
+        "on it; part='U1' -> every pin with its net; net='GND' -> its pins.",
+        {
+            "type": "object",
+            "properties": {
+                **_PROJECT,
+                "pin": {"type": "string"},
+                "part": {"type": "string"},
+                "net": {"type": "string"},
+            },
+        },
+        altium_connections,
+        ToolKind.READ,
+    ),
+    Tool(
+        "altium_bom",
+        "Bill of materials of an Altium project, identical parts grouped, with MPN and LCSC "
+        "numbers from the component parameters.",
+        {"type": "object", "properties": _PROJECT},
+        altium_bom,
+        ToolKind.READ,
+    ),
+    Tool(
+        "altium_review",
+        "Built-in checks (annotation, power, labels, schematic-vs-board parity) on an Altium "
+        "project.",
+        {"type": "object", "properties": _PROJECT},
+        altium_review,
+        ToolKind.READ,
+    ),
+    Tool(
+        "altium_convert",
+        "Write a KiCad netlist (.net) and BOM (.csv) from an Altium project.",
+        {
+            "type": "object",
+            "properties": {**_PROJECT, "out_dir": {"type": "string"}},
+        },
+        altium_convert,
+        ToolKind.WRITE,
+    ),
+]