YHLLXY/gift-pcb

Commemorative Display Board (gift-pcb)

A PCB that is purely aesthetic—no circuitry required. The challenge lies not in the schematic but in three often-overlooked aspects: what the reference board actually looks like, the material of each layer, and the gap between "looks right" and "measures right."

Three Golden Rules

1. Look at layers, not composite images. Copper under solder mask appears black; only "copper + solder mask opening" appears gold.
2. Measure, don't guess. All "is it enough?" questions must be answered with actual millimeter/pixel measurements, written into the reply. Guessed numbers will be exposed on the third rework.
3. Copy first, then modify. Problems already solved in reference boards or official emblems—directly adopt their geometry; do not reinvent.

Eight Stages and Gates

Stage	Output	Gate (cannot proceed without passing)
P0 Project Initiation	Recipient, dimensions, finish, element list	Every element can answer "where does it go? how big?"
P0.5 Requirements Interview	Intended use, scenario, realistic/ornamental, hand-drawn drafts, budget	All 8 questions asked (see 06), especially "do you want a hand-drawn feel?"
P1 Decode Reference Board	Per-layer renderings + element list + three-color ratio table; if no reference board, search materials	① Can point to layers and explain which are copper/gold/silkscreen/holes; ② Ran scripts/00-decode_badge.py, output badge prototype (line art/disc) + radius + area + thinnest stroke; ③ If reference board exists, measure gold/white/black values; ④ Complete the ten-item copy checklist in 07 (each with measured numbers + user decides whether to copy)
P2 Layout	Front/back bitmap mockups	User approves layout; and declare "pre-rendering does not represent final result"
P3 Vectors and Manufacturability	Badge/text vectors, line width table, gold area budget	Minimum line width ≥ process limit; Gold 12–24%, White ≥0.3%, Matte Black 65–85%
P4 EDA Implementation	Project + board + each layer's graphics	After saving each layer, read back—graphic count matches plan
P4.5 3D Acceptance	Front/back 3D images from scripts/14-render3d.py + user item-by-item confirmation (C1: check defects / C2: check aesthetics / C3: need additional assets)	User says "it's good"—at least one round, ideally two; without approval, do not generate order package
P5 Export Review	Gerber package + order package	scripts/13-check.py all green (including gold/white/black ratios) + at least one ≥60 px/mm close-up view (human eye check)

P0.5 and P4.5 are the two most easily skipped—and most expensive—gates. The former determines if the design is correct; the latter determines if the user accepts it.

Quick Reference

What you need to do	Read this
What to ask the user before starting, how to accept 3D, how to calculate gold area	references/06-Requirements-Interview-and-Acceptance.md
Open reference board Gerber, determine each layer's identity	references/01-Reference-Board-Decoding.md
Line width, whether it can be fabricated, bitmap-to-vector conversion, scanline precision, weave pattern parameters	references/02-Manufacturability-and-Vectors.md
Need to apply a weave pattern (reproduce reference board weave texture)	scripts/15-weave.py (--extract can re-extract table from any reference board)
What to copy item by item from reference board (gold bands/hole groups/bleed/silkscreen levels…)	references/07-What-to-Copy-from-Reference-Board.md
Not enough materials, need to search online for images	references/08-Asset-Crawl-Plan.md + scripts/17-crawl_assets.py
Which images among many are suitable for the board	scripts/18-filter_assets.py (outputs a wall of thumbnails, human picks)
What to ask the user before starting (fillable form)	templates/Questionnaire.md
Don't know how to arrange layout	templates/layouts/ (three templates + 24 px/mm illustration)
Want to preview the spec without opening EDA	scripts/20-preview_spec.py
Write CLI/JS calls for EasyEDA Pro	references/03-EDA-Implementation.md
Don't want to add graphics one by one (write .epcb2 directly)	references/03-EDA-Implementation.md section 8
Badge is a solid color block with white cut-out text (disc type)	references/02-Manufacturability-and-Vectors.md "Two Badge Prototypes"
Generate 3D preview for user acceptance	scripts/14-render3d.py
Any step "looks weird," first check historical pitfalls	references/04-Pitfall-List.md (118 items, sections A–R)
Package for ordering, verify that this version is the accepted one	scripts/19-pack_order.py (MANIFEST + --verify)
After modifying scripts, verify the board isn't broken	python -m pytest tests -q (gold board reproduction / weave / self-check integrity)
Want to change fonts / can't run on different machine	references/02-Manufacturability-and-Vectors.md "Fonts"
Find reference materials, see similar skills from others	references/05-Reference-Resources.md

