traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/altium/project.py

@@ -0,0 +1,328 @@
+"""Altium projects (``.PrjPcb``): load sheets and board, netlist, BOM, KiCad-side models."""
+
+from __future__ import annotations
+
+import csv
+import io
+import re
+from dataclasses import dataclass, field
+from datetime import date
+from pathlib import Path
+
+from traceforge.altium.cfb import AltiumError
+from traceforge.altium.pcb import AltPcb, parse_pcb
+from traceforge.altium.schematic import (
+    AltComponent,
+    AltPin,
+    AltSheet,
+    Netlist,
+    extract_nets,
+    natural_key,
+    parse_sheet,
+)
+
+_SKIP = {".git", "node_modules", "__pycache__", ".traceforge", "History"}
+
+
+def clean_pin_name(name: str) -> str:
+    """Altium marks overbars with a backslash after each barred character (``R\\S\\T\\``)."""
+    out: list[str] = []
+    barred: list[str] = []
+    i = 0
+    while i < len(name):
+        ch = name[i]
+        if i + 1 < len(name) and name[i + 1] == "\\":
+            barred.append(ch)
+            i += 2
+            continue
+        if barred:
+            out.append("~{" + "".join(barred) + "}")
+            barred = []
+        out.append(ch)
+        i += 1
+    if barred:
+        out.append("~{" + "".join(barred) + "}")
+    return "".join(out)
+
+
+def _alias(params: dict[str, str], pattern: str) -> str:
+    for key, val in params.items():
+        if val and re.search(pattern, key, re.I):
+            return val
+    return ""
+
+
+@dataclass
+class AltiumProject:
+    root: Path
+    prjpcb: Path | None
+    sheets: list[AltSheet] = field(default_factory=list)
+    pcb: AltPcb | None = None
+    netlist: Netlist = field(default_factory=lambda: Netlist({}))
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return (self.prjpcb or self.root).stem
+
+    def components(self) -> dict[str, AltComponent]:
+        """Real parts by designator; parts split over several placed symbols are merged."""
+        merged: dict[str, AltComponent] = {}
+        for sheet in self.sheets:
+            for comp in sheet.components:
+                if comp.is_power or not comp.designator.strip("*") or comp.designator.endswith("?"):
+                    continue
+                known = merged.get(comp.designator)
+                if known is None:
+                    merged[comp.designator] = AltComponent(
+                        **{**comp.__dict__, "pins": list(comp.pins), "params": dict(comp.params)}
+                    )
+                else:
+                    have = {p.number for p in known.pins}
+                    known.pins.extend(p for p in comp.pins if p.number not in have)
+        return dict(sorted(merged.items(), key=lambda kv: natural_key(kv[0])))
+
+    def find_pin(self, designator: str, number: str) -> tuple[AltComponent, AltPin] | None:
+        comp = self.components().get(designator)
+        if comp is None:
+            return None
+        pin = comp.pin(number)
+        if pin is None:
+            for p in comp.pins:
+                if clean_pin_name(p.name).lower() == number.lower():
+                    pin = p
+                    break
+        return (comp, pin) if pin else None
+
+    def net_of(self, designator: str, number: str) -> str | None:
+        for name, pins in self.netlist.nets.items():
+            if (designator, number) in pins:
+                return name
+        return None
+
+    def summary(self) -> dict:
+        comps = self.components()
+        out: dict = {
+            "project": self.name,
+            "prjpcb": self.prjpcb.name if self.prjpcb else None,
+            "sheets": [s.name for s in self.sheets],
+            "components": len(comps),
+            "pins": sum(len(c.pins) for c in comps.values()),
+            "nets": len(self.netlist.nets),
+            "wires": sum(len(s.wires) for s in self.sheets),
+            "net_labels": sum(len(s.net_labels) for s in self.sheets),
+            "power_ports": sum(len(s.power_ports) for s in self.sheets),
+            "warnings": self.warnings + self.netlist.warnings,
+        }
+        if self.pcb:
+            p = self.pcb
+            box = p.outline_bbox()
+            out["pcb"] = {
+                "file": p.path.name,
+                "components": len(p.components),
+                "pads": sum(len(c.pads) for c in p.components) + len(p.free_pads),
+                "nets": len(p.nets),
+                "tracks": len(p.tracks),
+                "tracks_per_layer": p.tracks_per_layer(),
+                "vias": len(p.vias),
+                "layers": p.layers,
+                "outline_mm": [round(v, 3) for v in box] if box else None,
+            }
+        return out
+
+
+def _find(root: Path, suffixes: set[str], depth: int = 4) -> list[Path]:
+    found: list[Path] = []
+    stack = [(root, 0)]
+    while stack:
+        d, n = stack.pop()
+        try:
+            entries = sorted(d.iterdir())
+        except OSError:
+            continue
+        for e in entries:
+            if e.is_dir():
+                if n < depth and e.name not in _SKIP and not e.name.startswith("."):
+                    stack.append((e, n + 1))
+            elif e.suffix.lower() in suffixes:
+                found.append(e)
+    return sorted(found, key=lambda p: (len(p.parts), str(p)))
+
+
+def find_projects(root: str | Path) -> list[Path]:
+    return _find(Path(root), {".prjpcb"})
+
+
+def project_documents(prjpcb: Path) -> list[Path]:
+    """``DocumentPath`` entries of the INI-style ``.PrjPcb``, resolved against its folder."""
+    docs: list[Path] = []
+    text = prjpcb.read_text(encoding="utf-8", errors="replace")
+    for line in text.splitlines():
+        if line.lower().startswith("documentpath="):
+            rel = line.split("=", 1)[1].strip().replace("\\", "/")
+            path = (prjpcb.parent / rel).resolve()
+            if path.exists():
+                docs.append(path)
+            else:  # tolerate case differences on case-sensitive systems
+                match = next(
+                    (
+                        p
+                        for p in prjpcb.parent.rglob("*")
+                        if p.name.lower() == Path(rel).name.lower()
+                    ),
+                    None,
+                )
+                if match:
+                    docs.append(match)
+    return docs
+
+
+def load_project(path: str | Path) -> AltiumProject:
+    """Load a ``.PrjPcb`` (or a folder / loose ``.SchDoc`` / ``.PcbDoc`` files)."""
+    path = Path(path).resolve()
+    if not path.exists():
+        raise AltiumError(f"{path} does not exist")
+    warnings: list[str] = []
+    prjpcb: Path | None = None
+    if path.is_file() and path.suffix.lower() == ".prjpcb":
+        prjpcb = path
+    elif path.is_dir():
+        found = find_projects(path)
+        prjpcb = found[0] if found else None
+    root = prjpcb.parent if prjpcb else (path if path.is_dir() else path.parent)
+    if prjpcb:
+        docs = project_documents(prjpcb)
+    elif path.is_file():
+        docs = [path]
+    else:
+        docs = _find(root, {".schdoc", ".pcbdoc"})
+    sch_paths = [d for d in docs if d.suffix.lower() == ".schdoc"]
+    pcb_paths = [d for d in docs if d.suffix.lower() == ".pcbdoc"]
+    if path.is_file() and path.suffix.lower() == ".schdoc":
+        pcb_paths = []
+    if not sch_paths and not pcb_paths:
+        raise AltiumError(f"no .SchDoc or .PcbDoc found for {path}")
+    sheets: list[AltSheet] = []
+    for p in sch_paths:
+        try:
+            sheets.append(parse_sheet(p))
+        except AltiumError as exc:
+            warnings.append(str(exc))
+    pcb = None
+    if pcb_paths:
+        try:
+            pcb = parse_pcb(pcb_paths[0])
+        except AltiumError as exc:
+            warnings.append(str(exc))
+        if len(pcb_paths) > 1:
+            warnings.append(f"{len(pcb_paths)} boards in the project; read {pcb_paths[0].name}")
+    netlist = extract_nets(sheets) if sheets else Netlist({})
+    if not sheets and pcb:
+        netlist = Netlist(pcb.pad_nets())
+    return AltiumProject(root, prjpcb, sheets, pcb, netlist, warnings)
+
+
+# --- outputs ---------------------------------------------------------------------
+
+
+def bom_rows(project: AltiumProject) -> list[dict[str, str]]:
+    """Altium-style BOM: identical parts grouped, with MPN / LCSC when the parameters have them."""
+    groups: dict[tuple, list[AltComponent]] = {}
+    for comp in project.components().values():
+        mpn = _alias(comp.params, r"^(mpn|manufacturer.?part|mfr.?part|part.?number)")
+        lcsc = _alias(comp.params, r"lcsc")
+        key = (comp.comment, comp.footprint, comp.lib_ref, comp.description, mpn, lcsc)
+        groups.setdefault(key, []).append(comp)
+    rows = []
+    for (comment, footprint, lib_ref, description, mpn, lcsc), comps in groups.items():
+        comps.sort(key=lambda c: natural_key(c.designator))
+        rows.append(
+            {
+                "Comment": comment,
+                "Description": description,
+                "Designator": ", ".join(c.designator for c in comps),
+                "Footprint": footprint,
+                "LibRef": lib_ref,
+                "Quantity": str(len(comps)),
+                "MPN": mpn,
+                "LCSC": lcsc,
+            }
+        )
+    rows.sort(key=lambda r: natural_key(r["Designator"].split(",")[0]))
+    return rows
+
+
+def bom_csv(project: AltiumProject) -> str:
+    rows = bom_rows(project)
+    cols = ["Comment", "Description", "Designator", "Footprint", "LibRef", "Quantity"]
+    for extra in ("MPN", "LCSC"):
+        if any(r[extra] for r in rows):
+            cols.append(extra)
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=cols, extrasaction="ignore", lineterminator="\n")
+    writer.writeheader()
+    writer.writerows(rows)
+    return buf.getvalue()
+
+
+def _q(text: str) -> str:
+    return '"' + str(text).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+_KICAD_PIN_TYPE = {
+    "input": "input",
+    "output": "output",
+    "bidirectional": "bidirectional",
+    "passive": "passive",
+    "power": "power_in",
+    "tri_state": "tri_state",
+    "open_collector": "open_collector",
+    "open_emitter": "open_emitter",
+}
+
+
+def kicad_netlist(project: AltiumProject) -> str:
+    """A KiCad netlist (``.net``, export format E) that KiCad's PCB editor and our tools read.
+
+    Footprints keep their Altium names: KiCad only links them when a footprint of the same
+    name exists in its libraries (see docs/altium.md).
+    """
+    comps = project.components()
+    lines = [
+        '(export (version "E")',
+        f"  (design (source {_q(project.name)}) (date {_q(date.today().isoformat())})",
+        '    (tool "Traceforge altium"))',
+        "  (components",
+    ]
+    for ref, c in comps.items():
+        lines.append(f"    (comp (ref {_q(ref)})")
+        lines.append(f"      (value {_q(c.comment)})")
+        if c.footprint:
+            lines.append(f"      (footprint {_q(c.footprint)})")
+        lines.append(f"      (libsource (lib {_q('altium')}) (part {_q(c.lib_ref)})")
+        lines.append(f"        (description {_q(c.description)}))")
+        fields = {k: v for k, v in c.params.items() if not k.startswith("_") and v}
+        if fields:
+            lines.append("      (fields")
+            for k, v in sorted(fields.items()):
+                lines.append(f"        (field (name {_q(k)}) {_q(v)})")
+            lines.append("      )")
+        lines.append("    )")
+    lines.append("  )")
+    lines.append("  (nets")
+    for code, (name, pins) in enumerate(project.netlist.nets.items(), 1):
+        lines.append(f"    (net (code {_q(str(code))}) (name {_q(name)})")
+        for ref, number in pins:
+            comp = comps.get(ref)
+            pin = comp.pin(number) if comp else None
+            extra = ""
+            if pin:
+                extra = (
+                    f" (pinfunction {_q(clean_pin_name(pin.name))})"
+                    f" (pintype {_q(_KICAD_PIN_TYPE.get(pin.electrical, 'passive'))})"
+                )
+            lines.append(f"      (node (ref {_q(ref)}) (pin {_q(number)}){extra})")
+        lines.append("    )")
+    lines.append("  )")
+    lines.append(")")
+    return "\n".join(lines) + "\n"