traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/altium/cfb.py

@@ -0,0 +1,70 @@
+"""Read Altium files: OLE compound documents (via ``olefile``) and their record streams."""
+
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+
+class AltiumError(Exception):
+    """The file is not a readable Altium document."""
+
+
+def open_cfb(path: str | Path):
+    try:
+        import olefile
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        raise AltiumError(
+            "Reading Altium files needs the 'olefile' package: pip install 'traceforge-pcb[altium]'"
+        ) from exc
+    path = Path(path)
+    try:
+        return olefile.OleFileIO(str(path))
+    except Exception as exc:
+        raise AltiumError(f"{path.name} is not an Altium (OLE compound) document: {exc}") from exc
+
+
+def read_stream(ole, name: str) -> bytes:
+    parts = name.split("/")
+    if not ole.exists(parts):
+        raise AltiumError(f"stream {name!r} not found")
+    return ole.openstream(parts).read()
+
+
+def decode(raw: bytes) -> str:
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw.decode("cp1252", errors="replace")
+
+
+def parse_properties(raw: bytes) -> dict[str, str]:
+    """``|KEY=VALUE|KEY=VALUE`` text. Keys are upper-cased; ``%UTF8%KEY`` wins over ``KEY``."""
+    text = raw.split(b"\0", 1)[0]
+    props: dict[str, str] = {}
+    utf8: dict[str, str] = {}
+    for part in text.split(b"|"):
+        if b"=" not in part:
+            continue
+        key, _, val = part.partition(b"=")
+        name = key.decode("ascii", "replace").strip().upper()
+        if name.startswith("%UTF8%"):
+            utf8[name[6:]] = val.decode("utf-8", "replace")
+        else:
+            props.setdefault(name, decode(val))
+    props.update(utf8)
+    return props
+
+
+def length_prefixed(data: bytes, offset: int = 0):
+    """Yield (flag, payload) for ``int32 length`` records; the top byte of the length is a flag."""
+    n = len(data)
+    while offset + 4 <= n:
+        (raw,) = struct.unpack_from("<I", data, offset)
+        size = raw & 0xFFFFFF
+        flag = raw >> 24
+        offset += 4
+        if offset + size > n:
+            raise AltiumError("truncated record stream")
+        yield flag, data[offset : offset + size]
+        offset += size

traceforge/altium/cli.py

