pcb-layer-step

Purpose

pcb-layer-step is a factory-test fixture alignment tool, not a full PCB-to-STEP exporter. The primary workflow is a device-under-test board with bottom-side test pads and a fixture or breakout board with spring-loaded pogo pins. The command produces a lightweight 3D reference model of the DUT layer so the fixture designer can place that model in the test-board CAD design and verify pogo-pin locations against DUT test pads.

Cricket Node is the reference use case. The useful model usually needs only the board outline for visual reference, selected bottom copper, and highlighted test-point pads. Dense via fields, complete pours, and full fabrication detail are optional because they often slow generation, increase STEP size, or distract from pogo alignment.

Usage

altium-cruncher pcb-layer-step --init-config --config pcb-layer-step.json
altium-cruncher pcb-layer-step board.PcbDoc --layer bottom --config pcb-layer-step.json -o output/step
altium-cruncher pcb-layer-step project.PrjPcb --doc board.PcbDoc --config pcb-layer-step.json

Arguments

file accepts a .PcbDoc or .PrjPcb. --init-config writes the JSONC template and exits without loading PCB or schematic data; --force-config allows that template to overwrite an existing file. CLI options select the PCB document, project-context mode, layer, output directory, Z offset, layer thickness, copper color, board-outline color and width, board-cutout color, polygon inclusion, board-outline/cutout inclusion, drill-hole mode, drill diameter filter, drill overlay shape, drill overlay colors, drill ring width, plated-ring source, and copper/outline fusion. CLI values override the active output config where both are supplied.

JSONC config controls the fixture-specific behavior: multi-output filenames, feature classes, component-designator filters, per-designator pad color rules, drill policy, and fusion defaults. --drill-hole-mode none omits drill visualization, cut subtracts hole regions from copper, overlay emits separate colored drill-reference bodies, and auto preserves the compatibility behavior of cutting small drill sets and using overlays for dense boards. The default project context is board-only, so .PrjPcb inputs do not parse .SchDoc files unless --project-context schematic or auto is requested.

Coordinates

The generated planar regions are normalized before Geometer sees them: source Altium absolute XY mils subtract the board placement origin (ORIGINX/ORIGINY) and are then converted to millimeters. This keeps the STEP model aligned to the same placement-origin-relative coordinate frame used when positioning the DUT reference in fixture CAD. The command should not apply fixture-board assembly translation or rotation; that remains a CAD-side assembly operation. Z placement is configurable through z_mm; it defines the bottom Z plane passed to Geometer for each emitted body. thickness_mm controls extrusion thickness.

Geometer Boundary

The command feeds Geometer geometry.planar_step.request.a0: colored planar bodies with z_mm, thickness_mm, closed regions, optional region holes, optional body cutouts, and optional fuse_regions. Geometer should remain PCB-agnostic. It should not know about designators, pads, vias, test points, polygons, board origins, or drill policy. Those decisions belong in altium_cruncher before request construction.

The first fixture-alignment feature set does not require Geometer changes. Annular drill rings can be represented as regions with holes. Designator-based colors can be represented by splitting geometry into multiple colored bodies. Whole-model fixture placement remains intentionally out of scope because the request is already normalized to the DUT board placement origin. Future Geometer enhancements may be useful for root/body transforms or per-region names/colors, but they are not release blockers for this command.

JSONC Config

The generated config is JSONC and includes block comments with editing guidance. The machine-readable contract is docs/contracts/pcb_layer_step_config.v2.schema.json. The target schema is a multi-output config: one file can define several outputs using an array of the same output configuration shape. A default section may provide shared values, but each output entry should be able to override layer, filename, colors, feature filters, drill policy, fusion, and Z/thickness settings.

