Facere/FacereDataset
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

tools/epro2/kicad: Phase-1 EPRO2 → KiCad schematic exporter

Browse Source 
写第一版 EPRO2 → .kicad_sch 转换：把 SCH_PAGE Document 的 wires +
COMPONENT placements + TEXT 输出到一个可被 KiCad 7+ 打开的 sch 文件。
不含 symbol 主体（lib_symbols 留空 stub），所以 KiCad 里组件会渲染
成红色 "?" 占位，但布线 + 位置 + Designator/Value 属性都正确。完整
symbol 库导出留 Phase 2。

模块结构：
  tools/epro2/kicad/sexpr.py        手写 S-expr emitter，Sym 标记裸符号，
                                    str 自动加引号 + 转义；float 去尾零；
                                    bool→yes/no；NaN/Inf 主动报错
  tools/epro2/kicad/_sexpr_reader.py  极简 S-expr parser，仅给 round-trip
                                    测试用（非完整 KiCad reader）
  tools/epro2/kicad/sch_writer.py   write_sch_page(doc) → str；处理：
                                      LINE  → (wire (pts ...) ...)
                                      COMPONENT → (symbol (lib_id facere:<partId>)
                                                  (at x y rot) (property Reference ...) ...)
                                      TEXT  → (text "..." (at ...))
                                    单位 mil → mm × 0.0254；零长 wire 跳过
  tools/epro2/kicad/__main__.py     CLI: --doc <uuid> | --all-sch

ESP-VoCat 验证（python -m tools.epro2.kicad <project> --all-sch）：
  9 SCH_PAGE 全部转换成功
  P1_408c9f4f.kicad_sch    wires=  6  symbols= 10  text=  0  skipped= 2  (370 lines)
  P1_ee409917.kicad_sch    wires= 20  symbols= 14  text=  0  skipped= 3
  P1_54743d77.kicad_sch    wires= 42  symbols= 30  text=  3
  Overview_dc13d6d2.kicad_sch wires=  0  symbols=  1  text= 34   (说明页)
  MCU_510cff33.kicad_sch   wires= 91  symbols= 86  text=  9
  Interface_b336a7c7.kicad_sch wires= 99  symbols= 95  text=  6
  P1_5c38f45b.kicad_sch    wires=179  symbols= 86  text=  9
  P1_45092758.kicad_sch    wires=187  symbols=138  text= 10  (主图)
  codec_0b0163fa.kicad_sch wires=190  symbols=112  text= 10

输出落在 data/processed/kicad_sch/<filename>.kicad_sch（gitignore 内，
可重新生成；不入库）。

测试：6 个 sexpr 测 + 6 个 sch_writer 测，含 round-trip parse 验证。
parser/relations/project_relations 的旧 21 个不动，合计 **33/33 通过**。

下一步：
1. Phase 2 — symbol library 导出 (.kicad_sym)，把 SYMBOL doc 的 PIN/RECT/
   TEXT primitives 转 KiCad symbol 主体；填 lib_symbols 块让组件渲染
   出真正的 schematic 符号
2. footprint library + .kicad_pcb 导出
3. 用 KiCad CLI (kicad-cli sch erc) 跑 ERC 校验

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Knowit
2026-04-28 22:29:15 +08:00
parent 3052e42991
commit 9213429a57
7 changed files with 615 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
tools/epro2/kicad/__init__.py Normal file
View File

@@ -0,0 +1,20 @@
"""KiCad export from EPRO2.
Phase 1 (current): schematic only — paper, wires, junctions, symbol placements
without symbol bodies. Output is a single .kicad_sch file
that KiCad will open (showing wires + placeholders for
missing symbols).
Phase 2 (planned): symbol library export (.kicad_sym) from SYMBOL docs;
wire it via lib_symbols block in the .kicad_sch.
Phase 3 (planned): footprint library + .kicad_pcb generation.
Coordinates: EasyEDA schematic stream stores in **mil** internally; KiCad uses
mm. Conversion factor ``MIL_TO_MM = 0.0254`` is applied at writer level.
"""
from .sch_writer import write_sch_page # noqa: F401
from .sexpr import Sym, to_sexpr # noqa: F401
__all__ = ["Sym", "to_sexpr", "write_sch_page"]

83
tools/epro2/kicad/__main__.py Normal file
View File

