pcb-svg

Usage

kicad-cruncher pcb-svg board.kicad_pcb
kicad-cruncher pcb-svg project.kicad_pro --views assembly-top
kicad-cruncher pcb-svg board.kicad_pcb --config pcb.svg.config -o output/pcb-svg
kicad-cruncher pcb-svg board.kicad_pcb --layers F.Cu,Edge.Cuts --views layers

Arguments

file accepts .kicad_pcb or .kicad_pro. When omitted, the command attempts auto-detection when exactly one KiCad project or PCB file exists in the current directory. --config selects a pcb.svg.config.a0 JSON/JSONC config file; when omitted, pcb.svg.config next to each input is used or created. --doc selects the board file for project inputs. --views filters configured views and layer outputs. --layers filters layer-output tokens. -o selects the output directory directly.

Output

When -o is omitted, artifacts are written under ./output/pcb-svg/. The command writes one <board>__views.json manifest, optional per-layer SVGs under layers/, and configured view SVGs under views/. Each view is composed in layer-token order from kicad-monkey enriched physical SVG groups plus explicit virtual layers. The root SVG records data-compositor-schema="kicad_cruncher.pcb_svg.compositor.a0" and data-layer-tokens.

Virtual Layers

BOARD_OUTLINE and BOARD_CUTOUTS are synthesized from board-level Edge.Cuts geometry. Closed gr_line/gr_arc loops, gr_rect, gr_circle, and gr_poly regions are sampled as closed regions; the largest closed region is treated as the board outline, and smaller closed regions inside it become cutouts. Arc, curve, and circle smoothness for derived board regions is controlled by styles.board_outline.max_arc_segment_mm, max_curve_segment_mm, max_circle_segment_mm, and their segment caps; smaller segment lengths produce smoother but larger SVG paths. Cutouts carry data-layer-key="BOARD_CUTOUTS", data-feature="board-cutout", source-kind/source-UUID metadata, and the default hatch pattern board-cutout-hatch.

DRILLS and SLOTS clone the existing kicad-monkey enriched pad-hole and via-hole groups, preserving canonical data-hole-kind, data-hole-plating, owner, dimensions, component, pad, net, and layer metadata. PIN1_TOP and PIN1_BOTTOM synthesize marker circles from footprint and pad model coordinates. Pad selection order is component override, pad 1, pad A1, grid-style fallback, then first pad. Global or per-view pin1 config can exclude single-pin footprints plus exact designators, numeric ranges such as U5-U15, and prefixes such as U or U*; generated defaults exclude single-pin parts plus R and C. Marker diameter can be a fixed value or a ratio of the selected pad size.

ASSEMBLY_DESIGNATORS_TOP and ASSEMBLY_DESIGNATORS_BOTTOM draw fitted component reference text over assembly views. Text bounds follow pad bounds when the view uses pad_bounds, and transformed STEP model bounds when model/HLR projection is selected. Text rotates 90 degrees when fitted bounds height/width exceeds assembly_designators.rotation_aspect_threshold, default 1.5, in the configured assembly_designators.rotation_direction direction. Designator color, font, fit ratio, opacity, aspect threshold, and direction are configurable globally, per view, per component through components.<designator>.assembly_designators, or by exact/prefix/wildcard/range selectors through assembly_designators.selector_overrides, while preserving glyph aspect ratio.

HLR

ASSEMBLY_HLR_TOP and ASSEMBLY_HLR_BOTTOM append component assembly geometry after physical and virtual layer composition. KiCad Cruncher computes the KiCad model-to-board transform from the footprint pose, side, board thickness, and model offset/rotation/scale, then passes that complete transform to wn-geometer for STEP projection and model bounds. The configured modes are detail, simple, bounding_box, model_bounds, pad_bounds, and none. bounding_box uses transformed STEP model bounds when a model is available and falls back to pad bounds. model_bounds emits only transformed STEP bounds. pad_bounds emits the 2D bounds of copper-bearing pads and does not require a STEP model. Exact components.<designator>.projection overrides the view mode for one component, and components.<designator>.assembly_hlr merges over the resolved global/view HLR style for that component. The default assembly overlay opacity is 0.75.

The current Geometer HLR result exposes flattened SVG-ready segments and arcs for simple and detail. It does not yet expose projected loop IDs, face IDs, edge classifications, or an explicit outer-contour mode. A true silhouette-only assembly view should be implemented either by adding an outer projected contour API to Geometer or, if needed, by a KiCad Cruncher post-process that reconstructs closed loops and drops contained loops from the flattened primitives.

Tests

L0 verifies command registration and help. L3 runs pcb-svg against copied public KiCad corpus boards with explicit pcb.svg.config.a0 files, checking the manifest, layer SVG output, configured view output, virtual cutout extraction, pin-1 marker synthesis, enriched drill metadata, and geometer-backed HLR overlay markers.