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 4 well-spread points (near the table corners gives the best accuracy). Click Compute homography — the per-point error (px) flags any misclick. 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

• A perspective (homography) transform assumes straight cuts stay straight. If a wide-angle camera bows straight lines, the calibration per-point error will reveal it; lens-distortion correction is a possible future addition.
• 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.