@@ -0,0 +1,83 @@
"""CLI: convert EPRO2 SCH_PAGE docs to KiCad ``.kicad_sch`` files.
Usage:
uv run python -m tools.epro2.kicad <project_dir> --doc <sch_uuid> --out <dir>
uv run python -m tools.epro2.kicad <project_dir> --all-sch --out <dir>
The ``--all-sch`` form converts every SCH_PAGE in the project, naming each
output by its document title (or doc_uuid prefix as fallback).
"""
from __future__ import annotations
import argparse
import re
import sys
from pathlib import Path
from ..replay import Project, replay_project
from .sch_writer import write_sch_page
_SAFE_CHARS = re.compile(r"[^A-Za-z0-9._\-一-鿿]+")
def _safe_filename(s: str) -> str:
s = _SAFE_CHARS.sub("_", s).strip("_")
return s or "untitled"
def _convert_one(proj: Project, doc_uuid: str, out_dir: Path) -> Path:
if doc_uuid not in proj.documents:
candidates = [u for u in proj.documents if u.startswith(doc_uuid)]
if len(candidates) != 1:
raise SystemExit(f"no unique match for {doc_uuid!r} (candidates: {candidates[:5]})")
doc_uuid = candidates[0]
doc = proj.documents[doc_uuid]
if doc.doc_type != "SCH_PAGE":
raise SystemExit(f"doc {doc_uuid} is {doc.doc_type!r}, not SCH_PAGE")
text = write_sch_page(doc)
title = (doc.objects.get("META") or {}).get("title") or doc_uuid[:12]
out_path = out_dir / f"{_safe_filename(title)}_{doc_uuid[:8]}.kicad_sch"
out_path.write_text(text, encoding="utf-8")
stats = getattr(write_sch_page, "last_stats", None)
if stats:
print(
f" {out_path.name}: wires={stats.wires} symbols={stats.symbol_placements} "
f"text={stats.text} skipped={stats.skipped}"
)
return out_path
def main(argv: list[str] | None = None) -> int:
ap = argparse.ArgumentParser(description="EPRO2 → KiCad schematic exporter (Phase 1)")
ap.add_argument("project_dir", type=Path)
g = ap.add_mutually_exclusive_group(required=True)
g.add_argument("--doc", help="SCH_PAGE doc uuid (or unique prefix) to convert")
g.add_argument("--all-sch", action="store_true", help="convert every SCH_PAGE")
ap.add_argument("--out", type=Path, default=Path("data/processed/kicad_sch"))
args = ap.parse_args(argv)
proj = replay_project(args.project_dir)
args.out.mkdir(parents=True, exist_ok=True)
if args.doc:
_convert_one(proj, args.doc, args.out)
return 0
targets = [u for u, d in proj.documents.items() if d.doc_type == "SCH_PAGE"]
if not targets:
print("no SCH_PAGE docs in this project", file=sys.stderr)
return 1
print(f"Converting {len(targets)} SCH_PAGE docs → {args.out}")
for u in targets:
try:
_convert_one(proj, u, args.out)
except Exception as e: # noqa: BLE001
print(f" FAIL {u[:12]}: {e}", file=sys.stderr)
return 0
if __name__ == "__main__":
raise SystemExit(main())

88
tools/epro2/kicad/_sexpr_reader.py Normal file
View File

@@ -0,0 +1,88 @@
"""Tiny S-expression parser used by tests for round-trip validation.
Not a full KiCad reader — just enough to confirm our writer output is
syntactically valid Lisp-flavored S-expr (balanced parens, quoted strings,
numbers, symbols).
"""
from __future__ import annotations
from typing import Iterator
def tokens(src: str) -> Iterator[str]:
i, n = 0, len(src)
while i < n:
c = src[i]
if c.isspace():
i += 1
continue
if c == "(":
yield "("
i += 1
continue
if c == ")":
yield ")"
i += 1
continue
if c == '"':
j = i + 1
buf = []
while j < n:
ch = src[j]
if ch == "\\" and j + 1 < n:
nxt = src[j + 1]
buf.append({"\\": "\\", '"': '"', "n": "\n", "t": "\t"}.get(nxt, nxt))
j += 2
continue
if ch == '"':
break
buf.append(ch)
j += 1
if j >= n:
raise SyntaxError("unterminated string")
yield '"' + "".join(buf) + '"'
i = j + 1
continue
# bare token until whitespace or paren
j = i
while j < n and not src[j].isspace() and src[j] not in "()":
j += 1
yield src[i:j]
i = j
def parse(src: str):
it = iter(tokens(src))
def _read(tok):
if tok == "(":
out = []
while True:
try:
nxt = next(it)
except StopIteration:
raise SyntaxError("unterminated list")
if nxt == ")":
return out
out.append(_read(nxt))
if tok == ")":
raise SyntaxError("unexpected )")
if tok.startswith('"') and tok.endswith('"'):
return tok[1:-1]
try:
return int(tok)
except ValueError:
try:
return float(tok)
except ValueError:
return tok # symbol
try:
first = next(it)
except StopIteration:
raise SyntaxError("empty input")
val = _read(first)
# Expect EOF
for extra in it:
raise SyntaxError(f"unexpected trailing token: {extra!r}")
return val

