From fac9168c006e6eaf21c11db08cc20256aad963c8 Mon Sep 17 00:00:00 2001
From: sjat <sjat@fisi.nyumbani.baobab.band>
Date: Mon, 8 Jun 2026 22:51:47 +0200
Subject: [PATCH] docs: README and deployment config

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3b02fdf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,31 @@
+# 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.