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 kicad_cruncher.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 when layer outputs are enabled. -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 and configured view SVGs under views/ by default. Standalone per-layer SVGs under layers/ are optional and are enabled by setting layer_outputs.enabled to true or by selecting layers with --views. Each view is composed in layer-token order from kicad-monkey enriched physical SVG groups plus explicit virtual layers. On the promoted Windows x64 production path, the physical base comes from the packaged native provider and failure is terminal; Linux and macOS retain the Python provider, while KICAD_CRUNCHER_NATIVE_PHYSICAL=1 is a development/test opt-in elsewhere. The root SVG records data-compositor-schema="kicad_cruncher.pcb_svg.compositor.a0" and data-layer-tokens.

Artifact publication is transactional: failed rendering leaves a new destination absent and preserves an existing destination exactly. A missing project-adjacent pcb.svg.config is intentionally authored before rendering and remains as configuration input even when artifact rendering fails.

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 family, font weight, 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. Fresh defaults generate only assembly_top_view and assembly_bottom_view; those views include board cutouts, drills, slots, pin-1 markers, Geometer outline HLR with hole-first bounds fallback, and bold monospace assembly designators. The configured modes are outline, detail, bounding_box, model_bounds, pad_bounds, and none. outline is the assembly silhouette mode and defaults to Geometer's mesh-shadow outline algorithm. detail renders the detailed visible projection. 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 footprint pads and holes 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.

Geometer projection results expose flattened SVG-ready segments and arcs for outline and detail, plus projected bbox geometry for direct model-bounds callers. KiCad Cruncher uses the outline/detail primitives for component overlays and the model-bounds API for rectangle fallback modes.

Roadmap

Remaining PCB SVG assembly follow-up is tracked by docs/pcb-svg/requirements/pcb-svg-req-001-assembly-validation-and-selectors.md. The active deferred items are manual HLR outline validation on hlr_test, a no-model synthetic pad_bounds test, and component selector groups for list, wildcard/prefix, and designator-range selection after exact overrides remain stable.

Tests

L0 verifies command registration and help. L3 runs pcb-svg against copied public KiCad corpus boards with explicit kicad_cruncher.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.

NativePhysicalProvider

Purpose: render a strict PCB Plotter-IR physical base through the packaged Monkey native process.

Rationale: native rendering owns the promoted Windows x64 physical base while Cruncher retains view composition and enrichment; failure is never retried through Python.

Test Requirements: prove exact native invocation, normalized viewport and identity, enrichment, bounded caching, and no fallback.

Working Definition: a validated native SVG artifact is normalized once and supplied to the compositor with bound provenance.

PhysicalSvgArtifact

Purpose: carry normalized physical SVG text together with its validated native provenance.

Rationale: keeping bytes and provenance coupled prevents composition or publication from losing the identity of the native result.

Test Requirements: verify normalized SVG structure and exact document/SVG hashes before cached reuse.

Working Definition: the artifact contains publishable normalized SVG and provenance for the same document and bytes.

PhysicalSvgProvenance

Purpose: record backend, engine, profile, document identity, byte count, and hashes for one native physical result.

Rationale: downstream manifests and tests need stable evidence that the selected provider—not an ambient Python renderer—created the base.

Test Requirements: assert exact backend/profile identities and hashes against the rendered document and normalized SVG.

Working Definition: every field is nonambient, deterministic, and bound to the returned physical artifact.