186
tools/epro2/kicad/sch_writer.py Normal file
View File

@@ -0,0 +1,186 @@
"""Convert one EPRO2 SCH_PAGE Document → a KiCad ``.kicad_sch`` S-expr.
Phase-1 scope: paper + wires + junctions + symbol placements (no symbol body
bundled in lib_symbols). KiCad will render the resulting .kicad_sch with
visible wires/junctions but the symbol instances will appear as red question
marks until lib_symbols is populated (next phase).
Coordinate system:
- EPRO2 schematic uses **mil** as its internal unit.
- KiCad uses **mm**, with origin top-left, +Y down.
- Y-axis already aligned (both Y-down), so we just apply ``MIL_TO_MM``.
- We additionally translate so that the schematic's own bounding box has
a small margin from page origin — keeps everything visible on A4.
"""
from __future__ import annotations
import math
import uuid as _uuid
from dataclasses import dataclass
from ..relations import Relations
from ..replay import Document
from .sexpr import Sym, to_sexpr
MIL_TO_MM = 0.0254
# KiCad sch S-expr metadata that doesn't depend on content.
KICAD_SCH_VERSION = 20231120
KICAD_GENERATOR = "facere-epro2"
# Default A4 in mm (KiCad uses these by default for "A4").
PAPER_A4_MM_W = 297.0
PAPER_A4_MM_H = 210.0
@dataclass
class WriteStats:
wires: int = 0
junctions: int = 0
symbol_placements: int = 0
text: int = 0
skipped: int = 0
def _new_uuid() -> str:
return str(_uuid.uuid4())
def _mil(v) -> float:
"""Coerce an EPRO2 mil value to mm. None / non-numeric → 0.0."""
if v is None:
return 0.0
try:
return float(v) * MIL_TO_MM
except (TypeError, ValueError):
return 0.0
def _stroke(width: float = 0.0, kind: str = "default") -> list:
return [Sym("stroke"), [Sym("width"), width], [Sym("type"), Sym(kind)]]
def write_sch_page(
doc: Document,
*,
title: str | None = None,
sheet_origin_mm: tuple[float, float] = (25.4, 25.4),
) -> str:
"""Render a single SCH_PAGE Document as kicad_sch text.
``sheet_origin_mm`` is added to every coordinate so the schematic doesn't
sit at (0,0) (KiCad's title block lives there). Default 1 inch margin.
"""
if doc.doc_type != "SCH_PAGE":
raise ValueError(f"expected SCH_PAGE doc, got {doc.doc_type!r}")
rel = Relations.build(doc)
stats = WriteStats()
ox, oy = sheet_origin_mm
elements: list = []
# 1. Wires from LINE primitives. Each LINE contributes one (wire ...).
for oid, obj in doc.objects.items():
if obj.get("_type") != "LINE":
continue
x1 = ox + _mil(obj.get("startX"))
y1 = oy + _mil(obj.get("startY"))
x2 = ox + _mil(obj.get("endX"))
y2 = oy + _mil(obj.get("endY"))
# KiCad rejects degenerate zero-length wires
if math.isclose(x1, x2) and math.isclose(y1, y2):
stats.skipped += 1
continue
elements.append([
Sym("wire"),
[Sym("pts"), [Sym("xy"), x1, y1], [Sym("xy"), x2, y2]],
_stroke(0.0),
[Sym("uuid"), _new_uuid()],
])
stats.wires += 1
# 2. Symbol placements from COMPONENT ops. Body deferred to Phase 2 (lib_symbols).
# For now we emit (symbol ...) entries that reference a placeholder lib_id.
# KiCad will draw a red ? but the position + properties are correct.
for cid, comp in rel.components.items():
x = ox + _mil(comp.get("x"))
y = oy + _mil(comp.get("y"))
rot = float(comp.get("rotation") or 0)
part_id = str(comp.get("partId") or "Unknown")
attrs = rel.attrs_dict(cid)
designator = str(attrs.get("Designator") or "")
value = str(attrs.get("Value") or "")
sym_block: list = [
Sym("symbol"),
[Sym("lib_id"), f"facere:{part_id}"],
[Sym("at"), x, y, rot],
[Sym("unit"), 1],
[Sym("exclude_from_sim"), Sym("no")],
[Sym("in_bom"), Sym("yes")],
[Sym("on_board"), Sym("yes")],
[Sym("dnp"), Sym("no")],
[Sym("uuid"), _new_uuid()],
[Sym("property"), "Reference", designator,
[Sym("at"), x, y - 5, 0],
[Sym("effects"), [Sym("font"), [Sym("size"), 1.27, 1.27]]]],
[Sym("property"), "Value", value,
[Sym("at"), x, y + 5, 0],
[Sym("effects"), [Sym("font"), [Sym("size"), 1.27, 1.27]]]],
[Sym("property"), "Footprint", "",
[Sym("at"), x, y, 0],
[Sym("effects"), [Sym("font"), [Sym("size"), 1.27, 1.27]],
[Sym("hide"), Sym("yes")]]],
[Sym("property"), "Datasheet", "",
[Sym("at"), x, y, 0],
[Sym("effects"), [Sym("font"), [Sym("size"), 1.27, 1.27]],
[Sym("hide"), Sym("yes")]]],
]
elements.append(sym_block)
stats.symbol_placements += 1
# 3. Text labels from TEXT objects (best-effort — only those with a non-empty value).
for oid, obj in doc.objects.items():
if obj.get("_type") != "TEXT":
continue
val = str(obj.get("value") or "").strip()
if not val:
continue
x = ox + _mil(obj.get("x"))
y = oy + _mil(obj.get("y"))
rot = float(obj.get("rotation") or 0)
elements.append([
Sym("text"),
val,
[Sym("at"), x, y, rot],
[Sym("effects"), [Sym("font"), [Sym("size"), 1.27, 1.27]]],
[Sym("uuid"), _new_uuid()],
])
stats.text += 1
sch_title = title or (
(doc.objects.get("META") or {}).get("title")
or doc.doc_uuid[:12]
)
sch: list = [
Sym("kicad_sch"),
[Sym("version"), KICAD_SCH_VERSION],
[Sym("generator"), KICAD_GENERATOR],
[Sym("uuid"), _new_uuid()],
[Sym("paper"), "A4"],
[Sym("title_block"),
[Sym("title"), sch_title],
[Sym("comment"), 1, f"epro2 doc_uuid: {doc.doc_uuid}"],
[Sym("comment"), 2, f"editor: {doc.head.get('editVersion','')}"]],
[Sym("lib_symbols")], # empty for Phase 1; Phase 2 will populate
*elements,
[Sym("sheet_instances"),
[Sym("path"), "/", [Sym("page"), "1"]]],
]
# Stash stats on the function for tests / CLI to inspect.
write_sch_page.last_stats = stats # type: ignore[attr-defined]
return to_sexpr(sch, pretty=True)

