traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/kicad/models3d.py

@@ -0,0 +1,942 @@
+"""3D models of footprints: find, check, assign, generate and render.
+
+A board footprint carries ``(model "<path>" (offset ..) (scale ..) (rotate ..))`` entries. The path
+is usually ``${KICAD8_3DMODEL_DIR}/<Lib>.3dshapes/<name>.step``; this module expands such
+variables, reports which paths resolve, proposes library models (with a confidence, never silently),
+writes ``(model ...)`` entries, and generates generic placeholder bodies for custom footprints.
+Rendering is delegated to ``kicad-cli pcb render`` (KiCad 8 or later); nothing is faked.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import shutil
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from difflib import SequenceMatcher
+from functools import lru_cache
+from pathlib import Path
+
+from traceforge import sexpr
+from traceforge.checks import Finding
+from traceforge.kicad import edit, formats, install
+from traceforge.kicad.cli import KicadCli, KicadCliError
+from traceforge.kicad.libraries import footprint_dirs, footprint_extent
+from traceforge.sexpr import Node, Sym, find, find_all, fmt, num
+
+CHECK_ID = "pcb.models3d"
+MODEL_EXTENSIONS = (".step", ".stp", ".wrl")
+_VERSIONS = ("11", "10", "9", "8", "7", "6")
+_MODEL_ENV = tuple(f"KICAD{v}_3DMODEL_DIR" for v in _VERSIONS) + ("KICAD_3DMODEL_DIR",)
+_VAR = re.compile(r"\$\{([^}]+)\}|\$\(([^)]+)\)")
+# Footprints that legitimately have no 3D body.
+_NO_MODEL = re.compile(
+    r"MountingHole|Mounting_Hole|Fiducial|TestPoint|Test_Point|TestPad|Testpad|Logo|Symbol:|"
+    r"Graphic|NetTie|Net_Tie|SolderJumper|Solder_Jumper|SolderWire|Jumper_Solder",
+    re.I,
+)
+
+
+class ModelError(ValueError):
+    """The 3D model operation does not apply."""
+
+
+# ---------------------------------------------------------------------------- library dirs
+
+
+def model_dirs(extra: list[Path] | None = None) -> list[Path]:
+    """Directories holding ``<Lib>.3dshapes`` folders, found like the symbol/footprint libraries."""
+    dirs: list[Path] = list(extra or [])
+    for env in _MODEL_ENV:
+        if os.environ.get(env):
+            dirs.append(Path(os.environ[env]))
+    dirs += [base / "3dmodels" for base in install.share_dirs()]
+    return [d for d in dict.fromkeys(dirs) if d.is_dir()]
+
+
+def project_variables(project_dir: Path, board: Path | None = None) -> dict[str, str]:
+    """``${KIPRJMOD}`` plus the project's user-defined text variables (``.kicad_pro``)."""
+    variables = {"KIPRJMOD": str(project_dir)}
+    pros = [board.with_suffix(".kicad_pro")] if board else []
+    pros += sorted(project_dir.glob("*.kicad_pro"))
+    for pro in pros:
+        try:
+            data = json.loads(pro.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            continue
+        text = data.get("text_variables") if isinstance(data, dict) else None
+        if isinstance(text, dict):
+            variables.update({str(k): str(v) for k, v in text.items()})
+        break
+    return variables
+
+
+def expand_candidates(
+    raw: str,
+    project_dir: Path,
+    variables: dict[str, str] | None = None,
+    dirs: list[Path] | None = None,
+) -> list[Path]:
+    """Every path ``raw`` can mean. A ``KICADn_3DMODEL_DIR`` variable that is not set in the
+    environment stands for each installed library root, so a KiCad 6 path works on KiCad 9."""
+    variables = {"KIPRJMOD": str(project_dir), **(variables or {})}
+    roots = dirs if dirs is not None else model_dirs()
+    results = [raw]
+    for token in dict.fromkeys(m.group(0) for m in _VAR.finditer(raw)):
+        name = token[2:-1]
+        if name in variables:
+            values = [variables[name]]
+        elif re.fullmatch(r"KICAD\d*_3DMODEL_DIR", name):
+            values = [os.environ[name]] if os.environ.get(name) else [str(d) for d in roots]
+        elif os.environ.get(name):
+            values = [os.environ[name]]
+        else:
+            values = []
+        results = [r.replace(token, v) for r in results for v in values]
+    paths = []
+    for text in results:
+        if _VAR.search(text):
+            continue
+        path = Path(text)
+        paths.append(path if path.is_absolute() else project_dir / path)
+    return paths
+
+
+def resolve_model(
+    raw: str,
+    project_dir: Path,
+    variables: dict[str, str] | None = None,
+    dirs: list[Path] | None = None,
+) -> Path | None:
+    candidates = expand_candidates(raw, project_dir, variables, dirs)
+    for path in candidates:
+        if path.is_file():
+            return path
+    # Newer KiCad libraries ship STEP only, older boards name the WRL: try the same stem.
+    for path in candidates:
+        for suffix in (".step", ".stp", ".wrl"):
+            other = path.with_suffix(suffix)
+            if other.is_file():
+                return other
+    return None
+
+
+# ---------------------------------------------------------------------------- reading
+
+
+@dataclass
+class ModelRef:
+    path: str  # as written in the file
+    resolved: Path | None
+    offset: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    scale: tuple[float, float, float] = (1.0, 1.0, 1.0)
+    rotate: tuple[float, float, float] = (0.0, 0.0, 0.0)
+    hidden: bool = False
+
+    def to_dict(self) -> dict:
+        return {
+            "path": self.path,
+            "resolved": str(self.resolved) if self.resolved else None,
+            "offset": list(self.offset),
+            "scale": list(self.scale),
+            "rotate": list(self.rotate),
+            **({"hidden": True} if self.hidden else {}),
+        }
+
+
+@dataclass
+class Proposal:
+    path: Path  # the model file
+    confidence: float
+    reason: str
+
+    @property
+    def label(self) -> str:
+        return "high" if self.confidence >= 0.9 else "medium" if self.confidence >= 0.7 else "low"
+
+    def to_dict(self) -> dict:
+        return {
+            "path": str(self.path),
+            "confidence": round(self.confidence, 2),
+            "level": self.label,
+            "reason": self.reason,
+        }
+
+
+@dataclass
+class FootprintModels:
+    ref: str
+    lib_id: str
+    models: list[ModelRef] = field(default_factory=list)
+    needs_model: bool = True
+    status: str = "none"  # resolved | missing | none
+    proposals: list[Proposal] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        data = {
+            "ref": self.ref,
+            "footprint": self.lib_id,
+            "status": self.status,
+            "needs_model": self.needs_model,
+            "models": [m.to_dict() for m in self.models],
+        }
+        if self.proposals:
+            data["proposals"] = [p.to_dict() for p in self.proposals]
+        return data
+
+
+def _xyz(node: Node, key: str, default: float) -> tuple[float, float, float]:
+    child = find(node, key)
+    xyz = find(child, "xyz") if child is not None else None
+    if xyz is None or len(xyz) < 4:
+        return (default,) * 3
+    return (num(xyz[1]), num(xyz[2]), num(xyz[3]))
+
+
+def _hidden(model: Node) -> bool:
+    return any(
+        isinstance(c, list) and c and c[0] == "hide" and (len(c) < 2 or c[1] != "no") for c in model
+    )
+
+
+def node_models(
+    fp: Node,
+    project_dir: Path,
+    variables: dict[str, str] | None = None,
+    dirs: list[Path] | None = None,
+) -> list[ModelRef]:
+    return [
+        ModelRef(
+            str(m[1]),
+            resolve_model(str(m[1]), project_dir, variables, dirs),
+            _xyz(m, "offset", 0.0),
+            _xyz(m, "scale", 1.0),
+            _xyz(m, "rotate", 0.0),
+            _hidden(m),
+        )
+        for m in find_all(fp, "model")
+        if len(m) >= 2
+    ]
+
+
+def needs_model(lib_id: str, fp: Node) -> bool:
+    """False for mounting holes, fiducials, test points, logos and other pad-less artwork."""
+    if _NO_MODEL.search(lib_id):
+        return False
+    return bool(find_all(fp, "pad"))
+
+
+def _status(models: list[ModelRef]) -> str:
+    live = [m for m in models if not m.hidden]
+    if not live:
+        return "none"
+    return "resolved" if all(m.resolved for m in live) else "missing"
+
+
+def _lib_id(fp: Node) -> str:
+    return str(fp[1]) if len(fp) > 1 and isinstance(fp[1], str) else ""
+
+
+def library_models(lib_id: str, dirs: list[Path] | None = None) -> list[str]:
+    """Raw model paths declared by a library footprint (``Lib:Name``), empty when unknown."""
+    nick, _, name = lib_id.partition(":")
+    for base in footprint_dirs() if dirs is None else dirs:
+        file = base / f"{nick}.pretty" / f"{name}.kicad_mod"
+        if file.is_file():
+            try:
+                root = sexpr.parse(file.read_text(encoding="utf-8"))
+            except (OSError, sexpr.ParseError):
+                return []
+            return [str(m[1]) for m in find_all(root, "model") if len(m) > 1]
+    return []
+
+
+def _value(fp: Node) -> str:
+    return sexpr.prop(fp, "Value") or next(
+        (str(t[2]) for t in find_all(fp, "fp_text") if len(t) > 2 and t[1] == "value"), ""
+    )
+
+
+def inventory(
+    board: Path, *, propose: bool = True, dirs: list[Path] | None = None
+) -> list[FootprintModels]:
+    """Every footprint of a board with its model references, resolution and proposals."""
+    board = Path(board)
+    root = edit.load(board)
+    variables = project_variables(board.parent, board)
+    rows = []
+    for ref, fp in edit.footprints(root).items():
+        lib_id = _lib_id(fp)
+        models = node_models(fp, board.parent, variables, dirs)
+        row = FootprintModels(ref, lib_id, models, needs_model(lib_id, fp), _status(models))
+        if propose and row.needs_model and row.status != "resolved":
+            row.proposals = propose_models(lib_id, _value(fp), dirs)
+        rows.append(row)
+    return rows
+
+
+# ---------------------------------------------------------------------------- matching
+
+
+@lru_cache(maxsize=8)
+def _index(dirs: tuple[Path, ...]) -> dict[str, list[Path]]:
+    """Lower-case model stem -> files, over every ``*.3dshapes`` folder (STEP before WRL)."""
+    found: dict[str, list[Path]] = {}
+    for base in dirs:
+        for shapes in sorted(base.glob("*.3dshapes")):
+            files = [f for f in shapes.iterdir() if f.suffix.lower() in MODEL_EXTENSIONS]
+            for file in sorted(
+                files, key=lambda p: (MODEL_EXTENSIONS.index(p.suffix.lower()), p.name)
+            ):
+                found.setdefault(file.stem.lower(), []).append(file)
+    return found
+
+
+def _norm(name: str) -> str:
+    return re.sub(r"[-\s]+", "_", name.lower())
+
+
+def _package_parts(name: str) -> tuple[str, str, list[float]]:
+    """``SOIC-8W_5.3x5.3mm_P1.27mm`` -> family ``soic``, pin count ``8``, body size ``[5.3, 5.3]``."""
+    first = re.match(r"([A-Za-z]+)[-_]?(\d*)", name)
+    sizes = re.search(r"(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)", name)
+    return (
+        first.group(1).lower() if first else "",
+        first.group(2) if first else "",
+        [float(sizes.group(1)), float(sizes.group(2))] if sizes else [],
+    )
+
+
+def _similarity(name: str, other: str) -> float:
+    """0..1 package-family similarity: family, pin count and body size, blended with the text."""
+    fam_a, pins_a, size_a = _package_parts(name)
+    fam_b, pins_b, size_b = _package_parts(other)
+    structured = 0.4 * (fam_a == fam_b) + 0.3 * (pins_a == pins_b)
+    if size_a and size_b:
+        close = all(abs(a - b) <= 0.05 * max(a, b) for a, b in zip(size_a, size_b, strict=True))
+        structured += 0.3 * close
+    elif not size_a and not size_b:
+        structured += 0.15
+    ratio = SequenceMatcher(None, _norm(name), _norm(other)).ratio()
+    return 0.5 * ratio + 0.5 * structured
+
+
+def propose_models(
+    lib_id: str, value: str = "", dirs: list[Path] | None = None, limit: int = 3
+) -> list[Proposal]:
+    """Library models a footprint could use, best first, each with a confidence.
+
+    1.00 the model the library footprint itself declares, 0.95 same library and name, 0.90
+    same name in another library; below that fuzzy matches by package family, capped at 0.89 so
+    that only exact matches reach the automatic-assignment threshold.
+    """
+    roots = model_dirs() if dirs is None else dirs
+    if not roots or not lib_id:
+        return []
+    nick, _, name = lib_id.partition(":")
+    name = name or nick
+    proposals: dict[Path, Proposal] = {}
+
+    def add(path: Path, confidence: float, reason: str) -> None:
+        if path not in proposals or proposals[path].confidence < confidence:
+            proposals[path] = Proposal(path, confidence, reason)
+
+    for raw in library_models(lib_id):
+        found = resolve_model(raw, Path("."), dirs=roots)
+        if found:
+            add(found, 1.0, "declared by the library footprint")
+    index = _index(tuple(roots))
+    for path in index.get(name.lower(), []):
+        same_lib = path.parent.name.lower() == f"{nick.lower()}.3dshapes"
+        add(path, 0.95 if same_lib else 0.9, "same name in " + path.parent.name)
+    if not proposals:
+        hint = _norm(value)
+        scored = []
+        for stem, files in index.items():
+            ratio = _similarity(name, stem)
+            if files[0].parent.name.lower() == f"{nick.lower()}.3dshapes":
+                ratio += 0.05
+            if len(hint) > 2 and hint in _norm(stem):
+                ratio += 0.05
+            if ratio >= 0.6:
+                scored.append((ratio, files[0]))
+        for ratio, path in sorted(scored, key=lambda s: (-s[0], str(s[1])))[:limit]:
+            add(path, min(ratio, 0.89), f"similar name in {path.parent.name}")
+    return sorted(proposals.values(), key=lambda p: (-p.confidence, str(p.path)))[:limit]
+
+
+# ---------------------------------------------------------------------------- check
+
+
+def check_models(board: Path, dirs: list[Path] | None = None) -> list[Finding]:
+    """P1 for a real part with no model or a model path that does not resolve; P3 for mounting
+    holes, fiducials and test points that cannot have one (and for broken paths on those)."""
+    findings: list[Finding] = []
+    for row in inventory(board, dirs=dirs):
+        if row.status == "resolved":
+            continue
+        hint, action = "", "Assign a model with `traceforge models3d assign`."
+        if row.proposals:
+            best = row.proposals[0]
+            hint = (
+                f"best match {best.path.name} ({best.label}, {best.confidence:.2f}: {best.reason})"
+            )
+            action = f"Assign {best.path} with `traceforge models3d assign {row.ref} <model>`."
+        if row.status == "missing":
+            gone = [m.path for m in row.models if not m.resolved and not m.hidden]
+            findings.append(
+                Finding(
+                    "P1" if row.needs_model else "P3",
+                    CHECK_ID,
+                    f"{row.ref} ({row.lib_id}): 3D model path does not resolve",
+                    refs=[row.ref],
+                    evidence="; ".join([*gone[:3], hint] if hint else gone[:3]),
+                    action=action,
+                )
+            )
+        elif row.needs_model:
+            findings.append(
+                Finding(
+                    "P1",
+                    CHECK_ID,
+                    f"{row.ref} ({row.lib_id}) has no 3D model",
+                    refs=[row.ref],
+                    evidence=hint,
+                    action=action,
+                )
+            )
+        else:
+            findings.append(
+                Finding(
+                    "P3",
+                    CHECK_ID,
+                    f"{row.ref} ({row.lib_id}) has no 3D model (none needed)",
+                    refs=[row.ref],
+                )
+            )
+    return findings
+
+
+def summary(rows: list[FootprintModels]) -> dict:
+    counts = {"resolved": 0, "missing": 0, "none": 0, "none_needed": 0}
+    for row in rows:
+        if row.status == "none" and not row.needs_model:
+            counts["none_needed"] += 1
+        else:
+            counts[row.status] += 1
+    return {"footprints": len(rows), **counts}
+
+
+# ---------------------------------------------------------------------------- assign
+
+
+def _model_var(root: Node) -> str:
+    return f"KICAD{formats.root_info(root).major or 8}_3DMODEL_DIR"
+
+
+def _written_path(
+    path: Path, root: Node, project_dir: Path, dirs: list[Path], copy: bool
+) -> tuple[str, Path | None]:
+    """The string to store for ``path`` and, when the file was copied, its new location."""
+    if not path.is_file():
+        raise ModelError(f"model file not found: {path}")
+    if path.suffix.lower() not in MODEL_EXTENSIONS:
+        raise ModelError("a 3D model must be a .step, .stp or .wrl file")
+    resolved = path.resolve()
+    for base in dirs:
+        try:
+            rel = resolved.relative_to(base.resolve()).as_posix()
+        except ValueError:
+            continue
+        return f"${{{_model_var(root)}}}/{rel}", None
+    try:  # already inside the project
+        return f"${{KIPRJMOD}}/{resolved.relative_to(project_dir.resolve()).as_posix()}", None
+    except ValueError:
+        pass
+    if not copy:
+        return resolved.as_posix(), None
+    target_dir = project_dir / "3dmodels"
+    target_dir.mkdir(exist_ok=True)
+    target = target_dir / path.name
+    if target.exists() and target.read_bytes() != path.read_bytes():
+        raise ModelError(f"{target} already exists with different content; rename the model file")
+    if not target.exists():
+        shutil.copy2(path, target)
+    return f"${{KIPRJMOD}}/3dmodels/{path.name}", target
+
+
+Vec3 = tuple[float, float, float]
+
+
+def _model_node(written: str, offset: Vec3, scale: Vec3, rotate: Vec3) -> Node:
+    def entry(key: str, xyz: Vec3) -> Node:
+        return [Sym(key), [Sym("xyz"), *(fmt(v) for v in xyz)]]
+
+    return [
+        Sym("model"),
+        written,
+        entry("offset", offset),
+        entry("scale", scale),
+        entry("rotate", rotate),
+    ]
+
+
+def assign_model(
+    board: Path,
+    ref: str,
+    path: Path | str,
+    offset: Vec3 = (0, 0, 0),
+    scale: Vec3 = (1, 1, 1),
+    rotate: Vec3 = (0, 0, 0),
+    *,
+    overwrite: bool = False,
+    copy_to_project: bool = True,
+    dirs: list[Path] | None = None,
+) -> dict:
+    """Write ``(model ...)`` into footprint ``ref``. Safe by default: a footprint that already has
+    a model (even a broken one) is left alone unless ``overwrite`` is true. A file outside the
+    3D libraries and the project is copied to ``<project>/3dmodels/`` and referenced through
+    ``${KIPRJMOD}``."""
+    board = Path(board)
+    root = edit.load(board)
+    fps = edit.footprints(root)
+    if ref not in fps:
+        raise ModelError(f"no footprint {ref!r} on the board")
+    fp = fps[ref]
+    existing = find_all(fp, "model")
+    if existing and not overwrite:
+        return {
+            "ref": ref,
+            "status": "kept",
+            "existing": [str(m[1]) for m in existing if len(m) > 1],
+            "note": "footprint already has a model; pass overwrite=true to replace it",
+        }
+    written, copied = _written_path(
+        Path(path), root, board.parent, model_dirs() if dirs is None else dirs, copy_to_project
+    )
+    for m in existing:
+        fp.remove(m)
+    fp.append(_model_node(written, offset, scale, rotate))
+    edit.save(board, root)
+    result = {"ref": ref, "status": "assigned", "model": written}
+    if existing:
+        result["replaced"] = [str(m[1]) for m in existing if len(m) > 1]
+    if copied:
+        result["copied_to"] = str(copied)
+    return result
+
+
+def assign_proposed(
+    board: Path, min_confidence: float = 0.9, *, dirs: list[Path] | None = None
+) -> list[dict]:
+    """Assign the best library match to every footprint without a model, but only matches at or
+    above ``min_confidence``; the rest are reported with their proposals and left untouched."""
+    results = []
+    for row in inventory(board, dirs=dirs):
+        if row.status != "none" or not row.needs_model:
+            continue
+        best = row.proposals[0] if row.proposals else None
+        if best is None or best.confidence < min_confidence:
+            results.append(
+                {
+                    "ref": row.ref,
+                    "status": "skipped",
+                    "reason": "no match at the required confidence",
+                    "proposals": [p.to_dict() for p in row.proposals],
+                }
+            )
+            continue
+        done = assign_model(board, row.ref, best.path, dirs=dirs)
+        done["confidence"] = round(best.confidence, 2)
+        results.append(done)
+    return results
+
+
+# ---------------------------------------------------------------------------- generic models
+
+Box = tuple[float, float, float, float, float, float]  # x0, y0, z0, x1, y1, z1 in mm
+_HEIGHTS = [  # (regex on the footprint name, body height mm); first match wins
+    (r"^R_(01005|0201)", 0.25),
+    (r"^R_0402", 0.35),
+    (r"^R_0603", 0.45),
+    (r"^R_0805", 0.55),
+    (r"^R_(1206|1210|2010|2512)", 0.6),
+    (r"^C_0402", 0.5),
+    (r"^C_0603", 0.8),
+    (r"^C_0805", 1.25),
+    (r"^C_1206", 1.6),
+    (r"^(LED|L)_0[46]0[23]", 0.6),
+    (r"^LED_", 1.0),
+    (r"SOIC|SOP-|SO-", 1.75),
+    (r"TSSOP|MSOP|SSOP|VSSOP", 1.1),
+    (r"QFN|DFN|LGA|WSON|UDFN", 0.9),
+    (r"QFP", 1.5),
+    (r"SOT-223", 1.7),
+    (r"SOT-23|SC-70|SOT-323|SOT-363", 1.1),
+    (r"SOD-|SOT-", 1.0),
+    (r"TO-220", 4.5),
+    (r"DIP", 3.4),
+    (r"USB", 3.2),
+    (r"PinHeader|PinSocket", 2.5),
+    (r"Crystal|HC49", 3.5),
+    (r"BGA", 1.2),
+]
+
+
+@dataclass
+class GenericBody:
+    boxes: list[Box]  # the body first, then one stub per pad
+    size: tuple[float, float, float]  # body length, width, height (mm)
+    height_basis: str
+    pins: int
+
+
+def _pads(fp: Node) -> list[tuple[float, float, float, float, bool]]:
+    """Footprint-local pads: x, y, width, height (after the pad's rotation), through-hole."""
+    pads = []
+    for pad in find_all(fp, "pad"):
+        at, size = find(pad, "at"), find(pad, "size")
+        if at is None or size is None or len(pad) < 4 or len(size) < 2:
+            continue
+        w = num(size[1])
+        h = num(size[2]) if len(size) > 2 else w
+        if len(at) > 3 and round(num(at[3]) / 90) % 2:
+            w, h = h, w
+        pads.append((num(at[1]), num(at[2]), w, h, str(pad[2]) in {"thru_hole", "np_thru_hole"}))
+    return pads
+
+
+def _body_rect(pads: list, tht: bool, court: tuple[float, float, float, float]) -> tuple:
+    """Body length, width and centre from the pads: two-terminal parts span the pad pitch,
+    gull-wing parts sit between the inner pad edges, everything else fills the courtyard."""
+    xs = sorted({round(p[0], 3) for p in pads})
+    ys = sorted({round(p[1], 3) for p in pads})
+    if len(pads) == 2 and not tht:
+        a, b = pads
+        if abs(a[0] - b[0]) >= abs(a[1] - b[1]):
+            return abs(a[0] - b[0]), min(a[3], b[3]) * 0.85, (a[0] + b[0]) / 2, (a[1] + b[1]) / 2
+        return min(a[2], b[2]) * 0.85, abs(a[1] - b[1]), (a[0] + b[0]) / 2, (a[1] + b[1]) / 2
+    if not tht and len(pads) >= 3 and 2 in (len(xs), len(ys)):
+        cx, cy = (xs[0] + xs[-1]) / 2, (ys[0] + ys[-1]) / 2
+        if len(ys) == 2:  # two rows along x
+            pitch = min((b - a for a, b in zip(xs, xs[1:], strict=False)), default=1.0)
+            depth = next(p[3] for p in pads if round(p[1], 3) == ys[0])
+            return (xs[-1] - xs[0] + pitch) * 0.97, ys[1] - ys[0] - depth * 0.6, cx, cy
+        pitch = min((b - a for a, b in zip(ys, ys[1:], strict=False)), default=1.0)
+        depth = next(p[2] for p in pads if round(p[0], 3) == xs[0])
+        return xs[1] - xs[0] - depth * 0.6, (ys[-1] - ys[0] + pitch) * 0.97, cx, cy
+    if not tht and len(pads) >= 8 and len(xs) >= 3 and len(ys) >= 3:  # QFP / QFN: pads on 4 sides
+        left = next(p[2] for p in pads if round(p[0], 3) == xs[0])
+        top = next(p[3] for p in pads if round(p[1], 3) == ys[0])
+        return (
+            max(xs[-1] - xs[0] - left * 0.6, 0.5),
+            max(ys[-1] - ys[0] - top * 0.6, 0.5),
+            (xs[0] + xs[-1]) / 2,
+            (ys[0] + ys[-1]) / 2,
+        )
+    return (
+        max(court[2] - court[0] - 0.5, 0.5),
+        max(court[3] - court[1] - 0.5, 0.5),
+        (court[0] + court[2]) / 2,
+        (court[1] + court[3]) / 2,
+    )
+
+
+def generic_body(fp: Node) -> GenericBody:
+    """A correct-size placeholder from the footprint: a body box plus one stub per pad."""
+    lib_id = _lib_id(fp)
+    name = lib_id.partition(":")[2] or lib_id
+    pads = _pads(fp)
+    if not pads:
+        raise ModelError(f"{lib_id or 'footprint'} has no pads; nothing to model")
+    court = footprint_extent(fp)
+    if str(sexpr.value(fp, "layer", "")).startswith("B."):
+        # A bottom footprint is stored mirrored in Y; KiCad turns the model over again when it
+        # draws it, so the model has to be built in the unmirrored library frame.
+        pads = [(x, -y, w, h, thru) for x, y, w, h, thru in pads]
+        court = (court[0], -court[3], court[2], -court[1])
+    tht = any(p[4] for p in pads)
+    height, basis = (5.0 if tht else 1.5), "default guess"
+    for pattern, h in _HEIGHTS:
+        if re.search(pattern, name):
+            height, basis = h, f"guess from name ({pattern})"
+            break
+    length, width, cx, cy = _body_rect(pads, tht, court)
+    z0 = 0.0 if tht else 0.05
+    boxes: list[Box] = [
+        (cx - length / 2, cy - width / 2, z0, cx + length / 2, cy + width / 2, z0 + height)
+    ]
+    for x, y, w, h, thru in pads:
+        if thru:
+            side = max(min(w, h) * 0.4, 0.3)
+            boxes.append((x - side / 2, y - side / 2, -1.6, x + side / 2, y + side / 2, z0))
+        else:
+            boxes.append((x - w * 0.4, y - h * 0.4, 0.0, x + w * 0.4, y + h * 0.4, 0.15))
+    return GenericBody(boxes, (round(length, 3), round(width, 3), height), basis, len(pads))
+
+
+def _wrl_box(box: Box, color: Vec3) -> str:
+    x0, y0, z0, x1, y1, z1 = (v / 2.54 for v in box)  # KiCad VRML unit: 2.54 mm
+    pts = ",".join(f"{x:.5f} {y:.5f} {z:.5f}" for z in (z0, z1) for y in (y0, y1) for x in (x0, x1))
+    faces = "0,2,3,1,-1,4,5,7,6,-1,0,1,5,4,-1,2,6,7,3,-1,0,4,6,2,-1,1,3,7,5,-1"
+    r, g, b = color
+    return (
+        f"Shape {{ appearance Appearance {{ material Material {{ diffuseColor {r} {g} {b} "
+        f"specularColor 0.3 0.3 0.3 shininess 0.3 }} }}\n"
+        f"  geometry IndexedFaceSet {{ coordIndex [{faces}]\n"
+        f"    coord Coordinate {{ point [{pts}] }} }} }}\n"
+    )
+
+
+def wrl_text(body: GenericBody, name: str) -> str:
+    """VRML 2.0 in KiCad's convention (1 unit = 2.54 mm, Z up)."""
+    head = (
+        "#VRML V2.0 utf8\n"
+        f"# GENERIC PLACEHOLDER MODEL for {name}, generated by Traceforge from the footprint.\n"
+        f"# Body {body.size[0]} x {body.size[1]} x {body.size[2]} mm "
+        f"({body.height_basis}); this is NOT the real package.\n"
+    )
+    shapes = _wrl_box(body.boxes[0], (0.15, 0.15, 0.17))
+    return head + shapes + "".join(_wrl_box(b, (0.78, 0.78, 0.8)) for b in body.boxes[1:])
+
+
+class _Step:
+    def __init__(self) -> None:
+        self.lines: list[str] = []
+
+    def add(self, text: str) -> int:
+        self.lines.append(text)
+        return len(self.lines)
+
+    def text(self) -> str:
+        return "\n".join(f"#{i}={t};" for i, t in enumerate(self.lines, start=1))
+
+
+def _sub(a: tuple, b: tuple) -> Vec3:
+    return (b[0] - a[0], b[1] - a[1], b[2] - a[2])
+
+
+def _unit(v: Vec3) -> tuple[Vec3, float]:
+    length = math.sqrt(sum(c * c for c in v))
+    return (v[0] / length, v[1] / length, v[2] / length), length
+
+
+def _direction(s: _Step, v: Vec3) -> int:
+    return s.add(f"DIRECTION('',({v[0]:.6f},{v[1]:.6f},{v[2]:.6f}))")
+
+
+def _box_brep(s: _Step, box: Box, name: str) -> int:
+    x0, y0, z0, x1, y1, z1 = box
+    pts = [(x, y, z) for z in (z0, z1) for y in (y0, y1) for x in (x0, x1)]
+    centre = ((x0 + x1) / 2, (y0 + y1) / 2, (z0 + z1) / 2)
+    cp = [s.add(f"CARTESIAN_POINT('',({x:.6f},{y:.6f},{z:.6f}))") for x, y, z in pts]
+    vp = [s.add(f"VERTEX_POINT('',#{c})") for c in cp]
+    edges: dict[tuple[int, int], int] = {}
+
+    def edge(a: int, b: int) -> tuple[int, bool]:
+        lo, hi = min(a, b), max(a, b)
+        if (lo, hi) not in edges:
+            unit, length = _unit(_sub(pts[lo], pts[hi]))
+            vec = s.add(f"VECTOR('',#{_direction(s, unit)},{length:.6f})")
+            line = s.add(f"LINE('',#{cp[lo]},#{vec})")
+            edges[lo, hi] = s.add(f"EDGE_CURVE('',#{vp[lo]},#{vp[hi]},#{line},.T.)")
+        return edges[lo, hi], a < b
+
+    faces = []
+    for quad in [
+        (0, 1, 3, 2),
+        (4, 6, 7, 5),
+        (0, 4, 5, 1),
+        (2, 3, 7, 6),
+        (0, 2, 6, 4),
+        (1, 5, 7, 3),
+    ]:
+        mid = tuple(sum(pts[i][k] for i in quad) / 4 for k in range(3))
+        u, v = _sub(pts[quad[0]], pts[quad[1]]), _sub(pts[quad[1]], pts[quad[2]])
+        n = (u[1] * v[2] - u[2] * v[1], u[2] * v[0] - u[0] * v[2], u[0] * v[1] - u[1] * v[0])
+        if sum(n[k] * (mid[k] - centre[k]) for k in range(3)) < 0:  # make the loop face outward
+            quad = quad[::-1]
+            n = (-n[0], -n[1], -n[2])
+        normal, _ = _unit(n)
+        ref_dir, _ = _unit(_sub(pts[quad[0]], pts[quad[1]]))
+        oriented = []
+        for a, b in zip(quad, quad[1:] + quad[:1], strict=True):
+            e, forward = edge(a, b)
+            oriented.append(s.add(f"ORIENTED_EDGE('',*,*,#{e},{'.T.' if forward else '.F.'})"))
+        loop = s.add(f"EDGE_LOOP('',({','.join(f'#{o}' for o in oriented)}))")
+        bound = s.add(f"FACE_OUTER_BOUND('',#{loop},.T.)")
+        origin = s.add(f"CARTESIAN_POINT('',({mid[0]:.6f},{mid[1]:.6f},{mid[2]:.6f}))")
+        place = s.add(
+            f"AXIS2_PLACEMENT_3D('',#{origin},#{_direction(s, normal)},#{_direction(s, ref_dir)})"
+        )
+        plane = s.add(f"PLANE('',#{place})")
+        faces.append(s.add(f"ADVANCED_FACE('',(#{bound}),#{plane},.T.)"))
+    shell = s.add(f"CLOSED_SHELL('',({','.join(f'#{f}' for f in faces)}))")
+    return s.add(f"MANIFOLD_SOLID_BREP('{name}',#{shell})")
+
+
+def step_text(body: GenericBody, name: str) -> str:
+    """A minimal AP214 STEP file: one solid per box (body and pin stubs), in millimetres."""
+    s = _Step()
+    solids = [_box_brep(s, b, f"{name}_{i}") for i, b in enumerate(body.boxes)]
+    origin = s.add("CARTESIAN_POINT('',(0.,0.,0.))")
+    zdir = s.add("DIRECTION('',(0.,0.,1.))")
+    xdir = s.add("DIRECTION('',(1.,0.,0.))")
+    axis = s.add(f"AXIS2_PLACEMENT_3D('',#{origin},#{zdir},#{xdir})")
+    length = s.add("(LENGTH_UNIT() NAMED_UNIT(*) SI_UNIT(.MILLI.,.METRE.))")
+    angle = s.add("(NAMED_UNIT(*) PLANE_ANGLE_UNIT() SI_UNIT($,.RADIAN.))")
+    solid_angle = s.add("(NAMED_UNIT(*) SI_UNIT($,.STERADIAN.) SOLID_ANGLE_UNIT())")
+    unc = s.add(
+        f"UNCERTAINTY_MEASURE_WITH_UNIT(LENGTH_MEASURE(1.E-05),#{length},"
+        "'distance_accuracy_value','confusion accuracy')"
+    )
+    ctx = s.add(
+        f"(GEOMETRIC_REPRESENTATION_CONTEXT(3) GLOBAL_UNCERTAINTY_ASSIGNED_CONTEXT((#{unc})) "
+        f"GLOBAL_UNIT_ASSIGNED_CONTEXT((#{length},#{angle},#{solid_angle})) "
+        "REPRESENTATION_CONTEXT('Context3D','3D'))"
+    )
+    items = ",".join(f"#{i}" for i in [axis, *solids])
+    rep = s.add(f"ADVANCED_BREP_SHAPE_REPRESENTATION('',({items}),#{ctx})")
+    app = s.add("APPLICATION_CONTEXT('core data for automotive mechanical design processes')")
+    s.add(
+        f"APPLICATION_PROTOCOL_DEFINITION('international standard','automotive_design',2000,#{app})"
+    )
+    pdc = s.add(f"PRODUCT_DEFINITION_CONTEXT('part definition',#{app},'design')")
+    prc = s.add(f"PRODUCT_CONTEXT('',#{app},'mechanical')")
+    prod = s.add(f"PRODUCT('{name}','{name} (generic placeholder)','',(#{prc}))")
+    form = s.add(f"PRODUCT_DEFINITION_FORMATION('','',#{prod})")
+    pdef = s.add(f"PRODUCT_DEFINITION('design','',#{form},#{pdc})")
+    pshape = s.add(f"PRODUCT_DEFINITION_SHAPE('','',#{pdef})")
+    s.add(f"SHAPE_DEFINITION_REPRESENTATION(#{pshape},#{rep})")
+    stamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S")
+    return (
+        "ISO-10303-21;\nHEADER;\n"
+        "FILE_DESCRIPTION(('Traceforge generic placeholder model, not the real package'),'2;1');\n"
+        f"FILE_NAME('{name}.step','{stamp}',('Traceforge'),(''),'Traceforge','Traceforge','');\n"
+        "FILE_SCHEMA(('AUTOMOTIVE_DESIGN { 1 0 10303 214 1 1 1 1 }'));\nENDSEC;\nDATA;\n"
+        + s.text()
+        + "\nENDSEC;\nEND-ISO-10303-21;\n"
+    )
+
+
+def generate_model(
+    board: Path, ref: str, format: str = "step", out_dir: Path | None = None
+) -> dict:
+    """Write a generic placeholder model for footprint ``ref`` (files named ``*_generic``)."""
+    if format not in {"step", "wrl"}:
+        raise ModelError("format must be 'step' or 'wrl'")
+    board = Path(board)
+    fp = edit.footprints(edit.load(board)).get(ref)
+    if fp is None:
+        raise ModelError(f"no footprint {ref!r} on the board")
+    lib_id = _lib_id(fp) or ref
+    body = generic_body(fp)
+    stem = re.sub(r"[^A-Za-z0-9_.+-]+", "_", lib_id.partition(":")[2] or lib_id) + "_generic"
+    out_dir = Path(out_dir) if out_dir else board.parent / "3dmodels"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    target = out_dir / f"{stem}.{format}"
+    text = step_text(body, stem) if format == "step" else wrl_text(body, lib_id)
+    target.write_text(text, encoding="utf-8")
+    return {
+        "ref": ref,
+        "file": str(target),
+        "format": format,
+        "body_mm": list(body.size),
+        "height_basis": body.height_basis,
+        "pins": body.pins,
+        "note": "generic placeholder sized from the footprint, not the real package",
+    }
+
+
+def assign_generic(board: Path, ref: str, format: str = "step", *, overwrite: bool = False) -> dict:
+    """Generate a placeholder for ``ref`` and assign it (safe by default, like assign_model)."""
+    fp = edit.footprints(edit.load(Path(board))).get(ref)
+    if fp is not None and find_all(fp, "model") and not overwrite:
+        return {
+            "ref": ref,
+            "status": "kept",
+            "note": "footprint already has a model; pass overwrite=true to replace it",
+        }
+    made = generate_model(board, ref, format)
+    return {**made, **assign_model(board, ref, Path(made["file"]), overwrite=overwrite)}
+
+
+# ---------------------------------------------------------------------------- render
+
+
+class RenderError(RuntimeError):
+    """3D rendering is not available or failed."""
+
+
+def supports_render(cli: KicadCli | None = None) -> bool:
+    """True when ``kicad-cli pcb render`` exists (KiCad 8 or later)."""
+    cli = cli or KicadCli()
+    if not cli.available:
+        return False
+    try:
+        return cli.run(["pcb", "render", "--help"]).returncode == 0
+    except KicadCliError:
+        return False
+
+
+def render_3d(
+    pcb: Path,
+    out: Path,
+    side: str = "top",
+    *,
+    width: int = 1600,
+    height: int = 900,
+    quality: str = "basic",
+    background: str = "opaque",
+    perspective: bool = False,
+    zoom: float | None = None,
+    cli: KicadCli | None = None,
+) -> Path:
+    """Render the board to a PNG with ``kicad-cli pcb render``.
+
+    Raises :class:`RenderError` when kicad-cli is missing or is KiCad 7 (which has no such
+    command). Models that do not resolve show as bare pads in the render.
+    """
+    if side not in {"top", "bottom"}:
+        raise RenderError("side must be 'top' or 'bottom'")
+    cli = cli or KicadCli()
+    if not cli.available:
+        raise RenderError("kicad-cli was not found; 3D rendering needs KiCad 8 or later")
+    try:
+        version = cli.version()
+    except KicadCliError as exc:
+        raise RenderError(str(exc)) from exc
+    if version < (8, 0, 0) or not supports_render(cli):
+        raise RenderError(
+            f"kicad-cli {'.'.join(map(str, version))} has no `pcb render` command; "
+            "3D rendering needs KiCad 8 or later"
+        )
+    out = Path(out)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    args = [
+        "pcb",
+        "render",
+        "--side",
+        side,
+        "--width",
+        str(int(width)),
+        "--height",
+        str(int(height)),
+    ]
+    args += ["--quality", quality, "--background", background, "-o", str(out)]
+    if perspective:
+        args.append("--perspective")
+    if zoom:
+        args += ["--zoom", str(zoom)]
+    args.append(str(Path(pcb)))
+    try:
+        completed = cli.run(args)
+    except KicadCliError as exc:
+        raise RenderError(str(exc)) from exc
+    if completed.returncode != 0 or not out.is_file():
+        detail = (completed.stderr or completed.stdout).strip()[-1500:]
+        raise RenderError(f"kicad-cli pcb render failed (exit {completed.returncode}): {detail}")
+    return out