FacereDataset/docs/sources/epro2_to_std_mapping.md

EPRO2 / Pro 2.x OPTYPE → EasyEDA Std shape verb mapping

For downstream adapters that consume tools/epro2/std/'s Option-2 output (raw objects: {id: payload} dict in the dataStr field) and need to produce real Std shape[] tilde strings.

This table is the same mapping our previous Phase-3 writer encoded inline (fe6971f:tools/epro2/std/pcb_writer.py); we extracted it here so adapter authors don't have to reverse-engineer it from the writer source.

All EPRO2 coordinate fields are in mil; Std dataStr.canvas declares mil as its unit, so the adapter copies coords through unchanged.

Layer id remapping

EPRO2 and Std agree on most copper layer ids, but differ on the mask / paste layers (5↔7 swapped) and have different numbering for OUTLINE / MULTI / inner SIGNAL.

EPRO2 id	EPRO2 type	Std id	Std name
1	TOP	1	TopLayer
2	BOTTOM	2	BottomLayer
3	TOP_SILK	3	TopSilkLayer
4	BOT_SILK	4	BottomSilkLayer
5	TOP_SOLDER_MASK	7	TopSolderMaskLayer
6	BOT_SOLDER_MASK	8	BottomSolderMaskLayer
7	TOP_PASTE_MASK	5	TopPasteMaskLayer
8	BOT_PASTE_MASK	6	BottomPasteMaskLayer
9	TOP_ASSEMBLY	13	TopAssembly
10	BOT_ASSEMBLY	14	BottomAssembly
11	OUTLINE	10	BoardOutLine
12	MULTI (THT pads)	11	Multi-Layer
13	DOCUMENT	12	Document
14	MECHANICAL	15	Mechanical
15..46	SIGNAL inner (in use)	21..50	Inner1..InnerN

The 21..50 inner mapping is dense — assign Std 21 to the lowest-numbered EPRO2 SIGNAL id actually carrying geometry on this board, 22 to the next, etc. EPRO2 SIGNAL layers declared in LAYER ops but unused don't need a Std slot.

PCB OPTYPE → Std shape verb (docType=3)

LINE (copper trace, silk line, ...) → TRACK

TRACK~width~layer~net~points~uuid~locked

• width ← LINE.width (mil)
• layer ← _layer(LINE.layerId) via the table above
• net ← LINE.netName (string, may be empty for non-net graphics)
• points ← "<startX> <startY> <endX> <endY>" (mil, space-separated)
• uuid ← any unique gge<8 hex> id; downstream usually mints fresh
• locked ← 0

EPRO2 doesn't distinguish copper trace from silk line at the op level — both are LINE with a different layerId. Std uses TRACK for both; the layer id is what disambiguates.

VIA → VIA

VIA~x~y~outerD~net~innerD~uuid~locked

• x y ← VIA.centerX/centerY
• outerD ← VIA.viaDiameter
• innerD ← VIA.holeDiameter
• net ← VIA.netName

POUR → COPPERAREA

COPPERAREA~1~layer~net~svgPath~strokeWidth~~~~~~~uuid~locked

• 1 is the id slot Std uses; any int works
• svgPath ← convert POUR.path to SVG M..L..Z string. Three EPRO2 path encodings:
  • rectangle [['R', x, y, w, h, ...]] → 4-corner closed polygon
  • circle [['CIRCLE', cx, cy, r]] → 24-segment polygon approximation
  • polyline [[x1, y1, 'L', x2, y2, ..., 'ARC', radius, endX, endY, ...]] → walk numeric pairs as M x y (first) / L x y (rest); ARC verbs chord-approximate to L endX endY (good enough for fill connectivity, Phase-2 sticks with this; precise arc chord recovery is a follow-up)
• strokeWidth ← POUR.width

FILL (manual filled region) → SOLIDREGION

SOLIDREGION~99~~svgPath~solid~uuid~~~~locked