@@ -0,0 +1,60 @@
+"""``traceforge altium info|netlist|bom|convert``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def add_parser(sub) -> None:
+    p = sub.add_parser("altium", help="read Altium Designer / CircuitMaker projects")
+    p.add_argument("action", choices=["info", "netlist", "bom", "convert", "pin"])
+    p.add_argument("project", nargs="?", help=".PrjPcb, .SchDoc or folder (default: workspace)")
+    p.add_argument("--pin", help="with action 'pin': U1.14")
+    p.add_argument("--out", help="output file (netlist, bom) or folder (convert)")
+    p.add_argument("--json", action="store_true")
+
+
+def cmd_altium(args: argparse.Namespace) -> int:
+    from traceforge.altium import AltiumError, load_project
+    from traceforge.altium.outputs import convert
+    from traceforge.altium.project import bom_csv, clean_pin_name, kicad_netlist
+
+    target = Path(args.project) if args.project else Path(args.workspace)
+    try:
+        project = load_project(target)
+    except AltiumError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if args.action == "info":
+        data = project.summary()
+        print(json.dumps(data, indent=1))
+        return 0
+    if args.action == "pin":
+        ref, _, number = (args.pin or args.project or "").partition(".")
+        found = project.find_pin(ref, number)
+        if not found:
+            print(f"error: no pin {args.pin!r}", file=sys.stderr)
+            return 1
+        comp, pin = found
+        net = project.net_of(ref, pin.number)
+        print(
+            f"{ref}.{pin.number} ({clean_pin_name(pin.name)}, {pin.electrical}) of {comp.comment}: {net}"
+        )
+        if net:
+            others = [f"{r}.{n}" for r, n in project.netlist.nets[net] if (r, n) != (ref, number)]
+            print("also on this net: " + ", ".join(others))
+        return 0
+    if args.action == "convert":
+        out = args.out or "outputs/altium"
+        print(json.dumps(convert(project, out), indent=1))
+        return 0
+    text = kicad_netlist(project) if args.action == "netlist" else bom_csv(project)
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+        print(f"wrote {args.out}")
+    else:
+        sys.stdout.write(text)
+    return 0

traceforge/altium/model.py

@@ -0,0 +1,163 @@
+"""Convert an Altium project to the models Traceforge uses for KiCad designs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from traceforge.altium.project import _KICAD_PIN_TYPE, AltiumProject, _alias, clean_pin_name
+from traceforge.kicad.pcb import Board, Footprint, Pad, Track, Via
+from traceforge.kicad.schematic import Schematic, SchLabel, SchSymbol
+from traceforge.validate.netmodel import DesignModel, Part, PinDef, SymbolInfo
+
+
+def part_fields(params: dict[str, str]) -> dict[str, str]:
+    """Parameters as KiCad-style fields, with ``MPN`` and ``LCSC`` aliases the parts tools read."""
+    fields = {k: v for k, v in params.items() if not k.startswith("_") and v}
+    for name, pattern in (
+        ("MPN", r"^(mpn|manufacturer.?part|mfr.?part|part.?number)"),
+        ("LCSC", r"lcsc"),
+    ):
+        if name not in fields:
+            found = _alias(fields, pattern)
+            if found:
+                fields[name] = found
+    return fields
+
+
+def to_design_model(project: AltiumProject) -> DesignModel:
+    """Parts with pin definitions plus nets: what ``kicad_connections`` and the checks use."""
+    parts: dict[str, Part] = {}
+    for ref, comp in project.components().items():
+        symbol = SymbolInfo(
+            name=comp.lib_ref,
+            pins={
+                p.number: PinDef(
+                    p.number, clean_pin_name(p.name), _KICAD_PIN_TYPE.get(p.electrical, "passive")
+                )
+                for p in comp.pins
+            },
+            description=comp.description,
+        )
+        parts[ref] = Part(
+            ref=ref,
+            value=comp.comment,
+            footprint=comp.footprint,
+            lib_id=comp.lib_ref,
+            fields=part_fields(comp.params),
+            symbol=symbol,
+            sheet=comp.sheet,
+        )
+    return DesignModel(parts, dict(project.netlist.nets), to_board(project), "altium")
+
+
+def to_schematic(project: AltiumProject) -> Schematic:
+    """A :class:`Schematic` (symbols, labels, counts) built from the Altium sheets."""
+    symbols: list[SchSymbol] = []
+    labels: list[SchLabel] = []
+    for sheet in project.sheets:
+        for comp in sheet.components:
+            if comp.is_power or not comp.designator:
+                continue
+            symbols.append(
+                SchSymbol(
+                    lib_id=comp.lib_ref,
+                    reference=comp.designator,
+                    value=comp.comment,
+                    footprint=comp.footprint,
+                    unit=int(comp.params.get("_part", "1") or 1),
+                    x=comp.x,
+                    y=comp.y,
+                    angle=0.0,
+                    uuid=f"{sheet.name}:{comp.designator}",
+                    fields=part_fields(comp.params),
+                    sheet=sheet.name,
+                )
+            )
+        for text, (x, y) in sheet.net_labels:
+            labels.append(
+                SchLabel("label", text, x / 100000 * 0.254, y / 100000 * 0.254, sheet.name)
+            )
+        for text, (x, y) in sheet.power_ports:
+            labels.append(
+                SchLabel("global_label", text, x / 100000 * 0.254, y / 100000 * 0.254, sheet.name)
+            )
+    first = project.sheets[0].path if project.sheets else project.root
+    return Schematic(
+        path=Path(first),
+        version="altium",
+        symbols=symbols,
+        labels=labels,
+        wires=sum(len(s.wires) for s in project.sheets),
+        no_connects=sum(s.no_erc for s in project.sheets),
+        junctions=sum(len(s.junctions) for s in project.sheets),
+        sheets=[s.name for s in project.sheets],
+        lib_ids=sorted({s.lib_id for s in symbols}),
+        title=project.name,
+        generator="altium",
+    )
+
+
+def to_board(project: AltiumProject) -> Board | None:
+    """A :class:`Board` from the ``.PcbDoc`` (Altium's Y axis points up, KiCad's down)."""
+    pcb = project.pcb
+    if pcb is None:
+        return None
+    footprints: list[Footprint] = []
+    for comp in pcb.components:
+        pads = [
+            Pad(
+                number=p.designator,
+                kind="thru_hole" if p.hole > 0 else "smd",
+                shape="rect",
+                x=p.x,
+                y=-p.y,
+                width=p.size_x,
+                height=p.size_y,
+                layers=["*.Cu"] if p.hole > 0 else ["F.Cu" if comp.layer == "Top" else "B.Cu"],
+                net=p.net,
+                drill=p.hole,
+            )
+            for p in comp.pads
+        ]
+        footprints.append(
+            Footprint(
+                lib_id=comp.footprint,
+                reference=comp.designator,
+                value=comp.comment or comp.lib_ref,
+                x=comp.x,
+                y=-comp.y,
+                angle=comp.rotation,
+                layer="F.Cu" if comp.layer == "Top" else "B.Cu",
+                pads=pads,
+            )
+        )
+
+    def cu(name: str) -> str:
+        if name == "Top Layer" or name == pcb.layers[0]:
+            return "F.Cu"
+        if name == "Bottom Layer" or name == pcb.layers[-1]:
+            return "B.Cu"
+        return name
+
+    box = pcb.outline_bbox()
+    return Board(
+        path=pcb.path,
+        version="altium",
+        thickness=1.6,
+        copper_layers=[cu(n) for n in pcb.layers],
+        nets=dict(enumerate(pcb.nets)),
+        footprints=footprints,
+        tracks=[
+            Track(t.x1, -t.y1, t.x2, -t.y2, t.width, cu(t.layer), t.net)
+            for t in pcb.tracks
+            if t.layer in pcb.layers
+        ],
+        vias=[
+            Via(v.x, -v.y, v.diameter, v.hole, [cu(v.start), cu(v.end)], v.net) for v in pcb.vias
+        ],
+        zones=[],
+        outline=(box[0], -box[3], box[2], -box[1]) if box else None,
+        texts=[],
+        rules={},
+        generator="altium",
+    )