75
tools/epro2/kicad/sexpr.py Normal file
View File

@@ -0,0 +1,75 @@
"""Hand-rolled S-expression emitter for KiCad files.
KiCad reads a Lisp-flavored S-expr; values are atoms (symbols / strings /
numbers) and lists. We emit lists as nested Python lists, with ``Sym`` marking
strings that should serialize as bare symbols (unquoted) — e.g. ``Sym("xy")``,
``Sym("kicad_sch")``, ``Sym("yes")``.
Plain ``str`` values get JSON-style double-quoting + backslash escaping.
Floats render with up to 6 decimals trimmed of trailing zeros (KiCad reads
either form, but trimmed is what kicad-cli emits).
"""
from __future__ import annotations
import io
import math
from typing import Any
class Sym(str):
"""Marker subclass: render as a bare S-expr symbol (unquoted)."""
__slots__ = ()
def _fmt_number(n: float | int) -> str:
if isinstance(n, bool): # bool is int subclass — guard first
return "yes" if n else "no"
if isinstance(n, int):
return str(n)
if math.isnan(n) or math.isinf(n):
raise ValueError(f"can't serialize non-finite number: {n}")
s = f"{n:.6f}".rstrip("0").rstrip(".")
return s if s else "0"
def _emit(value: Any, out: io.StringIO, indent: int, *, pretty: bool) -> None:
if isinstance(value, list):
out.write("(")
for i, item in enumerate(value):
if i > 0:
if pretty and isinstance(item, list) and len(item) > 1:
out.write("\n" + "\t" * (indent + 1))
else:
out.write(" ")
_emit(item, out, indent + 1, pretty=pretty)
out.write(")")
elif isinstance(value, Sym):
out.write(str(value))
elif value is True or value is False:
out.write("yes" if value else "no")
elif isinstance(value, (int, float)):
out.write(_fmt_number(value))
elif isinstance(value, str):
escaped = value.replace("\\", "\\\\").replace('"', '\\"')
out.write(f'"{escaped}"')
elif value is None:
# rare but sometimes a slot is intentionally empty
out.write('""')
else:
raise TypeError(f"can't S-expr serialize {type(value).__name__}: {value!r}")
def to_sexpr(value: Any, *, pretty: bool = True) -> str:
"""Render a Python data structure as a KiCad-style S-expression.
Top-level value is usually a list whose first element is a ``Sym`` (the
block tag, e.g. ``Sym("kicad_sch")``). When ``pretty=True``, child lists
of length > 1 go onto their own indented line.
"""
buf = io.StringIO()
_emit(value, buf, indent=0, pretty=pretty)
if pretty:
buf.write("\n")
return buf.getvalue()