• Same SVG-path encoding as COPPERAREA
• 99 is the id slot; the ~~ after it is an empty layer field (FILL on EPRO2 carries layerId but Std SOLIDREGION leaves it blank for "uses the path's natural color"; this is fine for downstream)

POLY with path[0] == 'CIRCLE' → CIRCLE

CIRCLE~cx~cy~radius~strokeWidth~layer~uuid~locked~~

POLY with polyline path → SOLIDREGION (graphic polygon)

Same as FILL.

COMPONENT (+ its FOOTPRINT.PADs) → LIB...#@$PAD...#@$TEXT...

The Std LIB shape is one outer string plus N inner shapes joined by the literal three-byte separator #@$. The outer carries placement; each inner is a real PAD / TEXT shape with the PCB-absolute coords that result from rotating + translating the FOOTPRINT-local pad positions.

Outer:

LIB~x~y~package_name`~rotation~~uuid~display~~~locked~~yes~~

• x y ← COMPONENT.x/y (mil)
• package_name ← FOOTPRINT META.title (then a literal trailing backtick)
• rotation ← COMPONENT.angle (degrees)
• display 1, locked 0

Inner PAD (one per FOOTPRINT.PAD owned by this COMPONENT):

PAD~shape~x~y~width~height~layer~net~num~drillSize~~rotation~uuid~0~~Y~0~0~0.2~x,y

• shape ← defaultPad.padType ∈ {RECT, ELLIPSE, OVAL, POLYGON}
• x y ← absolute coords:

  abs_x = comp.x + pad.centerX * cos(comp.angle) − pad.centerY * sin(comp.angle)
  abs_y = comp.y + pad.centerX * sin(comp.angle) + pad.centerY * cos(comp.angle)
  

• width height ← defaultPad.width/height
• layer ← _layer(pad.layerId) (typically 1=TOP, 2=BOTTOM, 11=Multi for THT)
• net ← resolve via PCB-level PAD_NET op: the PCB doc has ops with composite ids ["PAD_NET", <component_id>, <pin_num>, <pad_id>] → padNet payload is the net name. Cross-doc lookup; the FOOTPRINT itself doesn't know the net of any specific instance.
• num ← pad.num (pin number, string)
• drillSize ← pad.hole.width if hole present, else 0
• rotation ← (pad.padAngle + comp.angle) % 360

Inner TEXT (designator + value, one each if attrs present):

TEXT~P~x~y~strokeWidth~rotation~mirror~layer~font~size~content~svgPath~visible

• P flag = property text (vs L for label)
• content ← attrs.Designator / attrs.Value pulled from ATTR ops with parentId = component_id

The downstream adapter doesn't need a separate ATTR walk — by the time it has the COMPONENT's ATTR-derived attrs (Designator, Value, Footprint, ...), those are typically already collapsed into a attrs_dict map (tools.epro2.relations.Relations.attrs_dict(parent_id) does this).

Schematic OPTYPE → Std verb (docType=1, best-effort)

We have zero Std schematic samples in data/raw/oshwhub/*/source/ (all the projects we crawled are PCB-only Std exports), so the field orders below follow the EasyEDA Std public schematic spec, not direct observation. Adapter authors should expect to tweak field positions if their parser rejects a verb.

LINE → W (wire segment)

W~strokeColor~strokeWidth~strokeStyle~points~uuid~locked

• points ← same <x1> <y1> <x2> <y2> form as TRACK

LINE.lineGroup with parent WIRE.NET attr → also emit N (net flag)

N~x~y~rotation~text~uuid~locked

EPRO2 binds wire segments by NET name, not just geometry. Place one N flag at each LINE's start endpoint, with the text set to the parent WIRE op's NET ATTR value. Same-named flags on physically distinct wire segments is how Std unifies a multi-segment named net.

COMPONENT (+ its SYMBOL primitives) → LIB...#@$P...

Outer:

LIB~x~y~package`<symbol_title>`~rotation~~uuid~display~~~locked~~yes~~

Inner per SYMBOL.PIN:

P~show~0~~x~y~rotation~uuid^^pin_number^^pin_name^^length

(Note: PIN field separator inside the inner string uses ^^ not ~, per spec — but this varies by editor version. If downstream's parser rejects PIN, this is the most likely culprit.)

Power-port placeholder → LIB + extra N

EPRO2 represents power rails (VBUS / GND / VCC / VBAT_IN / ...) as a generic placeholder COMPONENT with partId = "pid8a0e77bacb214e" whose Global Net Name ATTR carries the rail name. For each such instance, emit the regular LIB placement plus an N flag at the placement coords with the Global Net Name as text — that's how the symbol's pin binds to the global rail. (This mirrors the same fix our KiCad path uses to emit a (global_label) for these.)

TEXT → T

T~x~y~rotation~text~uuid~locked

Skipped / "not yet supported"

These exist in EPRO2 but our writer doesn't address them — adapters can choose to skip silently or emit best-effort placeholders:

EPRO2 op	Std target	Notes
TEARDROP	(drop)	Cosmetic fillets at via/pad-trace junctions
ARC (PCB)	ARC	Std verb exists; we emit only chord-approximated ones
IMAGE	SVGNODE	Bitmap logos; Std stores as embedded SVG JSON
STRING (PCB)	TEXT	Board-level text; field order distinct from PCB TEXT-in-LIB
BUS / BE (SCH)	BUS / BE	Bus + bus entry — no EPRO2 sample in our corpus

Pro 2.x source format

Pro 2.x projects (lceda Pro editor 2.x — Liangshan Pi, Taishan Pi RK3566 in our corpus) use a different on-disk format than Pro 3.x EPRO2, even though both come out of the same crawler. Detection: the source/manifest.json file has "editor_version": "2.x.x". Our exporter auto-detects this and emits the same Std envelope, but with two key differences the adapter must branch on:

• result.dataStr.head.epro_format = "pro2" (vs absent / "epro2" for Pro 3.x). This is the canonical dispatch field.
• result.dataStr.objects values are JSON arrays, not the {"_type": ..., **fields} dicts EPRO2 produces. The first array element is the OPTYPE (["COMPONENT", "e1", "", 0, 0, 90, ...]).

Pro 2.x op vocabulary overlaps EPRO2 but adds editor-specific helpers: FONTSTYLE / LINESTYLE (referenced by id from text/stroke ops), CONNECT (sch wire-end to pin binding), OBJ (group container), REGION (sch background fills), DIMENSION (sch annotation), STRING (PCB board-level text — distinct from PCB TEXT), TEARDROP (cosmetic fillets at via/pad).

Field positions per OPTYPE follow the public EasyEDA Pro 2.x spec (versioned via the leading ["DOCTYPE","SCH","1.1"] / ["DOCTYPE", "PCB","1.4"] op). Our writer doesn't translate them — adapter dispatches by arr[0] (OPTYPE) and walks the rest by index.

Encrypted-external PCB blobs

Some Pro 2.x PCB docs (and a handful of resource docs) replace the inline dataStr field with {"dataStrId": "https://modules.lceda.cn/...", "iv": "...", "key": "..."} — the actual op-stream lives at the URL, AES-decrypted with the iv+key. Our exporter skips these; the source/<uuid>.json files still hold the dataStrId/iv/key so a future fetch+decrypt pass can recover them. Taishan PCB is the example in our corpus.

Provenance fields the adapter can rely on

In addition to objects, our writer always emits:

• result.dataStr.head.docType "3" (PCB) or "1" (SCH) — same string encoding Std uses
• result.dataStr.head.units "mil" — explicit unit hint so the adapter doesn't have to guess
• result.dataStr.head.editorVersion "facere-epro2/0.1 (epro2 X.Y.Z)" where X.Y.Z is the EPRO2 doc's editVersion. Useful for triage when a board exhibits version-specific quirks.
• result.dataStr.BBox {x, y, width, height} — gross outer rectangle from min/max of every numeric x/y/startX/startY/endX/endY/centerX/centerY field across objects. Adapters that want a tighter BBox can refine by walking path arrays themselves.