Before starting P4, you must read references/03. The most expensive mistake was guessing the parameter order of create() from memory, while the correct signature was always written in our own 03.

The 13 Most Expensive Lessons (full text in 04)

1. Gold = copper + solder mask opening; both layers are indispensable; Gold 12–24% (reference boards of same size: 22.0%, per 13-check metric—see 02 "Two Metrics"). Below 8% must be an empty board, above 26% means full-board gold plating.
2. Determine badge prototype before drawing: Line-art type → trace the entire badge; Disc type (solid color block + white cut-out text) → solid disc + text as black cutouts. Wrong prototype → text becomes burrs (that's how v3 was scrapped).
3. For complex glyphs, do not use polygon boolean operations; use rasterization + 0.06 mm scanlines; but Latin letters/numbers preferentially use text objects (vectors); scanlines only for Chinese characters, handwriting, and graphics.
4. Background textures must be clipped to the boundary (intersect with circles at rounded corners); don't discard partial crossing line segments entirely, otherwise the board edge will have a row of jagged gaps.
5. When background texture exists on the same layer, any bbox condition filtering must be combined with a size signature; otherwise, the texture will also be deleted.
6. Batch writes ≤600 per batch, sleep between batches, retry on failure, deduplicate by coordinate at the end; setState_* does not persist—geometry changes only trust modify().
7. All back layers (2/4/6) must be mirrored; bottom silkscreen is layer 4, not 3.
8. When the user says "doesn't look right," the problem is almost always in rules (arrangement, proportion, hierarchy), not in parameters; convert the reference board into numbers, not tune values.
9. After writing .epcb2, you must do session close --destroy then open; the editor does not reload disk changes automatically, so export will get old graphics (item 109).
10. The entire board can be written as .epcb2 text (one JSON line per entry, one FILL per path), which is orders of magnitude faster than batch CLI injection; but back-side text cannot rely on mirror:true—geometry must be mirrored.
11. For circles, always use path:["CIRCLE",cx,cy,r] + width; scanlines for circles will create notches with adjacent text.
12. "Copy everything you can"—but copy the numbers, not the impression. Board-edge gold band sits on the board outline (visible width = line width/2), hole group connects those φ0.3 small holes, graphics bleed beyond board edge, silkscreen three lines with three fonts, bottom horizontal line—measure each, fill the table in 07, ask the user whether to copy.
13. Self-check must be "script-generated table + at least one ≥60 px/mm close-up view"; 20 px/mm cannot see 0.06 mm defects; seeing one but writing "acceptable" is worse than not seeing it at all. Weave pattern is separate: must be 80 px/mm, viewing a single 12×12 mm area—it always looks like "a patch of gray" in composite images.

Deliverables (every final version must include)

• export/<name>_gerber_<date>_v<n>.zip
• preview/board-gerber<n>.png: Front/back each rasterized from Gerber and composited, not an EDA screenshot
• preview/v<n>_front3d.png / v<n>_back3d.png: Pseudo-3D from 14-render3d.py (matte black relief + gold reflections), for user's P4.5 acceptance
• docs/03-Current-Status.md: Layer statistics, geometry parameters, confirmed fixed items, pending items
• docs/Acceptance-Sheet.md: Measurement table from 13-check.py --md + P4.5 fourteen-item checklist (one per board, don't ask verbally)
• Order package: Gerber + preview images + project source files + Order-Instructions.txt (with measured data and known risks) + MANIFEST.txt (scripts/19-pack_order.py generates sha256; after extraction, run --verify to ensure consistency before ordering)

Self-Check (every deliverable, none optional)

1. Run scripts/13-check.py; all green before proceeding (dimensions / gold area / min line width / min silkscreen / white silkscreen / matte black / drill holes / graphic count / ring coverage). If the board has a weave pattern, add --weave: compare the orientation of each 2 mm cell on the board against the reference board's texture table; match rate ≥90% to consider copying correct. Also add --md docs/Acceptance-Sheet.md to write the numbers and P4.5 fourteen items into a file.
2. Generate a ≥60 px/mm close-up view, fixed on three areas: the badge, the main text, and one board corner.
3. Write the numbers from the two steps above into the reply—not "I checked it."
4. If defects found: fix them first, then decide whether to say "acceptable"—"acceptable" is not a repair plan.
5. The P4.5 3D images must actually be shown to the user (front + back, two images); not just "already rendered."