WGV — Web Gerber Viewer

Generate fully static, interactive PCB viewer website from Gerber manufacturing files. Open the result in any browser, no dynamic server required.

Features

• Render all copper, silk, mask, paste, drill, and outline layers
• Client-side Canvas rendering with d3-zoom pan/zoom/pinch
• Toggle individual layers on/off
• Top and bottom view (mirrored) with per-side layer defaults
• BOM and placement CSV overlay with component markers
• Search components by reference designator or value (Enter to select first match)
• Click component to show details, click search result to auto-switch view side and zoom to component
• Distance measurement tool (right-click to start, left or right-click to finish) with on-canvas label
• Cursor position readout in mm and mils
• Live placement offset adjustment in the viewer
• Tested with KiCad and Allegro exports, may support other tools by luck.

Result

Limitations

Sometimes, coordinates for drills, component placement and gerbers are not using the same origin. wgv tries hard to reconcilate them but may fail. This is the reason there are offset adjustment inputs in the final page. Default offset can also be overridden at generation time.

Installation

Requires Python 3.13+. No native dependencies — rendering is done client-side in the browser.

pip install -e ".[dev]"

Usage

Generate a viewer

# From a directory of Gerber files
wgv generate gerbers/ -o output/

# From a zip file with BOM and placement
wgv generate board.zip -o output/ \
    --bom board-bom.csv \
    --placement board-xy.csv

# Override auto-detected placement offset
wgv generate board.zip -o output/ \
    --bom bom.csv --placement xy.csv \
    --placement-offset 0.5 -15.5

# Explicit zoom level (default: auto, targeting 0.5 mil/pixel)
wgv generate board.zip -o output/ --zoom-max 8

Then open output/index.html in a browser. For local viewing, serve with:

python3 -m http.server -d output/ 8000
# Open http://localhost:8000

Diagnostics

Inspect coordinate systems and auto-detected offset before generating:

wgv info board.zip --bom bom.csv --placement xy.csv

Outputs bounding boxes (gerber, edge cuts, drill, placement), axis directions, size comparisons, and the correction offset. Use --json for machine-readable output.

Viewer controls

Supported formats

Gerber files: RS-274X from KiCad, Allegro, Altium, Eagle, and most other EDA tools. Layer identification uses Gerber X2 attributes when available, with filename-based fallback.

Drill files: Excellon format (.drl, .xln), including Allegro routed slots (.rou).

BOM CSV: Auto-detects column headers. Supports grouped references (C1, C2, C3), tab or comma delimited, with optional preamble rows.

Placement CSV: Auto-detects columns for reference, X, Y, rotation, and side. Handles comma decimal separators, mil/mm auto-detection, and KiCad/Allegro naming conventions (SYM_MIRROR = YES/NO for side).

Project structure

src/wgv/
├── cli.py              # Click CLI (generate, info)
├── board.py            # Board model, placement offset detection
├── gerber/
│   ├── parser.py       # Gerber/drill loading, layer identification
│   └── layers.py       # Layer types, colors, z-ordering
├── csv/
│   ├── bom.py          # BOM CSV parsing
│   ├── placement.py    # Placement CSV parsing
│   └── merge.py        # BOM + placement merge
├── render/
│   ├── extents.py      # Board-to-tile coordinate mapping
│   └── primitives_export.py  # Gerber primitive → JSON serialization
└── site/
    ├── generator.py    # Static site assembly
    └── static/         # HTML/JS/CSS + vendored d3-zoom

License

MIT

Notes

This project has been mostly vibe-coded using Claude Code from Anthropic. Coding manually would have been more-or-less the same but would have taken 10x the time.