{
  /* pcb-layer-step is intended for fixture alignment models.
     Keep the model small: include board outline, test pads, and only the copper
     features useful for pogo-pin verification. */
  "schema": "wn.altium_cruncher.pcb_layer_step.config.v2",
  "defaults": {
    "pcbdoc": null,
    "layer": "bottom",
    "z_mm": 0.0,
    "thickness_mm": 0.035,
    "include_board_outline": true,
    "board_outline": {
      "color": "#111111",
      "cutout_color": "#FF0000",
      "cutouts": true,
      "width_mm": 0.2,
      "fuse": true
    }
  },
  "outputs": [
    {
      "name": "fixture_alignment",
      "output_step": "{board}__fixture_alignment.step",
      "features": {
        "tracks": false,
        "arcs": false,
        "fills": false,
        "polygons": false,
        "regions": false,
        "vias": false,
        "component_pads": {
          "mode": "matching_designators",
          "include_designators": ["TP*", "J*", "U1", "U2"]
        },
        "free_pads": false
      },
      "colors": {
        "default_copper": "#B87333",
        "pad_rules": [
          {"designators": ["TP*"], "color": "#FF0000", "body": "test_points"}
        ]
      },
      "drills": {
        "mode": "overlay",
        "minimum_diameter_mm": 0.85,
        "shape": "ring",
        "color": "#666666",
        "plated_color": "#666666",
        "non_plated_color": "#00AEEF",
        "ring_width_mm": 0.12,
        "plated_ring_shape": "pad"
      },
      "fuse_copper": false
    }
  ]
}

The v2 shape should preserve a migration path from the existing single-output config. The loader can accept the current flat object as one implicit output, but generated templates should use outputs[] so repeated fixture artifacts do not require repeated command invocations.

Feature Model

The command should collect typed source features before creating Geometer regions. A typed feature keeps source kind, layer, optional component designator, optional pad designator, optional hole diameter, optional plating state, optional full pad region, and generated planar region. This is the key design change needed for filtering and colorization.

Supported feature categories should include tracks, arcs, fills, poured polygons, non-polygon regions, shape-based regions, component pads, free pads, vias, board outline, and board cutouts. Board-profile cutouts are separate from the outer board outline for visual coloring, but still act as cutouts against copper bodies. Defaults should favor fixture alignment: bottom layer, board outline included, component pads included by designator rules, vias excluded, pours excluded, and traces/arcs off unless requested.

Designator Selection

Designator filtering should support both broad families and explicit parts. The expected matching form is a list of case-insensitive shell-style patterns and exact names, such as TP*, J*, U1, and U2. Component-owned pads use the owning PCB component designator. Free pads may use their pad designator but should be opt-in because they are not tied to a component placement.

Color rules should be evaluated after inclusion filtering. Rules can match the same designator patterns and assign a STEP body color. Because Geometer colors are body-level, matching pads should be grouped into separate bodies such as test_points rather than relying on per-region color. For Cricket Node, the design validation target is all TP* component pads colored red.

Drill Policy

Drills are not automatically useful in fixture alignment models because normal boards contain many vias. Drill handling should be explicit and independent of via-copper inclusion. The requested modes are none, cut, and overlay, with auto retained as a compatibility mode. A minimum drill diameter filter should allow large mechanical holes to remain while ordinary vias are ignored. The Cricket Node validation target is minimum_diameter_mm: 0.85.

Overlay drills may be rendered as solid disks/capsules or as ring regions with holes. Rings are preferred for mechanical-hole reference because they identify the hole location without looking like copper. Plated and non-plated drill overlays can use different body colors. For plated pad holes such as mounting-hole components, plated_ring_shape: "pad" uses the full pad outline as the ring body and subtracts the drill hole from it; "annulus" keeps the fixed-width ring around the drill. Boolean cuts are most accurate but can be expensive on dense boards. Overlay bodies are faster and usually sufficient for fixture review.

Fusion

fuse_regions is a Geometer body option that performs planar union before extrusion. Fusion can remove internal overlap edges, but it may lose source arc fidelity and may not always reduce STEP size. The fixture-alignment config should keep fusion independently configurable for copper, board outline, drill overlays, and colored pad groups. The release tests should compare generated STEP sizes for fused and non-fused Cricket Node variants before choosing defaults.

Output

Each configured output writes a STEP file plus JSON manifest. The manifest should record the selected layer, source board, coordinate policy, Z/thickness settings, enabled feature classes, designator filters, color rules, drill policy, fusion settings, body counts, region counts, drill counts before and after diameter filtering, and generated byte size. For multi-output configs, each output should have an independent manifest next to its STEP file.

Tests

L3 should continue using the minimized Cricket Node PcbDoc. The next design validation pass should generate size and request-shape comparisons for fused versus non-fused copper, drills omitted versus drills filtered at greater than 0.85 mm, drill overlays as independently colored ring bodies, traces included versus excluded, and TP* pads colored red. Unit tests should cover JSONC block-comment config loading, multi-output config expansion, designator matching for TP*, J*, U1, and U2, feature-category filtering, drill diameter filtering, ring-region creation, and Geometer request grouping by body color.