Metadata-Version: 2.4
Name: wgv
Version: 0.1.0
Summary: Web Gerber Viewer — generate static PCB viewer sites from Gerber files
Project-URL: Homepage, https://github.com/nipo/wgv
Project-URL: Source, https://github.com/nipo/wgv
Project-URL: Issues, https://github.com/nipo/wgv/issues
Author: Nicolas Pouillon
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Requires-Python: >=3.13
Requires-Dist: cbor2>=5.0
Requires-Dist: click>=8.0
Requires-Dist: gerbonara>=1.6
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

![Demo](shots/demo.webp)

## 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.

```sh
pip install -e ".[dev]"
```

## Usage

### Generate a viewer

```sh
# 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:

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

### Diagnostics

Inspect coordinate systems and auto-detected offset before
generating:

```sh
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

| Action | Effect |
|--------|--------|
| Scroll / pinch | Zoom |
| Drag | Pan |
| Top / Bottom buttons | Switch view side (layers + flip) |
| Layer checkboxes | Toggle layer visibility |
| Search box (+ Enter) | Find component by ref or value |
| Click on component | Show component details popup |
| Right-click | Start / finish distance measurement |
| Left-click (while measuring) | Finish distance measurement |
| Escape | Clear measurement |
| Placement offset dX/dY | Nudge component markers in real-time |

## 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.