traceforge/altium/outputs.py

@@ -0,0 +1,24 @@
+"""Write netlist, BOM and the KiCad hand-off files of an Altium project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from traceforge.altium.project import AltiumProject, bom_csv, kicad_netlist
+
+KICAD_IMPORT_NOTE = (
+    "KiCad's own importer (File > Import > Non-KiCad Project, KiCad 8+; Altium support is in "
+    "the GUI only, kicad-cli has no import) gives a full .kicad_sch/.kicad_pcb with graphics. "
+    "This conversion writes the connectivity: a KiCad netlist (.net) and a BOM. In the PCB "
+    "editor use File > Import > Netlist after the footprints exist in a KiCad library."
+)
+
+
+def convert(project: AltiumProject, out_dir: str | Path) -> dict:
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    net = out / f"{project.name}.net"
+    bom = out / f"{project.name}_bom.csv"
+    net.write_text(kicad_netlist(project), encoding="utf-8")
+    bom.write_text(bom_csv(project), encoding="utf-8")
+    return {"netlist": str(net), "bom": str(bom), "note": KICAD_IMPORT_NOTE}

traceforge/altium/pcb.py

@@ -0,0 +1,301 @@
+"""Altium ``.PcbDoc`` parser: components, pads, nets, tracks, vias, outline and layer stack."""
+
+from __future__ import annotations
+
+import re
+import struct
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from traceforge.altium.cfb import AltiumError, length_prefixed, open_cfb, parse_properties
+
+MM_PER_MIL = 0.0254
+UNIT = 10000  # binary coordinates: 1/10000 mil
+_NO_NET = 0xFFFF
+
+
+def layer_name(layer_id: int, names: dict[int, str] | None = None) -> str:
+    if names and layer_id in names:
+        return names[layer_id]
+    if layer_id == 1:
+        return "Top Layer"
+    if layer_id == 32:
+        return "Bottom Layer"
+    if 2 <= layer_id <= 31:
+        return f"Mid-Layer {layer_id - 1}"
+    fixed = {
+        33: "Top Overlay",
+        34: "Bottom Overlay",
+        35: "Top Paste",
+        36: "Bottom Paste",
+        37: "Top Solder",
+        38: "Bottom Solder",
+        55: "Drill Guide",
+        56: "Keep-Out Layer",
+        73: "Drill Drawing",
+        74: "Multi-Layer",
+    }
+    if layer_id in fixed:
+        return fixed[layer_id]
+    if 39 <= layer_id <= 54:
+        return f"Internal Plane {layer_id - 38}"
+    if 57 <= layer_id <= 72:
+        return f"Mechanical {layer_id - 56}"
+    return f"Layer {layer_id}"
+
+
+def _mm(text: str) -> float:
+    """``4550mil`` / ``12.5mm`` / bare number (mil) to mm."""
+    m = re.match(r"\s*(-?[\d.]+(?:[eE][-+]?\d+)?)\s*(mil|mm|in)?", text or "")
+    if not m:
+        return 0.0
+    v = float(m.group(1))
+    unit = m.group(2) or "mil"
+    return v * {"mil": MM_PER_MIL, "mm": 1.0, "in": 25.4}[unit]
+
+
+@dataclass
+class PcbPad:
+    designator: str
+    x: float
+    y: float
+    size_x: float
+    size_y: float
+    hole: float
+    layer: str
+    net: str = ""
+    component: int = -1  # index into AltPcb.components, -1 for free pads
+    plated: bool = True
+
+
+@dataclass
+class PcbComponent:
+    designator: str
+    footprint: str
+    layer: str
+    x: float
+    y: float
+    rotation: float
+    comment: str = ""
+    description: str = ""
+    lib_ref: str = ""
+    pads: list[PcbPad] = field(default_factory=list)
+
+
+@dataclass
+class PcbTrack:
+    x1: float
+    y1: float
+    x2: float
+    y2: float
+    width: float
+    layer: str
+    net: str
+
+
+@dataclass
+class PcbVia:
+    x: float
+    y: float
+    diameter: float
+    hole: float
+    start: str
+    end: str
+    net: str
+
+
+@dataclass
+class AltPcb:
+    path: Path
+    components: list[PcbComponent]
+    nets: list[str]
+    free_pads: list[PcbPad]
+    tracks: list[PcbTrack]
+    vias: list[PcbVia]
+    layers: list[str]  # copper and enabled layers in stack order
+    outline: list[tuple[float, float]]
+    counts: dict[str, int] = field(default_factory=dict)
+
+    def tracks_per_layer(self) -> dict[str, int]:
+        out: dict[str, int] = {}
+        for t in self.tracks:
+            out[t.layer] = out.get(t.layer, 0) + 1
+        return dict(sorted(out.items()))
+
+    def outline_bbox(self) -> tuple[float, float, float, float] | None:
+        if not self.outline:
+            return None
+        xs = [p[0] for p in self.outline]
+        ys = [p[1] for p in self.outline]
+        return (min(xs), min(ys), max(xs), max(ys))
+
+    def pad_nets(self) -> dict[str, list[tuple[str, str]]]:
+        nets: dict[str, list[tuple[str, str]]] = {}
+        for comp in self.components:
+            for pad in comp.pads:
+                if pad.net:
+                    nets.setdefault(pad.net, []).append((comp.designator, pad.designator))
+        return nets
+
+
+def _records(ole, storage: str):
+    name = [storage, "Data"]
+    if not ole.exists(name):
+        return b""
+    return ole.openstream(name).read()
+
+
+def _text_records(ole, storage: str) -> list[dict[str, str]]:
+    return [parse_properties(p) for _, p in length_prefixed(_records(ole, storage))]
+
+
+def _sub(data: bytes, pos: int):
+    (size,) = struct.unpack_from("<I", data, pos)
+    pos += 4
+    return data[pos : pos + size], pos + size
+
+
+def _pstr(block: bytes) -> str:
+    if not block:
+        return ""
+    return block[1 : 1 + block[0]].decode("cp1252", "replace")
+
+
+def _i32(b: bytes, off: int) -> int:
+    return struct.unpack_from("<i", b, off)[0]
+
+
+def parse_pcb(path: str | Path) -> AltPcb:
+    path = Path(path)
+    ole = open_cfb(path)
+    try:
+        if not ole.exists(["Board6", "Data"]):
+            raise AltiumError(f"{path.name}: no Board6 storage (not a PCB document)")
+        board = _text_records(ole, "Board6")
+        board = board[0] if board else {}
+        nets = [r.get("NAME", "") for r in _text_records(ole, "Nets6")]
+        comp_rows = _text_records(ole, "Components6")
+        pads_raw = _records(ole, "Pads6")
+        tracks_raw = _records(ole, "Tracks6")
+        vias_raw = _records(ole, "Vias6")
+        counts = {}
+        for name in ("Arcs6", "Fills6", "Regions6", "Polygons6", "Texts6"):
+            data = _records(ole, name)
+            counts[name.rstrip("6").lower()] = (
+                sum(1 for _ in length_prefixed(data)) if name == "Polygons6" else 0
+            )
+    finally:
+        ole.close()
+
+    names: dict[int, str] = {}
+    for key, val in board.items():
+        m = re.fullmatch(r"LAYER(\d+)NAME", key)
+        if m:
+            names[int(m.group(1))] = val
+    layers: list[str] = []
+    cur, seen = 1, set()
+    while cur and cur not in seen and cur in names:  # copper stack: LAYERnNEXT chain from top
+        seen.add(cur)
+        layers.append(names[cur])
+        cur = int(float(board.get(f"LAYER{cur}NEXT", "0") or 0))
+
+    def net(idx: int) -> str:
+        return nets[idx] if idx != _NO_NET and idx < len(nets) else ""
+
+    components = [
+        PcbComponent(
+            designator=r.get("SOURCEDESIGNATOR", ""),
+            footprint=r.get("PATTERN", ""),
+            layer="Bottom" if r.get("LAYER", "TOP").upper().startswith("BOTTOM") else "Top",
+            x=_mm(r.get("X", "")),
+            y=_mm(r.get("Y", "")),
+            rotation=float(r.get("ROTATION", "0").strip() or 0),
+            description=r.get("SOURCEDESCRIPTION", ""),
+            lib_ref=r.get("SOURCELIBREFERENCE", ""),
+            comment=r.get("COMMENT", ""),
+        )
+        for r in comp_rows
+    ]
+    free: list[PcbPad] = []
+    pos = 0
+    while pos < len(pads_raw):
+        if pads_raw[pos] != 2:
+            raise AltiumError("unexpected record in Pads6")
+        pos += 1
+        name_b, pos = _sub(pads_raw, pos)
+        for _ in range(3):
+            _, pos = _sub(pads_raw, pos)
+        main, pos = _sub(pads_raw, pos)
+        _, pos = _sub(pads_raw, pos)  # size and shape per layer
+        if len(main) < 61:
+            continue
+        comp_idx = struct.unpack_from("<H", main, 7)[0]
+        pad = PcbPad(
+            designator=_pstr(name_b),
+            x=_i32(main, 13) / UNIT * MM_PER_MIL,
+            y=_i32(main, 17) / UNIT * MM_PER_MIL,
+            size_x=_i32(main, 21) / UNIT * MM_PER_MIL,
+            size_y=_i32(main, 25) / UNIT * MM_PER_MIL,
+            hole=_i32(main, 45) / UNIT * MM_PER_MIL,
+            layer=layer_name(main[0], names),
+            net=net(struct.unpack_from("<H", main, 3)[0]),
+            component=comp_idx if comp_idx != _NO_NET and comp_idx < len(components) else -1,
+            plated=bool(main[60]),
+        )
+        if pad.component >= 0:
+            components[pad.component].pads.append(pad)
+        else:
+            free.append(pad)
+
+    tracks: list[PcbTrack] = []
+    pos = 0
+    while pos < len(tracks_raw):
+        pos += 1  # record type 4
+        block, pos = _sub(tracks_raw, pos)
+        if len(block) < 33:
+            continue
+        tracks.append(
+            PcbTrack(
+                x1=_i32(block, 13) / UNIT * MM_PER_MIL,
+                y1=_i32(block, 17) / UNIT * MM_PER_MIL,
+                x2=_i32(block, 21) / UNIT * MM_PER_MIL,
+                y2=_i32(block, 25) / UNIT * MM_PER_MIL,
+                width=_i32(block, 29) / UNIT * MM_PER_MIL,
+                layer=layer_name(block[0], names),
+                net=net(struct.unpack_from("<H", block, 3)[0]),
+            )
+        )
+    vias: list[PcbVia] = []
+    pos = 0
+    while pos < len(vias_raw):
+        pos += 1  # record type 3
+        block, pos = _sub(vias_raw, pos)
+        if len(block) < 31:
+            continue
+        vias.append(
+            PcbVia(
+                x=_i32(block, 13) / UNIT * MM_PER_MIL,
+                y=_i32(block, 17) / UNIT * MM_PER_MIL,
+                diameter=_i32(block, 21) / UNIT * MM_PER_MIL,
+                hole=_i32(block, 25) / UNIT * MM_PER_MIL,
+                start=layer_name(block[29], names),
+                end=layer_name(block[30], names),
+                net=net(struct.unpack_from("<H", block, 3)[0]),
+            )
+        )
+    outline: list[tuple[float, float]] = []
+    i = 0
+    while f"VX{i}" in board and f"VY{i}" in board:
+        outline.append((_mm(board[f"VX{i}"]), _mm(board[f"VY{i}"])))
+        i += 1
+    return AltPcb(
+        path=path,
+        components=components,
+        nets=nets,
+        free_pads=free,
+        tracks=tracks,
+        vias=vias,
+        layers=layers,
+        outline=outline,
+        counts=counts,
+    )