# G-Code Overlay

Overlays a G-code toolpath on the CNC router's live camera stream, so you can reality-check a job before/while it runs and see where the tool will and won't go (e.g. for placing screws/clamps).

Pure client-side static web app — TypeScript + Vite + Canvas 2D, no backend. The G-code file is parsed locally in the browser; nothing is uploaded.

## Develop

- `npm install`
- `npm run dev` — local dev server
- `npm test` — run the unit tests
- `npm run build` — type-check + production build to `dist/`

## Deploy

Serve the built `dist/` as static files. Configure via `public/config.json` (bundled into the build):

- `streamUrl` — the camera stream URL. The page shows it in an `<img>` element, which works directly for an **MJPEG** stream. If the stream is **HLS** or **WebRTC**, swap the `<img id="stream">` in `index.html` for a `<video>` element and add the appropriate playback wiring (e.g. hls.js for HLS).
- `calibration` — produced once via the in-app Calibration panel (see below). Paste the generated JSON here to persist it for all viewers. Calibration is stored in **normalized [0,1] camera-frame coordinates**, so a single calibration works for every viewer regardless of screen size.
- `renderDefaults` — `cutColor`, `rapidColor`, `lineWidth` for the overlay.

## Use

1. Open a local G-code file with the **Open G-code** button.
2. **Calibrate** (one-time, persisted in `config.json`): jog the CNC spindle to a known X/Y, enter those coordinates, then click the spindle tip in the video. Repeat for **at least 10 well-spread points** including the table corners (distortion is worst there). A good target is a "box + #" — lines at the thirds of each axis — giving 16 points (12 on the perimeter + 4 interior crossings); jog-and-mark each so the coordinate is exact. Pick the polynomial **Degree** (default **3**, which compensates wide-angle barrel distortion; drop to 2 for sparse calibration), click **Compute warp** — the per-point error (px) flags any misclick — and paste the generated JSON into `public/config.json`.
3. **Align** the toolpath to the material: drag it to move, Shift-drag to rotate, use **Set origin by clicking video**, or type a numeric X/Y/rotation. Then reality-check the overlay against the live cut.

## Notes

- Calibration uses a **bivariate polynomial warp** (machine-mm ↔ normalized image), not a plain perspective homography. A homography keeps straight lines straight, so it cannot follow the curvature a wide-angle lens introduces; the polynomial's cubic terms model that barrel distortion (which is a degree-3 effect on position), so the overlay tracks the bowed bed edges instead of drifting at the corners. The forward map draws the overlay; an independently-fit inverse map powers click-to-set-origin and dragging.
- Supported G-code: G0/G1/G2/G3 motion, G90/G91, G20/G21 units, arcs via I/J or R. Cutting moves are drawn solid, rapids dashed.