31:Tcd8,hexTaster = { // One photograph, read by the shipping cascade, before the reader is asked to // point a camera at anything. The rig below needs a webcam and a printout; this // needs neither, and it is the same detector. // // The frame is chosen by NAME and never by index. The rest of the bank is // photographs of other people, and a reorder must not be able to put one of them // at the top of the page. await whenVisible("hexTaster", invalidation); const b = hexFrameBank.find((f) => /-04$/.test(f.name)); if (!b) return htl.html`

taster frame not in the bank

`; const frame = { gray: b.frame.gray, w: b.frame.w, h: b.frame.h }; // The number in the caption used to be a single call to analyzeFrameMan taken // at boot, and it read 134ms. Both halves of that were wrong, and they // compounded. Measured on this frame at stride 4 on a Macbook, 2026-08-11: // // analyzeFrameMan, main thread, warm 27.3ms // first call of it after boot, cold 63.7ms // analyzeFrameManAsync + pool of 6, warm 2.8ms <- what ships // // analyzeFrameMan is the pool-off fallback, not the path the rig runs, so the // caption was advertising the slow arm; and poolBenchmark already says why the // rest of the gap was there -- "a throughput number taken during boot would be // a measurement of the boot". So: the pooled path, warmed, and a median. const opts = { stride: 4, ...(detectPool ? { runRows: detectPool.runRows } : {}) }; const run = detectPool ? (f, o) => analyzeFrameManAsync(f, o) : async (f, o) => analyzeFrameMan(f, o); // Untimed. The first pool job allocates each worker's frame buffer, and the // first of anything here is also paying for JIT. let res = await run(frame, opts); const ts = []; for (let i = 0; i < 5; i++) { const t0 = window.performance.now(); res = await run(frame, opts); ts.push(window.performance.now() - t0); } ts.sort((x, y) => x - y); const ms = ts[2]; const pose = fitHexPose({ ...res, w: b.frame.w, h: b.frame.h }); const how = detectPool ? `on ${detectPool.size ?? "the"} workers` : "on the main thread, pool off"; const overlay = htl.svg``; overlay.innerHTML = hexOverlay.parts(pose, res); return htl.html`

${b.name}, ${b.frame.w}×${b.frame.h}, read here in **${ms.toFixed(1)}ms** at stride 4 ${how}, median of 5 after a warm-up: ${pose.ok ? `${pose.counts.read} of 7 barcodes decoded` : "no plane"}${ pose.ok && pose.offTarget.length ? `, ${pose.offTarget.length} off-target` : ""}. Solid rings carry an id, dashed ones located but did not decode. The whole bank, and what the settings above cost it, is ${ref("eval")}.

`; }32:Td87,priorWork = { // The series as each notebook's own opening prose describes it, not as // remembered. The 2012 post is Part I, which is what makes this one Part V -- // the notebooks number themselves I, II, III because they count only // notebooks, so a reader following their self-labels lands one short. // // Every part links to its lopecode page, so one destination serves the whole // run. Checked 2026-08-13: all three answer 200 and their bootconf mains name // the right module, so the page boots the notebook rather than an empty shell. // II and III are also on observablehq.com; IV is not (api.observablehq.com // 404s for the slug), which is why the pages are the common ground. // // Dates: I from the post's own URL; II and III are Observable publish_time // (api.observablehq.com/document/@tomlarkworthy/); IV and V are their // first commit in the lopebooks repo, which goes back to 2025-04, so those // are creation dates and not the repo's birthday. const rows = [ ["I", "2012-05", externalLink("Optical localization to 0.1mm, no problemo", "https://edinburghhacklab.com/2012/05/optical-localization-to-0-1mm-no-problemo/"), "Where it started. Cheap high-speed optical positioning for a robot's end effector, on a webcam."], ["II", "2023-06", externalLink("Simplifying Pose Estimation with Circular Barcodes", "https://tomlarkworthy.github.io/lopebooks/notebooks/@tomlarkworthy_circular-barcode-simulator.html"), "The geometry, in a three.js camera simulator. A circular barcode reads the same along any chord through its centre, so a 2D pose search becomes a 1D pattern match on one row of pixels."], ["III", "2025-08", externalLink("Fast 1D Circular Barcode Matching", "https://tomlarkworthy.github.io/lopebooks/notebooks/@tomlarkworthy_fast-1d-circular-barcode-matching.html"), "Centre and tilt of one barcode from one scan row of a simulated frame, by recovering the Möbius transform — the exact 1D projective map — from an anchor search, a DP alignment and a least-squares refit."], ["IV", "2026-08", externalLink("Realtime Multi-Barcode Tracking", "https://tomlarkworthy.github.io/lopebooks/notebooks/tomlarkworthy_realtime-multi-barcode-tracking.html"), "Several barcodes at independent poses, on live frames. Strided rows so each barcode is near-centred on one of them, and a cross-ratio test in place of the anchor SVD."], ["V", "2026-08", htl.html`This notebook`, "Printed barcodes that carry their own position, decoded from a live camera, fused into a plane pose."] ]; return htl.html`

Earlier installments

${rows.map(([n, when, link, subject]) => htl.html``)}

${n}

${when}

${link}

${subject}

`; }33:T9f5,hexRigView = { // The rig draws into its OWN canvas rather than laying an overlay over // liveVideo. A DOM node lives in one place at a time, so borrowing the video // element would take it out of The Scanner's view; and the rig wants the frame it // actually analysed on screen, at working resolution, not the camera's. const cap = htl.html`

`; const overlay = htl.svg``; const hud = htl.html`

`; const stage = htl.html`

${cap}${overlay}${hud}

`; const keep = htl.html``; const clear = htl.html``; // OFF by default. A keep costs a full-frame grayAll plus a PNG encode of the // whole canvas, which on a phone is tens of milliseconds -- enough to make // the live view visibly jerky and to dominate any frame-budget reading taken // while it runs. Collecting is a deliberate act, not a background one. const auto = htl.html` auto-collect hard cases`; const note = htl.html``; const bar = htl.html`

${keep}${clear}${auto}${note}

`; const el = htl.html`

${stage}${bar}

`; // The buttons only raise flags; hexRig reads and clears them. It is the one // cell that holds the frame, the labels and the settings that produced them // together, and a case missing any of the three cannot be replayed -- so it // owns every write to the case store. el.wantKeep = false; el.wantClear = false; el.autoCollect = () => auto.firstElementChild.checked; el.cap = cap; el.overlay = overlay; el.hud = hud; el.note = note; keep.onclick = () => { el.wantKeep = true; }; clear.onclick = () => { el.wantClear = true; }; return el; }34:Tbf7,viewof hexRigCfg = Inputs.form({ // EVERY default here is the value the shipping detector already uses, so the // rig at rest measures the detector as deployed rather than a near miss of // it. The three pose gates are the ones to watch: their defaults are `??` // fallbacks inside fitManPose (1/3, 0.3, 0.35), not fields on manLayout, so // they cannot be read off the layout and are mirrored here by hand. If // fitManPose's fallbacks change, change these with them. // // min axis ratio steps by 1/60 rather than 0.01 for one reason: a range // input snaps its value onto the min+k*step grid, and 1/3 is not on a // hundredths grid -- the slider quietly reported 0.33 and the rig would have // been measuring a detector nobody ships. stride: Inputs.range([2, 10], { step: 1, value: 4, label: "stride (rows)" }), edgeThreshold: Inputs.range([2, 30], { step: 1, value: 12, label: "edge threshold" }), minRows: Inputs.range([2, 8], { step: 1, value: 3, label: "min rows / cluster" }), minVotes: Inputs.range([1, 6], { step: 1, value: 2, label: "min id votes" }), voteRatio: Inputs.range([1, 4], { step: 0.5, value: 2, label: "vote margin x" }), minAxisRatio: Inputs.range([0, 0.9], { step: 1 / 60, value: 1 / 3, label: "min axis ratio" }), minCover: Inputs.range([0, 0.9], { step: 0.05, value: 0.3, label: "min cover" }), maxASpread: Inputs.range([0.05, 1.5], { step: 0.05, value: 0.35, label: "max width spread" }), gapFrac: Inputs.range([0.15, 0.6], { step: 0.05, value: 0.3, label: "row split gap frac" }), // Defaults to the TOP of its range on purpose. Lowering it does not just cost // resolution: the working width has to equal the width the camera's frames // ARRIVE at for the zero-copy capture path to engage, so any value // under that buys a smaller image at the price of a ~20ms/frame RGBA readback // -- a net loss on a phone. Cost tracks locked rows, not pixels. // // The top is 1920, not the 1280 the camera is requested at, because the two // are not the same number. A track constrained to 1280 can still deliver // 1440x1080 frames and let the browser scale them down for display, and the // rig sizes itself to what arrives. maxWidth: Inputs.range([480, 1920], { step: 160, value: 1920, label: "working width (px)" }), // The odd one out: not a threshold to tune but a second scan of the same // frame, down the columns instead of across the rows (§4.3). The row scan // MEASURES a centre's x while only extrapolating its y, so the column scan // supplies the coordinate the row scan guessed. // // On by default (§4.3). It used to halve the frame rate, which is why it was // not; the two passes now run concurrently across the worker pool and cost // ~26ms against a 33.3ms budget on the phone, inside the 30fps camera cap. // It finds 4 more marks across the bank with no false positives, and now // that the merge fuses by decode margin it no longer costs placement to get // them. bothAxes: Inputs.toggle({ label: "scan both axes", value: true }) })35:T940,liveStream = { if (!liveOn) return null; try { // The detector needs ~2 image pixels per template unit, so 1280 rather than // the default 640 is the single cheapest thing that widens the usable // working distance. `max` as well as `ideal`, because a phone camera // offered a free hand will hand back 1920 or more, and the zero-copy // capture path needs the working width to EQUAL the camera width // (VideoFrame.copyTo crops, it cannot scale). Overshoot here costs ~20ms a // frame there. const s = await window.navigator.mediaDevices.getUserMedia({ video: { width: { ideal: 1280, max: 1280 }, height: { ideal: 960, max: 1280 }, facingMode: liveFacing } }); // Hold the screen awake for as long as the camera is on, and no longer. // Tracking is minutes of not touching the phone, and Android then blanks // the screen -- which hides the tab, and a hidden tab fires no rAF, so the // rig stops dead. Tying it to the stream rather than to a toggle of its own // means an idle notebook can never pin someone's display on. let lock = null, done = false; const hold = async () => { // request() rejects outright while the page is not visible, so this has // to be retried on visibilitychange rather than attempted once here. if (done || lock || !window.navigator.wakeLock) return; if (window.document.visibilityState !== "visible") return; try { lock = await window.navigator.wakeLock.request("screen"); // The UA drops the lock every time the page hides and does NOT restore // it on return; clearing the handle is what lets onVisible re-take it. lock.addEventListener("release", () => { lock = null; }); } catch (e) { lock = null; // a refusal must never take the camera down with it } }; const onVisible = () => { if (window.document.visibilityState === "visible") hold(); }; window.document.addEventListener("visibilitychange", onVisible); hold(); invalidation.then(() => { done = true; window.document.removeEventListener("visibilitychange", onVisible); if (lock) lock.release().catch(() => {}); for (const t of s.getTracks()) t.stop(); }); return s; } catch (e) { return { error: String((e && e.message) || e) }; } }36:T450,liveVideo = { // Never shown: the rig canvas below draws these same pixels with the overlay // on top, so a raw feed is duplicate. It has to stay in the document to keep // decoding, so hide it with visibility (not display:none, which stops frame // delivery) and take it out of flow so the cell collapses. const v = htl.html`

`; if (liveStream && !liveStream.error) v.srcObject = liveStream; // Never await play(): an unsettled promise would leave this cell pending and // take the whole rig with it. A media element removed from its document is // paused by the UA and nothing resumes it, and a lopepage pane move detaches // us, so poll instead. const kick = () => { if (v.srcObject && v.paused && v.isConnected) v.play().catch(() => {}); }; kick(); const resume = setInterval(kick, 500); invalidation.then(() => { clearInterval(resume); try { v.pause(); v.srcObject = null; } catch (e) {} }); return v; }37:T143d,hexRigAutosave = { // Captured cases die with the tab. hexRigCases is an Inputs.input([]), so it // holds real pixels at runtime and exports as empty -- a reload, a crash or a // slow export throws away work that costs someone standing in front of a // camera holding a printed sheet at arm's length. This takes each case off // the page the moment it is kept. // // What gets sent is the `gray` buffer, which is exactly the bytes the // detector was handed, plus a sidecar of the frozen labels and the settings // that produced them. No image codec in either direction, so a restored case // is bit-identical to the captured one -- which matters here more than // anywhere, because a JPEG round trip moves measured centres by up to 10px // and these cases exist to BE the ground truth. // // It depends on the cases NODE, not the cases value. Depending on the value // would re-run this cell on every capture, rebuilding the panel and losing // track of what had already been sent; listening to the node's input event // leaves the cell running and stateful across captures. const node = viewof hexRigCases; const sent = new Set(); let sink = "http://127.0.0.1:8787"; let auto = false; // opt in: a page that POSTs to localhost on load is a surprise const el = htl.html`

autosave to

`; const chk = el.querySelector("input[type=checkbox]"); const box = el.querySelector("input[type=text]"); const btns = el.querySelectorAll("button"); const saveBtn = btns[0], dlBtn = btns[1]; const status = el.querySelector("[data-status]"); const log = el.querySelector("[data-log]"); const say = (msg) => { log.textContent = (msg + "\n" + log.textContent).split("\n").slice(0, 12).join("\n"); }; chk.oninput = () => { auto = chk.checked; }; box.oninput = () => { sink = box.value.trim(); sent.clear(); }; const meta = (c) => ({ name: c.name, w: c.w, h: c.h, labelled: c.labelled, pinned: c.pinned, difficulty: c.difficulty, truth: c.truth, cfg: c.cfg, capture: c.capture }); const push = async (c) => { // gray first: if the sidecar lands without pixels the case is unusable, so // a half-finished transfer should leave the recoverable half on disk. const g = await window.fetch(sink + "/gray/" + encodeURIComponent(c.name), { method: "POST", body: c.gray }); if (!g.ok) throw new Error("gray " + g.status); const j = await window.fetch(sink + "/meta/" + encodeURIComponent(c.name), { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(meta(c), null, 1) }); if (!j.ok) throw new Error("meta " + j.status); }; const drain = async (force) => { if (!sink || (!auto && !force)) return 0; const cases = node.value ?? []; let n = 0, failed = 0; for (const c of cases) { if (!c.gray) continue; if (sent.has(c.name) && !force) continue; try { await push(c); sent.add(c.name); n++; say("saved " + c.name + " (" + c.gray.length.toLocaleString() + "B)"); } catch (e) { failed++; say("FAILED " + c.name + ": " + e.message); } } status.textContent = sent.size + "/" + cases.length + " on disk" + (failed ? " — " + failed + " failed" : ""); return n; }; // A bundle for when no receiver is running: raw gray, gzipped, one file, // restorable without an image decoder. const bundle = async () => { const cases = node.value ?? []; const parts = []; for (const c of cases) { if (!c.gray) continue; const packed = await new window.Response( new window.Blob([c.gray]).stream().pipeThrough(new window.CompressionStream("gzip")) ).arrayBuffer(); const b = new Uint8Array(packed); let s = ""; for (let i = 0; i < b.length; i += 0x8000) s += String.fromCharCode.apply(null, b.subarray(i, i + 0x8000)); parts.push({ ...meta(c), grayGzipB64: window.btoa(s) }); } const a = window.document.createElement("a"); a.href = URL.createObjectURL(new window.Blob( [JSON.stringify({ format: "hexrig-cases-1", cases: parts })], { type: "application/json" } )); a.download = "hexrig-cases.json"; a.click(); say("bundled " + parts.length + " case(s)"); }; saveBtn.onclick = () => drain(true); dlBtn.onclick = () => bundle(); const onInput = () => drain(false); node.addEventListener("input", onInput); invalidation.then(() => node.removeEventListener("input", onInput)); drain(false); return el; }38:T552,hexRigOpts = { // One options object, used by BOTH the live loop and the offline sweep. // Sharing it is the point: a knob the sweep can move but the live view // cannot would let the two disagree about what is being measured. // // The pose gates are not top-level options — they live on the layout object // (fitManPose takes L), so overriding them means passing a modified copy of // the layout. Everything else is a plain opt that analyzeFrameMan forwards // down through detectRowMan to manRowGroups. // // bothAxes goes through the same channel, which is why nothing downstream of // here needed changing to gain the option: analyzeFrameMan dispatches on it // itself, so the live rig, the sweep and every replay pick it up together. // It costs a second full pass and is worth it HERE specifically — the rig's // ground truth is a homography through these centres, and the centre's weak // coordinate is the one the row scan extrapolates rather than measures. const c = hexRigCfg; return { stride: c.stride, edgeThreshold: c.edgeThreshold, minRows: c.minRows, minVotes: c.minVotes, voteRatio: c.voteRatio, gapFrac: c.gapFrac, bothAxes: c.bothAxes, layout: { ...manLayout, minAxisRatio: c.minAxisRatio, minCover: c.minCover, maxASpread: c.maxASpread } }; }39:T62e,hexRigLoo = function hexRigLoo(res, target) { // Leave-one-out prediction error over the detected target marks. // // This exists because the fit's own rms residual cannot be trusted to say // whether the labels are any good. A homography has 8 degrees of freedom; 4 // marks fit it exactly, and 5 leave only 2 residual degrees, so a badly // measured centre is absorbed by the fit rather than shown by it. Measured: // a frame with rms 1.39px carried label errors up to 66px, on marks that // were READ, not extrapolated. // // LOO asks the question the rms only appears to answer -- refit without one // mark, then predict it -- and every one of those predictions is made // without the data it is checked against. That is exactly the situation // every unread mark's label is in. const T = target ?? hexTarget; const pairs = (res.fused ?? []) .filter((f) => T.byId.has(f.id)) .map((f) => { const m = T.byId.get(f.id); return { sx: m.xMm, sy: m.yMm, dx: f.xc, dy: f.yc, id: f.id }; }); // 4 points fit exactly, so LOO needs a fifth to have anything to hold out if (pairs.length < 5) return null; let worstPx = 0, id = null; const each = []; for (const p of pairs) { const fit = fitHomography(pairs.filter((q) => q !== p)); if (!fit) return null; const [px, py] = fit.map(p.sx, p.sy); const d = Math.hypot(px - p.dx, py - p.dy); each.push({ id: p.id, px: +d.toFixed(1) }); if (d > worstPx) { worstPx = d; id = p.id; } } return { worstPx: +worstPx.toFixed(1), id, n: pairs.length, each }; }3a:T8ad,hexRigScore = function hexRigScore(res, truth, tolFrac = 0.6) { // Score one cascade result against a FROZEN label set. // // This is the difference between the rig and fitHexPose. fitHexPose fits the // plane from the detections in the frame it is given, which is right for a // live view but circular for tuning: change a setting, lose a mark, and the // plane moves under you, so the thing you are scoring against is a function // of the thing you are scoring. Here the labels are frozen -- measured once, // offline, by the §4.7 relabelling pass at twelve directions and stride 1 with // ring-lattice refinement -- and every replay at every setting is scored // against those same seven positions. // // States match fitHexPose's vocabulary so the live overlay and the sweep // table mean the same thing by the same word. const fused = res.fused ?? []; const unread = (res.unidentified ?? []).filter((u) => u.posed); const known = new Set(truth.map((t) => t.id)); const marks = truth.map((t) => { const tol = tolFrac * t.radiusPx; const hit = fused.find((f) => f.id === t.id); const near = unread.find((u) => Math.hypot(u.xc - t.x, u.yc - t.y) <= tol); const resid = hit ? Math.hypot(hit.xc - t.x, hit.yc - t.y) : null; return { id: t.id, state: hit ? (resid <= tol ? "read" : "misplaced") : near ? "located" : "missing", residualPx: resid == null ? null : +resid.toFixed(1) }; }); const counts = { read: 0, misplaced: 0, located: 0, missing: 0 }; for (const m of marks) counts[m.state]++; const offTarget = fused.filter((f) => !known.has(f.id)); // A wrong id costs more than a miss. The target's seven ids are pairwise // Hamming distance 3 apart, so a false read is not a near miss of a correct // one -- it is the detector asserting something no single flipped cell can // explain. Weight 3 is a judgement, and it is the only judgement in here; // every other number reported is a count. const wrong = counts.misplaced + offTarget.length; return { marks, counts, offTarget: offTarget.map((f) => ({ id: f.id, x: Math.round(f.xc), y: Math.round(f.yc) })), wrong, score: counts.read - 3 * wrong }; }3b:T2980,lumaCapture = function makeLumaCapture() { // Getting the luma out of a camera, by the cheapest route the browser // actually offers rather than the one everyone writes. // // The obvious pipeline -- drawImage into a 2D canvas, getImageData, weighted // sum to gray -- costs 5.1 + 17.7 + 1.7 ms on a mid-range Android at // 960x1280. The 17.7 is a GPU-to-CPU readback of 4.9MB of RGBA. But a camera // does not produce RGBA: it produces I420 or NV12, whose FIRST PLANE IS THE // LUMA. WebCodecs will hand that over directly for 1.4ms. The whole detour // exists to reconstruct something the hardware already had. // // Everything here is capability-detected and falls back to the old path, so // a browser without WebCodecs, a camera that reports RGBA, or a frame the // caller wants at a different size all still work -- more slowly, and // saying so through `path`. const LUMA_FIRST = /^(I420|I422|I444|NV12|NV21)/; // formats whose plane 0 is Y let W = 0, H = 0; let cvs = null, ctx = null; // fallback surface let raw = null, packed = null; // fast-path buffers let lut = null; let gray = null; let full = false; let src = null; // fast path: the luma plane grab() read from const size = (w, h) => { if (w === W && h === H) return; W = w; H = h; gray = new Uint8Array(W * H); raw = null; packed = null; cvs = null; ctx = null; }; const fallbackSurface = () => { if (ctx) return; cvs = window.document.createElement("canvas"); cvs.width = W; cvs.height = H; // willReadFrequently asks for a CPU-backed surface. It makes the readback // less catastrophic and the drawImage worse; on this path we do both, so // it is still the right side of that trade. ctx = cvs.getContext("2d", { willReadFrequently: true }); }; // BT.601 limited range (16-235) to full range. The old path derived luma // from RGB that the decoder had ALREADY expanded to full range, so without // this the two paths differ by a scale and an offset -- edge magnitudes // shrink by 219/255 and every tuned threshold, and every archived case, // quietly means something else. One table lookup per pixel is cheaper than // the three multiplies the old conversion cost, so correctness here is free. const buildLut = () => { lut = new Uint8Array(256); for (let v = 0; v < 256; v++) { const x = Math.round(((v - 16) * 255) / 219); lut[v] = x < 0 ? 0 : x > 255 ? 255 : x; } }; const api = { path: "unknown", format: null, fullRange: null, why: "", ms: 0, // What copyTo will ACTUALLY deliver, which is not what the video element // reports. `videoWidth` is the DISPLAY size, after any scaling the browser // applied to satisfy the track constraints; `visibleRect` is the frame the // camera really hands over. On a 1920x1080 sensor centre-cropped to 4:3 // they read 1280x960 and 1440x1080 -- and since copyTo crops rather than // scales, a caller sizing itself from the element analyses the top-left // 1280x960 of a 1440x1080 image while showing the whole thing scaled: an // overlay wrong by 1440/1280 everywhere, growing with distance from the // origin. Ask the frame, once per size change, and size to its answer. probe: (video) => { if (typeof window.VideoFrame !== "function" || !video || !video.videoWidth) return null; let f = null; try { f = new window.VideoFrame(video); const fmt = f.format || ""; const r = f.visibleRect; return { w: r ? r.width : f.codedWidth, h: r ? r.height : f.codedHeight, format: fmt, luma: LUMA_FIRST.test(fmt) }; } catch (e) { return null; } finally { if (f) try { f.close(); } catch (e2) {} } }, // Fill `gray` for this frame. `rows` is only consulted on the fallback // path, where converting the whole frame costs real time and the scan // needs a quarter of it; the fast path always has every row and says so // through `full`, which is what lets bothAxes and case capture skip their // extra pass entirely. grab: async (video, w, h, rows) => { size(w, h); const t0 = window.performance.now(); full = false; // The fast path cannot resize -- copyTo crops, it does not scale -- so a // caller asking for anything but the size the frame arrives at gets the // slow one. That test has to be made against the FRAME, not the video // element: the element reports the display size, which the browser may // have scaled down from what copyTo delivers, and a mismatch there is // invisible -- the repack loop reads the extra width as stride padding // and silently analyses a crop. See `probe`. if (typeof window.VideoFrame === "function" && api.path !== "getimagedata-forced") { let frame = null; try { frame = new window.VideoFrame(video); const fmt = frame.format || ""; const vr = frame.visibleRect; const fw = vr ? vr.width : frame.codedWidth; const fh = vr ? vr.height : frame.codedHeight; if (!LUMA_FIRST.test(fmt)) { api.why = `format ${fmt} has no luma plane`; frame.close(); } else if (fw !== W || fh !== H) { api.why = `frame requested at ${W}x${H}, copyTo delivers ${fw}x${fh}`; frame.close(); } else { const need = frame.allocationSize(); if (!raw || raw.length < need) raw = new Uint8Array(need); const layout = await frame.copyTo(raw); const cs = frame.colorSpace; const fr = cs && cs.fullRange; frame.close(); frame = null; const { offset, stride } = layout[0]; // Plane 0 may be padded to a hardware-friendly stride, and often // is not. Only repack when it actually differs. let y; if (stride === W) { y = raw.subarray(offset, offset + W * H); } else { if (!packed || packed.length !== W * H) packed = new Uint8Array(W * H); for (let r = 0; r < H; r++) packed.set(raw.subarray(offset + r * stride, offset + r * stride + W), r * W); y = packed; } if (fr === false) { // The expansion is a per-pixel loop, and a profile on a phone put // it at 4.5ms/frame -- the whole remaining cost of capture, and // more than the copy it follows. The scan reads a quarter of the // rows at stride 4, so expand a quarter of the rows. Same trick // the RGB path always used, for the same reason. if (!lut) buildLut(); src = y; if (rows) { for (const yy of rows) { const b = yy * W; for (let x = 0; x < W; x++) gray[b + x] = lut[y[b + x]]; } } else { for (let i = 0, n = W * H; i < n; i++) gray[i] = lut[y[i]]; full = true; } } else { // a bulk copy, not a loop -- cheap enough to always do whole gray.set(y); full = true; } api.path = "videoframe"; api.format = fmt; api.fullRange = fr == null ? null : !!fr; api.why = ""; api.ms = window.performance.now() - t0; return { gray, full, path: api.path }; } } catch (e) { if (frame) try { frame.close(); } catch (e2) {} api.why = "VideoFrame: " + (e && e.message ? e.message : String(e)); } } else if (typeof window.VideoFrame !== "function") { api.why = "no WebCodecs"; } fallbackSurface(); ctx.drawImage(video, 0, 0, W, H); const px = ctx.getImageData(0, 0, W, H).data; api._px = px; const row = (yy) => { const b = yy * W; for (let x = 0, p = b * 4; x < W; x++, p += 4) gray[b + x] = (px[p] * 77 + px[p + 1] * 150 + px[p + 2] * 29) >> 8; }; if (rows) { for (const yy of rows) row(yy); } else { for (let yy = 0; yy < H; yy++) row(yy); full = true; } api._row = row; api.path = "getimagedata"; api.format = "RGBA"; api.ms = window.performance.now() - t0; return { gray, full, path: api.path }; }, // Fallback only: convert the rows grab() was allowed to skip. A no-op on // the fast path, which is the point -- callers stop having to know which // path they are on. ensureFull: () => { if (full) return gray; if (api.path === "videoframe") { for (let i = 0, n = W * H; i < n; i++) gray[i] = lut[src[i]]; } else { for (let yy = 0; yy < H; yy++) api._row(yy); } full = true; return gray; }, // Do the two paths agree? Same bar as poolAgreement: run both on ONE // frame and report the difference rather than assert a number nobody // measured. They cannot be identical -- the RGB path has been through // YUV->RGB->luma with rounding at each step -- so this reports the // distribution and lets the reader judge. compare: async (video, w, h) => { const a = await api.grab(video, w, h); if (a.path !== "videoframe") return { note: "fast path unavailable: " + api.why }; const fast = gray.slice(); const fmt = api.format, fr = api.fullRange; const was = api.path; api.path = "getimagedata-forced"; await api.grab(video, w, h); api.path = was; api.format = fmt; const n = w * h; let max = 0, sum = 0, lo = 255, hi = 0; for (let i = 0; i < n; i++) { const d = Math.abs(fast[i] - gray[i]); if (d > max) max = d; sum += d; if (fast[i] < lo) lo = fast[i]; if (fast[i] > hi) hi = fast[i]; } gray.set(fast); full = true; const out = { format: fmt, fullRange: fr, range: lo + ".." + hi, maxDiff: max, meanDiff: +(sum / n).toFixed(3), px: n }; // A lens-down phone makes both paths produce all zeros, and "identical" // then means nothing at all -- it is the most agreeable answer this // check can give and the only worthless one. Say so rather than pass. if (hi - lo < 32) out.note = `INCONCLUSIVE: frame spans only ${lo}..${hi}. Point the camera at a lit scene.`; return out; } }; return api; }3c:T4bdf,hexRig = { // The calibration rig. Point the camera at the printed hexTargetSvg sheet and it // does three things at once: // // 1. runs the cascade at whatever hexRigCfg currently says, // 2. fits the sheet's plane and grades all seven marks against it, so the // failures are named rather than counted, // 3. KEEPS the frames that fail, with their labels, so the failure can be // replayed offline at other settings (hexRigSweep). // // Point 3 is the reason it exists. Tuning against a live camera tunes // against whatever you happened to be pointing at while you dragged the // slider; a knob that looks better is indistinguishable from a hand that // moved. A stored case is the same photons every time. // // A frame is only worth keeping if it can be LABELLED, and the bar for that // is the fussiest part of this cell, because a mislabelled case is worse // than no case: it teaches the sweep the wrong thing and never announces // itself. Three conditions, and the third is the one that matters: // // read >= 5 4 marks fit a homography exactly, so 4 tells you nothing // about whether the fit is right. // rms <= 4px cheap, catches the obviously broken. // LOO <= 0.3r leave-one-out prediction error, worst over the detected // marks, against the median predicted radius. // // The rms bar alone is not enough and measurably so: a rendered frame with // rms 1.39px carried label errors of 66px. With 5 marks a homography has 2 // spare degrees of freedom, so it absorbs a badly measured centre instead of // reporting it, and the residual it shows you is the residual of the data it // was fitted to. Across 12 rendered frames the LOO bar admitted exactly the // one whose labels were actually good (true error 0.06 radii) and rejected // every frame whose labels were off by 0.4 radii or more -- see // hexRigSelfTest, which checks that against the renderer's own truth. const view = hexRigView; const store = viewof hexRigCases; const MAX = 12; const MIN_GAP_MS = 1200; const LOO_FRAC = 0.3; if (!liveOn) { view.hud.textContent = "camera off — turn it on in The Scanner, at the top"; // Idle, but never on a promise that cannot settle. The runtime ends a // generator by calling return() on it, which lands at the next yield; a // cell parked on `new Promise(() => {})` has no next yield, so the // termination never completes and the whole update chain stops behind it // — not this cell alone. Ticking keeps the cell endable. while (true) { yield null; await new Promise((r) => window.setTimeout(r, 250)); } } // No willReadFrequently: nothing reads this canvas back per frame any more, // so it stays a GPU surface and drawImage stays ~0.1ms. const ctxOut = view.cap.getContext("2d"); const luma = lumaCapture(); view.luma = luma; let W = 0, H = 0, gray = null; // Probing builds and closes a VideoFrame, so do it only when the element's // own dimensions move -- a camera does not change what it delivers without // changing those too. But the first frames of a track can refuse to make a // VideoFrame at all, and caching that null pinned the rig to the fallback // path for the whole session while `probe` answered correctly the moment // anyone asked it by hand. So a failed probe is not an answer: retry until // one succeeds, bounded so a camera that can never do it stops paying. let probed = null, probedFor = { w: 0, h: 0 }, probeLeft = 0; let lastCap = -1e9, lastYield = 0, n = 0, kept = 0; // The counter restarts at 0 in every tab, so a bare hexcase-NN silently // OVERWROTE earlier captures on the receiver -- four frames were lost that // way and only found again in git. A per-boot tag makes the name unique at // the granularity that actually collides: a second device, or a reload. const session = Math.floor(window.Date.now() / 1000).toString(36).slice(-4); const fps = []; // Where the frame actually goes. The headline number used to start AFTER the // capture and the luma conversion, so two pieces of main-thread work in the // middle of the budget -- a full-frame getImageData and a per-pixel loop over // a quarter of it -- were invisible in it. On a laptop that is a rounding // error and on a phone it is not, which is precisely the machine the number // was being read on. Same 20-frame window as fps, medians not means: one // stalled frame should not move a stage's number. const STAGES = ["cap", "gray", "scan", "fit", "draw"]; const hist = {}; for (const s of STAGES) hist[s] = []; const stage = (name, t0) => { const h = hist[name]; h.push(window.performance.now() - t0); if (h.length > 20) h.shift(); }; const stageMed = (name) => { const h = hist[name]; if (!h.length) return 0; return h.slice().sort((a, b) => a - b)[h.length >> 1]; }; // Read from the console or over CDP while the camera runs -- the HUD has room // for a summary, not for the evidence. view.stages = () => { const o = {}; for (const s of STAGES) o[s] = +stageMed(s).toFixed(2); o.total = +Object.values(o).reduce((a, b) => a + b, 0).toFixed(2); o.workerMs = detectPool ? detectPool.lastWorkerMs : null; o.workerChunks = detectPool ? detectPool.lastWorkerChunks : null; o.px = W * H; return o; }; // Stage 1 goes to the pool when there is one. analyzeFrameManAsync with no // runRows is analyzeFrameMan, so poolSize 0 is a real fallback and not a // second code path -- poolAgreement holds the two to 4dp. const poolOpts = detectPool ? { ...hexRigOpts, runRows: detectPool.runRows } : hexRigOpts; const COL = { read: "#2fe08a", located: "#ffd23f", missing: "#ff5c5c", misplaced: "#ff9f1c", off: "#d264ff" }; const push = (kase) => { // Pinned (hand-kept) cases outrank collected ones, then hardest first. // Something kept on purpose should never be evicted by the auto-collector. const next = [...store.value, kase] .sort((a, b) => (b.pinned - a.pinned) || (b.difficulty - a.difficulty)) .slice(0, MAX); store.value = next; store.dispatchEvent(new window.Event("input", { bubbles: true })); kept = next.length; }; while (true) { await new Promise((r) => window.requestAnimationFrame(r)); if (view.wantClear) { view.wantClear = false; store.value = []; store.dispatchEvent(new window.Event("input", { bubbles: true })); kept = 0; } const v = liveVideo; if (!v || v.readyState < 2 || !v.videoWidth) continue; // Size to the frame the camera DELIVERS, not to the one the element // displays. Those differ whenever the browser scales a track to satisfy a // constraint -- a 1920x1080 sensor cropped to 4:3 and constrained to 1280 // hands copyTo a 1440x1080 frame while `videoWidth` reads 1280. Sizing // from the element there put the analysis in a different coordinate space // from the canvas beside it: the fast path crops rather than scales, so // the detector saw the top-left 1280x960 of the frame, the canvas showed // all of it shrunk, and every overlay landed 1440/1280 out. Adopting the // delivered size keeps both the fast path and one coordinate space. // Above maxWidth we fall back to the display size, which loses the fast // path -- lumaCapture says so through `why` -- but stays consistent. if (v.videoWidth !== probedFor.w || v.videoHeight !== probedFor.h) { probedFor = { w: v.videoWidth, h: v.videoHeight }; probed = null; probeLeft = 60; } if (!probed && probeLeft > 0) { probed = luma.probe(v); if (!probed) probeLeft--; } const srcW = probed && probed.luma && probed.w <= hexRigCfg.maxWidth ? probed.w : v.videoWidth; const srcH = probed && probed.luma && probed.w <= hexRigCfg.maxWidth ? probed.h : v.videoHeight; const tw = Math.min(hexRigCfg.maxWidth, srcW); const th = Math.round((srcH * tw) / srcW); if (tw !== W || th !== H) { W = tw; H = th; view.cap.width = W; view.cap.height = H; view.overlay.setAttribute("viewBox", `0 0 ${W} ${H}`); } // Capture and luma in one step when the browser allows it. `cap` is now // the whole cost of getting a gray buffer; on the fast path `gray` is // nothing, because there is no conversion left to do. const tCap = window.performance.now(); const grabbed = await luma.grab( v, W, H, hexRigOpts.bothAxes ? null : manScanRows({ w: W, h: H }, hexRigOpts) ); gray = grabbed.gray; stage("cap", tCap); const tGray = window.performance.now(); // Convert only the rows the scan is going to read. At stride 4 that is a // quarter of the frame, and this is main-thread work sitting in the middle // of the frame budget -- the same argument that moved the scan itself into // workers. Two callers still need the whole frame: bothAxes reads it // transposed, and a captured case gets replayed at other strides, so both // ask for a full pass. Rows nobody converted keep whatever the previous // frame left there, which is why neither of those may read this buffer // without filling it first. const grayAll = () => luma.ensureFull(); stage("gray", tGray); // Straight from the video to the visible canvas: 0.1ms, because it never // leaves the GPU. The old path drew the CPU-side copy here, which is only // necessary if you already paid to bring the pixels down. ctxOut.drawImage(v, 0, 0, W, H); const t = window.performance.now(); const res = await analyzeFrameManAsync({ gray, w: W, h: H }, poolOpts); stage("scan", t); const tFit = window.performance.now(); // Every frame is judged on its own evidence. Carrying a focal length (or // anything else) forward from an earlier frame belongs in a notebook about // exploiting similar frames under geometric constraints, not in the one // that defines what a single frame can establish. const pose = fitHexPose({ ...res, w: W, h: H }); stage("fit", tFit); const dt = window.performance.now() - t; fps.push(dt); if (fps.length > 20) fps.shift(); // ---- overlay ---- // Frame pixels per CSS pixel of stage. The overlay is authored in frame // coordinates and stretched to the stage width, so on a phone a 3px stroke // arrives as barely one. Every WIDTH and TYPE SIZE below is multiplied by // this so it stays constant on screen; positions and radii are not, because // those are the measurement. const tDraw = window.performance.now(); const k = W / (view.overlay.clientWidth || W); const sw = (n) => +(n * k).toFixed(2); const parts = []; if (pose.ok) { const ring = pose.marks.filter((m) => m.k != null); if (ring.length > 2) parts.push( `` ); for (const m of pose.marks) { const c = COL[m.state]; const r = m.radiusPx; const dash = m.state === "read" ? "none" : m.state === "located" ? `${sw(7)} ${sw(5)}` : `${sw(2)} ${sw(6)}`; // the projected circle, not a circle: on a tilted sheet the two differ // by the tilt, and a ring that does not sit on its mark reads as a // tracking error rather than as a drawing one const top = m.outline ? Math.min(...m.outline.map((p) => p[1])) : m.predicted.y - r; const shape = m.outline ? `` + `${m.id}${m.state === "read" ? "" : " " + m.state[0]}` ); } for (const o of pose.offTarget) parts.push( ` ${o.id}?` ); } else { // no plane: show the raw detections, otherwise there is nothing to aim by // No homography here, but fitManPose measured both semi-axes -- a along // the scan, b across it -- so an axis-aligned ellipse is still closer to // the mark than a circle of a. for (const f of res.fused) { const ra = f.a ?? f.wHalf ?? 24; parts.push( `` ); } } view.overlay.innerHTML = parts.join(""); stage("draw", tDraw); // ---- collect ---- const loo = pose.ok ? hexRigLoo(res) : null; const rMed = pose.ok ? pose.marks.map((m) => m.radiusPx).sort((a, b) => a - b)[3] : null; const looOk = !!(loo && loo.worstPx <= LOO_FRAC * rMed); const labelled = pose.ok && pose.counts.read >= 5 && pose.rmsResidualPx <= 4 && looOk; const difficulty = pose.ok ? 4 * (pose.counts.misplaced + pose.offTarget.length) + 2 * pose.counts.located + pose.counts.missing : 0; const manual = view.wantKeep; view.wantKeep = false; const auto = view.autoCollect() && labelled && difficulty > 0 && t - lastCap > MIN_GAP_MS; if (manual || auto) { lastCap = t; n++; // a case is replayed at other strides, so it needs the rows this frame's // scan skipped if (!hexRigOpts.bothAxes) grayAll(); push({ name: `hexcase-${session}-${String(n).padStart(2, "0")}`, w: W, h: H, // a copy: the loop reuses this buffer every frame gray: gray.slice(), // the visible canvas holds exactly the analysed frame -- the overlay is // a sibling SVG, so nothing drawn on top can contaminate a stored case url: view.cap.toDataURL("image/png"), labelled, pinned: manual, difficulty, // Frozen at capture. Every later replay is scored against THESE, not // against a fresh fit -- see hexRigScore for why that matters. The // capture-time state rides along on each mark so the panel can show // WHICH mark failed, which is the part a count throws away. truth: pose.ok ? pose.marks.map((m) => ({ id: m.id, x: m.predicted.x, y: m.predicted.y, radiusPx: m.radiusPx, state: m.state })) : [], cfg: { ...hexRigCfg }, capture: { counts: pose.ok ? { ...pose.counts } : null, offTarget: pose.ok ? pose.offTarget.length : 0, rmsPx: pose.ok ? pose.rmsResidualPx : null, looPx: loo ? loo.worstPx : null, looFrac: loo ? +(loo.worstPx / rMed).toFixed(3) : null, mmPerPx: pose.ok ? pose.mmPerPx : null, distanceMm: pose.pose ? pose.pose.distanceMm : null, tiltDeg: pose.pose ? pose.pose.tiltDeg : null, ms: +dt.toFixed(1) } }); } const med = fps.slice().sort((a, b) => a - b)[fps.length >> 1] ?? dt; // cap+gray+scan+fit+draw, not just scan+fit. The difference between this // and `med` is exactly the work the old headline number did not count. const whole = STAGES.reduce((a, s) => a + stageMed(s), 0); const budget = STAGES.map((s) => s[0] + stageMed(s).toFixed(0)).join(" "); const c = pose.ok ? pose.counts : null; // On a phone the long form wraps to three lines and buries the bottom two // marks under the panel, so below ~560px say the same things shorter. const narrow = (view.overlay.clientWidth || W) < 560; view.hud.textContent = narrow ? `${W}×${H} ${whole.toFixed(0)}ms [${budget}] ${detectPool ? detectPool.size + "w" : "1t"}` + `${luma.path === "videoframe" ? " vf" : " gid"} ` + (pose.ok ? `${c.read}r ${c.located}l ${c.missing}m ${c.misplaced}x` + (pose.offTarget.length ? ` ${pose.offTarget.length}?` : "") + ` rms${pose.rmsResidualPx}` + (loo ? ` loo${loo.worstPx}` : "") + (pose.pose ? ` ${pose.pose.distanceMm}mm ${Math.round(pose.pose.tiltDeg)}°` : ` (${pose.poseWhy})`) : `no plane, ${res.fused.length} read`) + ` ${kept}/${MAX}` : `${W}x${H} ${whole.toFixed(0)}ms frame (cap ${stageMed("cap").toFixed(1)}` + ` gray ${stageMed("gray").toFixed(1)} scan ${stageMed("scan").toFixed(1)}` + ` fit ${stageMed("fit").toFixed(1)} draw ${stageMed("draw").toFixed(1)})` + ` ${detectPool ? detectPool.size + "w" : "1t"}` + ` ${luma.path === "videoframe" ? "luma " + luma.format : "rgba readback" + (luma.why ? " (" + luma.why + ")" : "")} ` + (pose.ok ? `read ${c.read} located ${c.located} missing ${c.missing} misplaced ${c.misplaced}` + (pose.offTarget.length ? ` off ${pose.offTarget.length}` : "") + ` rms ${pose.rmsResidualPx}px` + (loo ? ` loo ${loo.worstPx}px` : "") + ` ${pose.mmPerPx}mm/px` + (pose.pose ? ` ${pose.pose.distanceMm}mm tilt ${pose.pose.tiltDeg}°` : ` (${pose.poseWhy})`) : `no plane — ${res.fused.length} read, need 4 target marks`) + ` cases ${kept}/${MAX}`; view.note.textContent = labelled ? `frame is labellable (difficulty ${difficulty})` : !pose.ok ? "not labellable: no plane" : pose.counts.read < 5 ? `not labellable: only ${pose.counts.read} read — move closer, 5 is the minimum` : !looOk ? `not labellable: leave-one-out ${loo ? loo.worstPx + "px" : "n/a"}` + ` vs ${(LOO_FRAC * rMed).toFixed(0)}px allowed — the plane does not predict its own marks` : `not labellable: rms ${pose.rmsResidualPx}px`; if (t - lastYield > 250) { lastYield = t; yield { w: W, h: H, msMedian: +med.toFixed(1), // the whole frame, stage by stage -- watchable from the pairing channel stages: view.stages(), counts: pose.ok ? pose.counts : null, offTarget: pose.ok ? pose.offTarget.length : 0, rmsPx: pose.ok ? pose.rmsResidualPx : null, looPx: loo ? loo.worstPx : null, mmPerPx: pose.ok ? pose.mmPerPx : null, pose: pose.pose, labelled, difficulty, cases: kept }; } } }3d:Tbf9,hexRigCasePanel = { // What the rig collected, and a way to get it off the page. A case is only // useful later if the LABELS travel with the pixels, so the JSON link // carries the frozen truth positions, the per-mark verdict and the settings // that produced them -- a bare PNG would have to be re-labelled by hand, // which is the work the target exists to avoid. // // The per-mark chips are the point of the strip. Seven ids in fixed print // positions means "the same mark fails every time" and "a different one // fails each time" look completely different at a glance, and they are // different problems: the first is the sheet or the optics, the second is // the detector's margin. const cases = hexRigCases; const COL = { read: "#2fe08a", located: "#ffd23f", missing: "#ff5c5c", misplaced: "#ff9f1c" }; if (!cases.length) return htl.html`

No cases yet. Aim the camera at the printed sheet with the rig running: frames that read 5+ barcodes and still fail on at least one are collected automatically.

`; const bundle = cases.map((c) => ({ name: c.name, w: c.w, h: c.h, labelled: c.labelled, pinned: c.pinned, difficulty: c.difficulty, truth: c.truth, cfg: c.cfg, capture: c.capture })); const jsonHref = "data:application/json," + encodeURIComponent(JSON.stringify(bundle, null, 1)); const chip = (t) => htl.html`${t.id}`; const card = (c) => htl.html`

${c.name} ${c.w}x${c.h}${c.pinned ? " · kept" : ""}

${c.truth.map(chip)}

${c.capture.rmsPx != null ? `rms ${c.capture.rmsPx}px · ${c.capture.mmPerPx}mm/px` : "unlabelled"}${ c.capture.distanceMm != null ? ` · ${c.capture.distanceMm}mm · ${c.capture.tiltDeg}°` : ""}${ c.capture.offTarget ? ` · ${c.capture.offTarget} off-target` : ""}

`; const nLabelled = cases.filter((c) => c.labelled).length; return htl.html`

${cases.length} case${cases.length === 1 ? "" : "s"}, ${nLabelled} labelled — download labels (frames save one at a time; click a thumbnail)

${cases.map(card)}

`; }3e:Td0c,barcodeDemo = { const L = manLayout; const bits = Array.from({ length: L.nBits }, (_, j) => (barcodeId >> (L.nBits - 1 - j)) & 1); const svg = manMarkSvgSource(barcodeId, { diameterMm: 60, label: false }); const img = htl.html`

`; // labelled variant for print: the same mark hexTargetSvg's A4 page lays out const printSvg = manMarkSvgSource(barcodeId, { diameterMm: 60 }); const printHref = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(printSvg); // manColor is piecewise constant between teeth, so one band per tooth // interval is exact -- this strip IS the radial profile, not a sampling of it. const W = 520, H = 46, R = L.R; const x = (r) => (r / R) * W; const bounds = [0, ...L.teeth]; const bands = []; for (let i = 1; i < bounds.length; i++) { const g = manColor((bounds[i - 1] + bounds[i]) / 2, bits, L); bands.push(``); } // Which edges exist for THIS payload: ask manColor either side of each tooth // rather than re-deriving the rule and risking disagreeing with the renderer. const eps = 1e-3; const ticks = []; let nMid = 0, nBoundary = 0; for (let m = 0; m <= L.nT; m++) { const r = L.teeth[m]; const here = manColor(r - eps, bits, L) !== manColor(r + eps, bits, L); const mid = L.guaranteed.indexOf(m) >= 0; if (here && mid) nMid++; if (here && !mid) nBoundary++; if (!here) continue; ticks.push(``); } const strip = htl.html`

`; strip.innerHTML = ``; const key = (c, t) => htl.html` ${t}`; return htl.html`

${img}

download man ${barcodeId} (60mm)

radius → centre to rim

${strip}

id ${barcodeId} = bits ${bits.join("")}

${key("#4ade80", `${nMid} mid edges — one per cell, always`)}${key("#facc15", `${nBoundary} cell boundaries`)}

${nMid + nBoundary} edges to position against on this scan line

`; }3f:T841,hexPrintPanel = { // data: URIs, not blob: -- a file:// page refuses blob: as a resource const svg = hexTargetSvg({ target: hexTarget }); const uri = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(svg); const T = hexTarget; const px = (mm, dPx) => Math.round((mm * dPx) / T.diameterMm); return htl.html`

download A4 target

${T.ids.length} barcodes, ids ${T.ids.join(", ")} — the seven non-zero codewords of a [6,3] code, so no single misread cell can turn one member into another.

${T.diameterMm}mm barcodes, ${T.pitchMm}mm pitch, cluster rotated ${T.rollDeg}°, sheet ${T.widthMm} × ${T.heightMm}mm on A4. Tightest clearance between barcodes that can share a scan row: ${T.minRowGapMm}mm (${T.rowGapInDiscs}× the dark disc it has to beat).

The rotation is not decoration — it is worth more than the pitch is. Over three poses each, rotated reads 7/7/7 barcodes against 3/3/3 upright at this pitch. Why is not established: the obvious explanations (collinear triples, along-row clearance) are both contradicted by the same table, so this is an empirical setting, not a derived one.

Working distance: a barcode needs roughly 4 pixels per tooth, so keep the whole cluster in frame with each barcode above ~${px(T.diameterMm, 60)}px. On a 1280-wide camera that is roughly 0.4–1.2 m from the sheet.

Print at 100%, not "fit to page" — the millimetre geometry is the calibration. Measure the 100mm bar to check.

`; }40:Tfca,hexTargetSvg = function hexTargetSvg(opts = {}) { // The calibration target as one A4 page, mm-sized, same print conventions as // manMarkSvgSource: white page, each mark nested full discs drawn outside-in. // Page level comes from manPageLevel -- see manMarkSvgSource for the // measurement behind white, and for what is still unvalidated. // // No labels inside the cluster. A man mark reads by finding edges along a // scan row, and text sitting in the gap between two marks puts edges exactly // where the segmenter is trying to find background. The legend goes in the // bottom margin, outside the pattern, where it can do no harm. // // PRINT AT 100%. "Fit to page" silently rescales the sheet, and the // millimetre geometry IS the calibration -- every distance the pose fit // reports is in units of it. The 100 mm bar in the legend is there to be // measured with a real ruler: if it is not 100 mm, the print was scaled and // the reported distances are wrong by that factor. const T = opts.target ?? hexTarget; const L = T.layout; // Default from manPageLevel so the printed sheet and the synthetic benches // cannot drift apart. const g = manPageLevel.toString(16).padStart(2, "0"); const pageFill = opts.pageFill ?? `#${g}${g}${g}`; const flooded = pageFill.toLowerCase() !== "#ffffff" && pageFill.toLowerCase() !== "#fff"; const pageW = opts.pageW ?? 210, pageH = opts.pageH ?? 297; const cx0 = opts.cx ?? pageW / 2; const cy0 = opts.cy ?? 110; // cluster centre, leaving a legend below const scale = T.radiusMm / L.R; // mm per layout unit const parts = []; for (const m of T.marks) { const mx = cx0 + m.xMm; const my = cy0 - m.yMm; // sheet y is up, SVG y is down const bounds = [0, ...L.teeth]; for (let i = bounds.length - 1; i >= 1; i--) { const mid = (bounds[i - 1] + bounds[i]) / 2; const dark = manColor(mid, m.bits, L) < 128; parts.push( `` ); } } const legendY = cy0 + T.heightMm / 2 + 18; const rows = T.marks.map( (m) => `id ${String(m.id).padStart(2)} ${m.k == null ? "centre" : "ring " + m.k} x ${m.xMm.toFixed(1).padStart(6)} y ${m.yMm.toFixed(1).padStart(6)}` ); const legend = [ `man hex calibration target · ${T.diameterMm}mm barcodes · pitch ${T.pitchMm}mm · rotated ${T.rollDeg}°`, `PRINT AT 100% — not "fit to page". The bar below must measure 100mm.`, // ruler bar with end ticks ``, ``, ``, `100 mm` ]; rows.forEach((r, i) => { legend.push( `${r}` ); }); legend.push( `millimetres from the centre barcode, +y up.${flooded ? " The gray is part of the pattern — do not trim." : ""}` ); return ``; }41:T138a,makeHexTarget = function makeHexTarget(opts = {}) { // A calibration target: seven man marks at KNOWN positions on one sheet of // paper, in a hexagonal cluster (one centre, six at 60 degree spacing). // // Why a cluster of known geometry rather than seven loose marks. A single // mark gives a centre, a size and (when the fit is good) a tilt magnitude -- // but no orientation, no scale in world units, and no way to tell a bad fit // from a good one. Seven coplanar marks whose relative positions are known // in millimetres give a HOMOGRAPHY: four detections determine the plane // pose, and every detection past the fourth is a residual, an independent // statement about whether the others were right. That is what makes it // useful in a cluttered scene -- it can say which marks read, which did not, // and where the missing ones should have been. // // The ids are not arbitrary. They are the seven non-zero codewords of a // [6,3] linear code, pairwise Hamming distance 3, so a single misread cell // cannot turn one member of the target into another. A misread lands on an // id that is not on the sheet, where it is discarded as off-target rather // than silently swapping two landmarks. // // THE CLUSTER IS PRINTED ROTATED 30 DEGREES, and that matters more than the // pitch. Measured over three poses at each setting (hexPitchSweep, apparent // diameter held fixed), marks read out of 7: // // pitch upright rotated 30 // 1.25 3/6/4 3/7/5 // 1.45 3/3/3 7/7/7 // 1.70 2/2/2 7/7/7 // // The effect is large, consistent across pitch, and reproduces on a cold // boot. WHY it happens is not established. Two plausible mechanisms have // already been tried and killed by this same table: // - "rotation breaks up collinear triples" is backwards. Upright, no three // marks share a row; rotated, the middle three do. // - "rotation widens the tightest along-row clearance" is necessary but // not sufficient. It is true (minRowGapMm below, 12.3mm -> 21.6mm at // pitch 1.45) and it does explain why 1.25 is poor either way, but // upright at pitch 1.70 has MORE clearance (22.7mm) than rotated at 1.45 // and still reads 2/2/2. // So minRowGapMm is kept as a diagnostic, not as the explanation. Something // about the upright arrangement specifically defeats the row cascade, and // finding out what is worth a section of its own -- it is a statement about // the detector, not about this sheet. const L = opts.layout ?? manLayout; const ids = opts.ids ?? [56, 11, 22, 29, 37, 46, 51]; // centre, then ring k=0..5 const diameterMm = opts.diameterMm ?? 48; const pitchFactor = opts.pitchFactor ?? 1.45; const rollDeg = opts.rollDeg ?? 30; const pitchMm = +(diameterMm * pitchFactor).toFixed(3); const radiusMm = diameterMm / 2; const mmPerUnit = radiusMm / L.R; const bitsOf = (id) => Array.from({ length: L.nBits }, (_, j) => (id >> (L.nBits - 1 - j)) & 1); // ring index k at angle 90 + 60k + roll, in sheet coordinates (+y up, // millimetres, origin at the centre mark) const marks = ids.map((id, i) => { if (i === 0) return { id, k: null, xMm: 0, yMm: 0, bits: bitsOf(id) }; const k = i - 1; const a = ((90 + 60 * k + rollDeg) * Math.PI) / 180; return { id, k, xMm: +(pitchMm * Math.cos(a)).toFixed(4), yMm: +(pitchMm * Math.sin(a)).toFixed(4), bits: bitsOf(id) }; }); // Smallest horizontal clearance among pairs whose row bands overlap, i.e. // pairs that can land in one scan row together. This is the quantity // manRowGroups has to work with, and it is NOT the pitch: a mark can sit // between two others that are offset vertically. Compare it against the dark // disc (12 of 57 layout units), the widest gap a single mark may contain -- // below about one disc, no gap rule can tell two marks from one. let minRowGapMm = Infinity; for (let i = 0; i < marks.length; i++) { for (let j = i + 1; j < marks.length; j++) { if (Math.abs(marks[i].yMm - marks[j].yMm) >= diameterMm) continue; // bands miss minRowGapMm = Math.min(minRowGapMm, Math.abs(marks[i].xMm - marks[j].xMm) - diameterMm); } } const ext = (sel) => Math.max(...marks.map((m) => Math.abs(sel(m)))); return { ids, marks, diameterMm, radiusMm, pitchMm, pitchFactor, rollDeg, mmPerUnit, layout: L, byId: new Map(marks.map((m) => [m.id, m])), minRowGapMm: Number.isFinite(minRowGapMm) ? +minRowGapMm.toFixed(2) : null, rowGapInDiscs: Number.isFinite(minRowGapMm) ? +(minRowGapMm / (2 * 6 * mmPerUnit)).toFixed(2) : null, // bounding box of the printed cluster, marks included -- computed from the // rotated positions, since the rotation changes which way it is widest widthMm: +(2 * ext((m) => m.xMm) + diameterMm).toFixed(2), heightMm: +(2 * ext((m) => m.yMm) + diameterMm).toFixed(2) }; }42:Taa2,hexPrintCheck = { // Read the THING THAT GETS PRINTED, not a parallel model of it. // // hexPitchSweep renders the target through its own plane renderer, which is // the right tool for sweeping poses but shares no code with hexTargetSvg. // A wrong radius, a mark at the wrong millimetre, or a legend that strays // into the pattern would sail straight through it. So this rasterises the // actual A4 SVG the download button hands over, and checks the cascade reads // it and lands where the millimetre geometry says it should. const T = hexTarget; const svg = hexTargetSvg({ target: T }); const pageW = 210, pageH = 297, cx0 = pageW / 2, cy0 = 110; // must match hexTargetSvg const uri = "data:image/svg+xml;charset=utf-8," + encodeURIComponent(svg); const img = new window.Image(); await new Promise((res, rej) => { img.onload = res; img.onerror = () => rej(new Error("could not rasterise the target SVG")); img.src = uri; }); const out = []; for (const pxPerMm of [3, 2, 1.5]) { const W = Math.round(pageW * pxPerMm), H = Math.round(pageH * pxPerMm); const cv = window.document.createElement("canvas"); cv.width = W; cv.height = H; const ctx = cv.getContext("2d"); ctx.drawImage(img, 0, 0, W, H); const px = ctx.getImageData(0, 0, W, H).data; const gray = new Uint8Array(W * H); for (let i = 0, p = 0; i < gray.length; i++, p += 4) gray[i] = (px[p] * 77 + px[p + 1] * 150 + px[p + 2] * 29) >> 8; const res = analyzeFrameMan({ gray, w: W, h: H }, { stride: 4 }); const pose = fitHexPose({ ...res, w: W, h: H }, { target: T }); // where each mark must be, straight from the mm layout and the raster scale const truth = new Map( T.marks.map((m) => [m.id, { x: (cx0 + m.xMm) * pxPerMm, y: (cy0 - m.yMm) * pxPerMm }]) ); const onTarget = res.fused.filter((f) => truth.has(f.id)); const errs = onTarget.map((f) => Math.hypot(f.xc - truth.get(f.id).x, f.yc - truth.get(f.id).y) ); out.push({ pxPerMm, raster: `${W}x${H}`, markPx: Math.round(T.diameterMm * pxPerMm), read: onTarget.length, ids: onTarget.map((f) => f.id).sort((a, b) => a - b), offTarget: res.fused.filter((f) => !truth.has(f.id)).map((f) => f.id), worstErrPx: errs.length ? +Math.max(...errs).toFixed(2) : null, // the scale the fit recovers, against the scale we rasterised at mmPerPx: pose.ok ? pose.mmPerPx : null, mmPerPxTrue: +(1 / pxPerMm).toFixed(3), located: pose.ok ? pose.counts.located : null, missing: pose.ok ? pose.counts.missing : null, rms: pose.ok ? pose.rmsResidualPx : null, ms: +res.ms.toFixed(0) }); } return out; }43:Tbac,hexOverlay = { // The detection overlay, in one place. Lifted verbatim out of hexFrameReport on // 2026-08-10 when the taster at the top needed the same picture: two copies of // this would drift, and a taster that draws a mark differently from the report // below it is worse than no taster. const COL = { read: "#2fe08a", located: "#ffd23f", missing: "#ff5c5c", misplaced: "#ff9f1c", off: "#d264ff" }; // Returns SVG source, not nodes -- the caller sets innerHTML, because htl would // escape a string built as markup. const parts = (pose, res) => { const parts = []; if (pose.ok) { for (const m of pose.marks) { const c = COL[m.state]; const r = m.radiusPx; const dash = m.state === "read" ? "none" : m.state === "located" ? "7 5" : "2 6"; // Same shape the rig draws: the projected circle, not a circle. On a // tilted sheet the two differ by the tilt, and a ring that does not sit // on its mark reads as a tracking error rather than as a drawing one. const top = m.outline ? Math.min(...m.outline.map((p) => p[1])) : m.predicted.y - r; const shape = m.outline ? `` + `${m.id}` ); } // A detection that fits the involution but sits nowhere the plane goes is // the failure the background is in this bank to provoke, so it is drawn // rather than counted away. for (const o of pose.offTarget) parts.push( ` ` ); } else { // No homography here, but fitManPose measured both semi-axes -- a along // the scan, b across it -- so an axis-aligned ellipse is still closer to // the mark than a circle of a. for (const f of res.fused) { const ra = f.a ?? f.wHalf ?? 24; parts.push( `` ); } } return parts.join(""); }; return { COL, parts }; }44:T15aa,hexFrameReport = { // Replay every banked frame through the shipping cascade and show what it // makes of each one. No pass/fail bars: this bank grows as more conditions get // photographed, and a bar per frame would mean setting one by hand on every // arrival and going red on the first genuinely hard capture. The rendered // rendered scenes and the mirror bank in §3 are where the tripwires live; this // is where the ground truth about REAL optics lives, and its job is to be // looked at. // Seconds of work that nothing above it reads: hold it until the cell is on screen. await whenVisible("hexFrameReport", invalidation); const COL = hexOverlay.COL; const cards = []; let nowRead = 0, thenRead = 0, marks = 0, spurious = 0; for (const b of hexFrameBank) { const t0 = window.performance.now(); const res = analyzeFrameMan({ gray: b.frame.gray, w: b.frame.w, h: b.frame.h }, { stride: 4 }); const pose = fitHexPose({ ...res, w: b.frame.w, h: b.frame.h }); const ms = window.performance.now() - t0; // One copy of the drawing, shared with the taster at the top: hexOverlay.parts. const parts = hexOverlay.parts(pose, res); if (pose.ok) { nowRead += pose.counts.read; spurious += pose.offTarget.length; } // Why a bad frame is bad, measured on the frame rather than asserted about it. // "missing" means missing FROM THE PREDICTION, and with four detections the // prediction is an extrapolation off an exactly-determined homography -- so // this asks the two questions the count cannot: how far the prediction landed // from the recorded label, and whether a posed-but-unread cluster is sitting // at the label anyway. // // hexcase-5ivq-06 is the frame that prompted it (2026-08-10): 4 of 7 read, the // other three predicted 149/160/189px from their labels at radii 6/6/35px // against a true 34/38/39 -- and mark 51 had a 15-row posed cluster 1px from // its label the whole time. It fires on 7 of the 16 frames. let diag = ""; if (pose.ok && pose.counts.missing) { const truthById = new Map((b.truth ?? []).map((t) => [t.id, t])); const lines = []; for (const m of pose.marks) { if (m.state !== "missing") continue; const t = truthById.get(m.id); if (!t) continue; const off = Math.hypot(m.predicted.x - t.x, m.predicted.y - t.y); let near = null; for (const u of res.unidentified) { const d = Math.hypot(u.xc - t.x, u.yc - t.y); if (!near || d < near.d) near = { d, u }; } lines.push( `${m.id}: predicted ${off.toFixed(0)}px from its label` + (near && near.d < (t.radiusPx ?? 40) ? `, but a cluster of ${near.u.rows} rows sits ${near.d.toFixed(0)}px from it` : ", and nothing is at the label either") ); } if (lines.length) diag = lines.join(" · "); } thenRead += b.capture.read ?? 0; marks += (b.truth ?? []).length; // innerHTML rather than interpolation: htl escapes a string, and these are // built as SVG source const overlay = htl.svg``; overlay.innerHTML = parts; const chip = (m) => htl.html`${m.id}`; cards.push({ portrait: b.frame.h > b.frame.w, node: htl.html`

${b.name} · ${b.frame.w}×${b.frame.h} · ${ms.toFixed(0)}ms
${b.capture.distanceMm ? `${b.capture.distanceMm}mm · ${b.capture.tiltDeg}° · ` : ""}${ pose.ok ? `${pose.counts.read}/7 read` : "no plane"}${ pose.ok && pose.offTarget.length ? ` · ${pose.offTarget.length} off-target` : ""}
${pose.ok ? pose.marks.map(chip) : ""}
${diag ? htl.html`
${diag}
` : ""}

` }); } // Cards are a fixed width, so a wrapped row is as tall as its tallest member // and a landscape frame beside a portrait one pays for the difference in white // space. Grouping by orientation makes every row homogeneous except the seam. const ordered = [ ...cards.filter((c) => !c.portrait), ...cards.filter((c) => c.portrait) ].map((c) => c.node); return htl.html`

${nowRead} of ${marks} marks read now, ${thenRead} when captured${ spurious ? `, ${spurious} off-target detection${spurious === 1 ? "" : "s"}` : ", no off-target detections"}. solid = read · dashed = located, payload did not decode · dotted = missing · ✕ = fitted an involution somewhere the plane does not go

${ordered}

`; }45:T11a4,hexBankScores = { // Scored against the frozen labels, not against a plane fitted to this // frame's own detections -- the same distinction the rig makes (see // hexRigScore). fitHexPose is right for the live overlay and circular for // tuning, so §3.2's cards and this table will disagree, and the disagreement // is the point: a mark can be placed consistently with the other six and // still be in the wrong place. // // Reads hexRigOpts, so it is the rig's controls that move it, not a second // set of knobs. Costs a full cascade pass over sixteen frames; hold it until // it is on screen. await whenVisible("hexBankScores", invalidation); const rows = []; const tot = { marks: 0, read: 0, located: 0, missing: 0, misplaced: 0, off: 0, score: 0, ms: 0 }; for (const b of hexFrameBank) { const res = analyzeFrameMan({ gray: b.frame.gray, w: b.frame.w, h: b.frame.h }, hexRigOpts); const s = hexRigScore(res, b.truth); // Residuals over every mark the cascade placed, misplaced ones included: // dropping those would flatter the median by exactly the marks that matter. const d = s.marks.map((m) => m.residualPx).filter((x) => x != null).sort((x, y) => x - y); const row = { name: b.name, size: b.frame.w + "×" + b.frame.h, read: s.counts.read, located: s.counts.located, missing: s.counts.missing, misplaced: s.counts.misplaced, off: s.offTarget.length, p50: d.length ? +d[d.length >> 1].toFixed(1) : null, worst: d.length ? +d[d.length - 1].toFixed(1) : null, ms: Math.round(res.ms), score: s.score }; rows.push(row); tot.marks += b.truth.length; for (const k of ["read", "located", "missing", "misplaced", "off", "score", "ms"]) tot[k] += row[k]; } const num = (v, bad) => htl.html`${v == null ? "–" : v}`; const th = (t, title) => htl.html`${t}`; return htl.html`

${th("size", "frame the label set was measured on")} ${th("read", "id decoded and centre within 0.6 of the label's radius")} ${th("loc", "involution fitted at the barcode, payload did not decode")} ${th("miss", "nothing fitted there")} ${th("wrong", "id decoded but the centre is not at that label")} ${th("off", "id decoded somewhere the target has no barcode")} ${th("p50 px", "median distance from label, over every barcode placed")} ${th("worst px", "largest such distance")} ${th("ms", "one cascade pass over the whole frame")} ${th("score", "read − 3 × (wrong + off): a false id costs more than a miss")} ${rows.map((r) => htl.html` ${num(r.read + "/7", r.read < 7)}${num(r.located)}${num(r.missing, r.missing > 0)} ${num(r.misplaced, r.misplaced > 0)}${num(r.off, r.off > 0)} ${num(r.p50)}${num(r.worst, r.worst > 4)}${num(r.ms)}${num(r.score, r.score < 7)} `)} ${htl.html``} ${[tot.located, tot.missing, tot.misplaced, tot.off, "", "", tot.ms, tot.score].map((v) => htl.html``)}

frame
${r.name}	${r.size}
16 frames		${tot.read}/${tot.marks}	${v}

stride ${hexRigOpts.stride} · edge threshold ${hexRigOpts.edgeThreshold} · min rows ${hexRigOpts.minRows} · min votes ${hexRigOpts.minVotes} · ${hexRigOpts.bothAxes ? "both axes" : "rows only"}

`; }46:T38e0,encodingDiagram = { // The u = r^2 claim, computed rather than drawn. A real pinhole pose puts the // mark on a plane at some yaw and tilt; a HORIZONTAL image row cuts it; the // crossings that row sees are plotted against the tooth lattice. Nothing is // placed by hand -- if the claim is wrong the points bend, and the residual // alongside says so. // // Not every tooth shows up as an edge: the boundary between two cells exists // only where their bits agree, so the lattice positions that carry no edge // are drawn faint. Those are the ones a detector cannot see, and they are // excluded from the fit. const L = manLayout; const cfg = encodingCfg; const bits = Array.from({ length: L.nBits }, (_, j) => (cfg.id >> (L.nBits - 1 - j)) & 1); const rad = Math.PI / 180; // ---- pose --------------------------------------------------------------- const ps = cfg.yaw * rad, th = cfg.tilt * rad; const c1 = [Math.cos(ps), Math.sin(ps) * Math.sin(th), -Math.sin(ps) * Math.cos(th)]; const c2 = [0, Math.cos(th), Math.sin(th)]; const FL = 600, Z0 = 240; const H = [ [FL * c1[0], FL * c2[0], 0], [FL * c1[1], FL * c2[1], 0], [c1[2], c2[2], Z0] ]; const inv3 = (m) => { const [[a, b, c], [d, e, f], [g, h, i]] = m; const A0 = e * i - f * h, B0 = -(d * i - f * g), C0 = d * h - e * g; const det = a * A0 + b * B0 + c * C0; return [ [A0 / det, -(b * i - c * h) / det, (b * f - c * e) / det], [B0 / det, (a * i - c * g) / det, -(a * f - c * d) / det], [C0 / det, -(a * h - b * g) / det, (a * e - b * d) / det] ]; }; const ap = (m, v) => [ m[0][0] * v[0] + m[0][1] * v[1] + m[0][2] * v[2], m[1][0] * v[0] + m[1][1] * v[1] + m[1][2] * v[2], m[2][0] * v[0] + m[2][1] * v[1] + m[2][2] * v[2] ]; const Hi = inv3(H); const fwd = (X, Y) => { const q = ap(H, [X, Y, 1]); return [q[0] / q[2], q[1] / q[2]]; }; const back = (x, y) => { const q = ap(Hi, [x, y, 1]); return [q[0] / q[2], q[1] / q[2]]; }; const NA = 160; const ringPts = (r) => Array.from({ length: NA }, (_, i) => { const a2 = (i / NA) * 2 * Math.PI; return fwd(r * Math.cos(a2), r * Math.sin(a2)); }); const poly = (r) => ringPts(r).map((p) => p[0].toFixed(1) + "," + p[1].toFixed(1)).join(" "); const rim = ringPts(L.R); const xs0 = rim.map((p) => p[0]), ys0 = rim.map((p) => p[1]); const bx0 = Math.min(...xs0), bx1 = Math.max(...xs0); const by0 = Math.min(...ys0), by1 = Math.max(...ys0); const ctr = fwd(0, 0); const rowY = ctr[1] + cfg.row * Math.min(ctr[1] - by0, by1 - ctr[1]); // a homography takes a line to a line, so two pullbacks fix the chord exactly const pA = back(bx0 - 40, rowY), pB = back(bx1 + 40, rowY); const ex0 = pB[0] - pA[0], ey0 = pB[1] - pA[1]; const en = Math.hypot(ex0, ey0), ex = ex0 / en, ey = ey0 / en; const along = pA[0] * ex + pA[1] * ey; const footX = pA[0] - along * ex, footY = pA[1] - along * ey; const d = Math.hypot(footX, footY); const Pimg = fwd(footX, footY)[0]; const qh = ap(H, [ex, ey, 0]); const qFinite = Math.abs(qh[2]) > 1e-9; const Qimg = qFinite ? qh[0] / qh[2] : null; const norm = (x) => (qFinite ? (x - Pimg) / (x - Qimg) : (x - Pimg) * 1e-3); const eps = 1e-4; const pts = []; for (let m = 0; m <= L.nT; m++) { const r = L.teeth[m]; if (r <= d) continue; const s = Math.sqrt(r * r - d * d); const R1 = fwd(footX + s * ex, footY + s * ey); const R2 = fwd(footX - s * ex, footY - s * ey); const uR = norm(R1[0]) ** 2, uL = norm(R2[0]) ** 2; pts.push({ m, r, r2: r * r, s, pR: R1, pL: R2, u: (uR + uL) / 2, uGap: Math.abs(uR - uL), // does this tooth actually produce an intensity step for this payload? edge: manColor(r - eps, bits, L) !== manColor(r + eps, bits, L) }); } const MUT = "var(--theme-foreground-muted,#888)"; const FG = "var(--theme-foreground,#ccc)"; const GRN = "#2fe08a", YEL = "#f5a524", GHOST = "#7a7a7a"; const svgEl = (vb, body) => { const el = htl.html`

`; el.innerHTML = ``; return el; }; const txt = (x, y, s, o = {}) => `${s}`; if (pts.length < 3) return htl.html`

the row misses the barcode at this pose — move the scan row slider back toward 0

`; const seen = pts.filter((p) => p.edge); const fitOn = seen.length >= 3 ? seen : pts; // ---- A: the mark as the camera sees it, with the row across it ---------- // A FIXED box, not the pose's bounding box: the mark centre always projects // to the origin, and 78 clears the widest projection the sliders can reach // (worst half-extent 71.8px, face-on 71.25px), so the panel never resizes. // The extra 14 below is the caption strip. const HALF = 78; const vbA = `${-HALF} ${-HALF} ${2 * HALF} ${2 * HALF + 14}`; // the outermost ring is black and so is the page, so the mark's rim needs // something to sit against let a = ``; const bounds = [0, ...L.teeth]; for (let i = bounds.length - 1; i >= 1; i--) { const g = manColor((bounds[i - 1] + bounds[i]) / 2, bits, L); a += ``; } a += ``; // d is the offset: centre to the row, measured perpendicular ON THE MARK, // which is why the segment is drawn from the centre and not straight up const footImg = fwd(footX, footY); a += ``; const tick = (x, col, len, w) => ``; for (const p of pts) { if (p.edge) { a += tick(p.pR[0], GRN, 6, 1.8) + tick(p.pL[0], YEL, 6, 1.8); } else { a += tick(p.pR[0], GHOST, 3, 0.8) + tick(p.pL[0], GHOST, 3, 0.8); } } a += ``; a += ``; // label the segment, on the side of it away from the mark's centre { const mxd = (ctr[0] + footImg[0]) / 2, myd = (ctr[1] + footImg[1]) / 2; const vx = footImg[0] - ctr[0], vy = footImg[1] - ctr[1]; const vn = Math.hypot(vx, vy) || 1; const nx = -vy / vn, ny = vx / vn; a += txt(mxd + nx * 7, myd + ny * 7 + 2, "d", { fill: "#5af", size: 8, style: "italic" }); } a += txt(footImg[0] + 9, footImg[1] - 4, "P", { fill: "#5af", size: 7 }); a += txt(0, HALF + 10, `yaw ${cfg.yaw}° · tilt ${cfg.tilt}° · d = ${d.toFixed(2)}`, { size: 7 }); // ---- B: the crossings as the row delivers them -------------------------- const rxs = pts.flatMap((p) => [p.pL[0], p.pR[0]]); const mnx = Math.min(...rxs, Pimg), mxx = Math.max(...rxs, Pimg); const bw = 250, sxb = (x) => 4 + ((x - mnx) / (mxx - mnx || 1)) * (bw - 8); // headroom above the row for the pairing arcs const AH = 40; let b = ``; // The involution, drawn. One arc per ring, joining that ring's two crossings: a single // projective map on this row carries every left crossing to its right one, the same map // for all of them, and P is one of the two points it leaves alone. pts.forEach((p, i) => { const x1 = sxb(p.pL[0]), x2 = sxb(p.pR[0]); const hh = 8 + (i / Math.max(1, pts.length - 1)) * 26; b += ``; }); for (const p of pts) { const c1c = p.edge ? GRN : GHOST, c2c = p.edge ? YEL : GHOST; const h = p.edge ? 7 : 3.5, w = p.edge ? 1.5 : 0.7; b += ``; b += ``; } // P runs the full height of the arc stack -- the arcs nest about it because it is fixed b += ``; b += txt(sxb(Pimg), -18, "P", { fill: "#5af", size: 6 }); b += txt(0, -30, "each arc joins one ring's two crossings", { size: 6, anchor: "start", fill: "#5af" }); b += txt(bw, 44, qFinite ? `Q at x = ${Qimg.toFixed(0)}` : "Q at infinity", { fill: "#5af", size: 6, anchor: "end" }); b += txt(0, 44, "one image row — the lattice is gone", { size: 6, anchor: "start" }); // ---- C: u against the lattice ------------------------------------------ const n = fitOn.length; const mx = fitOn.reduce((s2, p) => s2 + p.r2, 0) / n; const my = fitOn.reduce((s2, p) => s2 + p.u, 0) / n; const A = fitOn.reduce((s2, p) => s2 + (p.r2 - mx) * (p.u - my), 0) / fitOn.reduce((s2, p) => s2 + (p.r2 - mx) ** 2, 0); const B = my - A * mx; const resid = Math.max(...fitOn.map((p) => Math.abs(p.u - (A * p.r2 + B)))); const us = fitOn.map((p) => p.u); const span = Math.max(...us) - Math.min(...us); const pairGap = Math.max(...fitOn.map((p) => p.uGap)); const dHat = Math.sqrt(Math.max(0, -B / A)); const cw = 330, ch = 158, padL = 30, padB = 30; // BOTH axes fixed, like panel A above. u used to be scaled to the data // (max(u) * 1.08), which normalised away the thing the panel is for: the // fitted line came out at roughly the same angle at every pose, so moving the // tilt slider changed the numbers and not the picture. // // The bound is measured, not guessed. Driving the real cell over the sliders' // full range and reading its own A and B, u at the rim (A*R^2 + B) spans // 0.00165 to 0.01389 across 106 poses that the row actually crosses, median // 0.00508 (2026-08-11). Largest at yaw -70, tilt -70, row 0, which is where // the chord is longest -- so row 0 is the maximum by construction and not by // luck of the sampling. 0.0145 clears it by 4%. // // Nothing clamps: a point past the top draws outside the axes, because the // panel overflows visibly, and an off-scale point is information. const U_TOP = 0.0145; const rx1 = L.R * L.R * 1.05, uy1 = U_TOP; const px = (v) => padL + (v / rx1) * (cw - padL - 6); const py = (v) => ch - padB - (v / uy1) * (ch - padB - 12); let c = `` + ``; c += ``; c += ``; c += txt(px(d * d), py(0) + 12, "d² = -B/A", { fill: "#5af", size: 6 }); for (const p of pts) { const X = px(p.r2), Y = py(p.u); if (!p.edge) { c += ``; continue; } const R2 = 4.2; c += ``; c += ``; c += ``; } c += txt((cw + padL) / 2, ch - 8, "r² — the tooth lattice, known in advance", { size: 6.5 }); c += `u = t² measured`; const stat = (label, value) => htl.html`

${label} ${value}

`; return htl.html`

${svgEl(vbA, a)}

${svgEl(`0 ${-AH} ${bw} ${48 + AH}`, b)}

${svgEl(`0 0 ${cw} ${ch}`, c)}

${stat("rings crossed", `${pts.length} of ${L.nT + 1}`)} ${stat("of those, edges", `${seen.length}${seen.length < 3 ? " (too few — fitting all)" : ""}`)} ${stat("A", A.toExponential(4))} ${stat("B", B.toExponential(4))} ${stat("d recovered", `${dHat.toFixed(6)} (true ${d.toFixed(6)})`)} ${stat("max residual / span", resid === 0 ? "0" : (resid / span).toExponential(1))} ${stat("max |u_left - u_right|", pairGap.toExponential(1))}

d is the offset — centre of the barcode to the scan row, measured on the barcode, in the same units as the tooth radii. It is the one pose quantity the row gives back on its own, as √(-B/A).

A tooth only shows an edge where the two cells either side of it carry the same bit; the rest are drawn faint and left out of the fit. Each solid marker is half green / half orange — the ring's two crossings, at opposite ends of the row, landing on one u. Move the sliders: the row changes completely, the line does not.

`; }47:Tbf2,manMarkSvgSource = function manMarkSvgSource(id, opts = {}) { // A man mark as standalone SVG, mm-sized: page flood, nested full discs // outside-in. ALL 64 ids are usable -- Manchester guarantees a transition // per cell, so no payload ever resembles featureless paint. // // The page is white. The mark ends in a dark framing half-cell, so its rim // edge never needed a gray page -- on white that edge is 25->255 rather than // 25->128, larger and the same polarity. Rendered, white measures BETTER: // over nine poses of renderHexScene scored against the renderer's own truth, // 63 marks read against 60, and worst-case residual 9.4px -> 2.2px at // yaw45/tilt20. It also stops flooding a whole A4 sheet with ink. // // The mid-gray it replaced had no recorded motivation anywhere -- not in the // prose, not in the comments, not in the commit that designed this mark // family. Nothing in the detector reads the page level. // // STILL UNVALIDATED ON PAPER (2026-08-09): all 174 archived captures are of a // gray sheet, so what auto-exposure does with a frame full of white paper is // measured by nobody. Set manPageLevel back to 128 to print the old sheet AND // score it on the synthetic benches, if a capture session says the flood was // earning something after all. const L = opts.layout ?? manLayout; const bits = Array.from({ length: L.nBits }, (_, j) => (id >> (L.nBits - 1 - j)) & 1); const dMm = opts.diameterMm ?? 60; const padFrac = opts.padFrac ?? 0.35; const label = opts.label !== false; // Default from manPageLevel so the printed sheet and the synthetic benches // cannot drift apart. const g = manPageLevel.toString(16).padStart(2, "0"); const pageFill = opts.pageFill ?? `#${g}${g}${g}`; // Label contrast has to follow the page, or a white sheet prints a white label. const pageLum = ((v) => (0.299 * ((v >> 16) & 255) + 0.587 * ((v >> 8) & 255) + 0.114 * (v & 255)))( parseInt(pageFill.replace("#", ""), 16) || 0); const labelFill = pageLum > 160 ? "#4a4a4a" : "#e8e8e8"; const scale = dMm / 2 / L.R; const half = L.R * (1 + padFrac) * scale; const w = +(2 * half).toFixed(3); const labelMm = label ? 6 : 0; const h = +(w + labelMm).toFixed(3); // band boundaries 0, teeth..., R; color from the radial profile midpoint const bounds = [0, ...L.teeth]; const discs = []; for (let i = bounds.length - 1; i >= 1; i--) { const mid = (bounds[i - 1] + bounds[i]) / 2; const dark = manColor(mid, bits, L) < 128; discs.push( `` ); } return ``; }48:Tc2a,renderManFrame = function renderManFrame(bits, opts = {}) { // Synthetic 2-D frame of one man mark under a pinhole yaw homography. // Mark plane spanned by u=(cos p,0,sin p), v=(0,1,0) at distance Z. // Inverse map: xm = a1 Z/(cos p - a1 sin p), ym = b1 (Z + xm sin p). // Seeded noise so a given (bits, opts) is reproducible. const L = opts.layout ?? manLayout; const W = opts.W ?? 60; // apparent halfwidth at frontal, px const phi = ((opts.yawDeg ?? 0) * Math.PI) / 180; const blur = opts.blur ?? 1.0; const noise = opts.noise ?? 3; const seed = opts.seed ?? 1; const R = L.R, Z = 400; const f = (W * Z) / R; const c = Math.cos(phi), s = Math.sin(phi); const xPlus = (f * R * c) / (Z + R * s), xMinus = (-f * R * c) / (Z - R * s); const bV = (f * R) / Z; const mx = 25; const w = Math.ceil(xPlus - xMinus + 2 * mx); const h = Math.ceil(2 * bV + 2 * mx); const cx = mx - xMinus, cy = h / 2; const SS = 2; const hi = new Float64Array(w * SS * h * SS); for (let py = 0; py < h * SS; py++) { const b1 = ((py + 0.5) / SS - cy) / f; for (let px = 0; px < w * SS; px++) { const a1 = ((px + 0.5) / SS - cx) / f; const den = c - a1 * s; let v = manPageLevel; // degenerate ray: the page, not the mark if (Math.abs(den) > 1e-9) { const xm = (a1 * Z) / den; const ym = b1 * (Z + xm * s); v = manColor(Math.hypot(xm, ym), bits, L); } hi[py * w * SS + px] = v; } } const img = new Float64Array(w * h); for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) { let acc = 0; for (let dy = 0; dy < SS; dy++) for (let dx = 0; dx < SS; dx++) acc += hi[(y * SS + dy) * w * SS + x * SS + dx]; img[y * w + x] = acc / (SS * SS); } const rad = Math.max(1, Math.ceil(3 * blur)); const ker = new Float64Array(2 * rad + 1); let ks = 0; for (let i = -rad; i <= rad; i++) ks += ker[i + rad] = Math.exp((-i * i) / (2 * blur * blur)); const tmp = new Float64Array(w * h); for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) { let acc = 0; for (let i = -rad; i <= rad; i++) acc += img[y * w + Math.min(w - 1, Math.max(0, x + i))] * ker[i + rad]; tmp[y * w + x] = acc / ks; } // mulberry32 + Box-Muller, seeded let st = seed | 0; const rnd = () => { st = (st + 0x6d2b79f5) | 0; let t = Math.imul(st ^ (st >>> 15), 1 | st); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; }; const gauss = () => { const u = Math.max(1e-12, rnd()), v2 = rnd(); return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v2); }; const gray = new Uint8Array(w * h); for (let x = 0; x < w; x++) for (let y = 0; y < h; y++) { let acc = 0; for (let i = -rad; i <= rad; i++) acc += tmp[Math.min(h - 1, Math.max(0, y + i)) * w + x] * ker[i + rad]; gray[y * w + x] = Math.max(0, Math.min(255, Math.round(acc / ks + noise * gauss()))); } return { gray, w, h, cx, cy, aTrue: (xPlus - xMinus) / 2, bTrue: bV, yawDeg: opts.yawDeg ?? 0 }; }49:T4f7,manScene = { // One 960x540 frame with four man marks of different sizes and yaws, plus the // truth the renderer used to draw them. Shared by every whole-frame check // that wants a known answer (manSceneTest, manAxesTest) so they cannot end up // measuring subtly different scenes and disagreeing for the wrong reason. const SCENE = [ { id: 45, W: 55, yaw: 0, x: 150, y: 140 }, { id: 9, W: 40, yaw: 30, x: 430, y: 130 }, { id: 62, W: 70, yaw: 50, x: 700, y: 300 }, { id: 21, W: 33, yaw: 15, x: 300, y: 400 } ]; const W = 960, H = 540; const gray = new Uint8Array(W * H).fill(manPageLevel); const truth = []; for (const m of SCENE) { const bits = []; for (let i = manLayout.nBits - 1; i >= 0; i--) bits.push((m.id >> i) & 1); const f = renderManFrame(bits, { W: m.W, yawDeg: m.yaw, blur: 1.0, noise: 3, seed: m.id }); for (let y = 0; y < f.h; y++) { const ty = m.y + y; if (ty < 0 || ty >= H) continue; for (let x = 0; x < f.w; x++) { const tx = m.x + x; if (tx < 0 || tx >= W) continue; gray[ty * W + tx] = f.gray[y * f.w + x]; } } truth.push({ ...m, xc: m.x + f.cx, yc: m.y + f.cy, aTrue: f.aTrue, bTrue: f.bTrue }); } return { gray, w: W, h: H, truth }; }4a:T957,rowWalkRow = { // One row, every stage kept rather than thrown away. This runs the SAME // functions the detector runs -- edges1Dsub, manRowGroups, findInvolution, // solveMan -- so nothing here can drift from what §4.2 describes. const b = hexFrameBank[rowWalkCfg.frame]; const { gray, w, h } = b.frame; const y = Math.max(0, Math.min(h - 1, Math.round(rowWalkCfg.rowFrac * (h - 1)))); const thr = rowWalkCfg.thr; const edges = edges1Dsub(gray.subarray(y * w, (y + 1) * w), thr); const xs = new Float64Array(edges.length), ss = new Int8Array(edges.length); edges.forEach((e, i) => { xs[i] = e.x; ss[i] = e.s; }); const kept = detectRowMan(edges, {}); const claimed = new Set(); const groups = manRowGroups(xs, {}).map(([lo, hi], gi) => { const sub = []; for (let i = lo; i <= hi; i++) sub.push({ x: xs[i], s: ss[i] }); const iv = findInvolution(sub, {}); const sol = iv ? solveMan(iv, manLayout, {}) : null; // detectRowMan's own gates, restated so the display can say WHY a group died let why = !iv ? "no involution fits" : !sol.ok ? "no lattice assignment" : sol.sup < 5 ? `lattice support ${sol.sup} < 5` : null; let survives = false; if (!why) { const pOut = iv.up[iv.up.length - 1]; const wHalf = (iv.xs[pOut.f] - iv.xs[pOut.e]) / 2; // Two different ways a passing group still yields nothing, and they are // not the same thing. offerWhole submits one run twice (whole and split), // so the second copy is the SAME lock at the same foot. A different foot // inside a taken lock's span is a rival, dropped by detectRowMan's // overlap rule -- ties go to whichever it reached first. const same = kept.findIndex((t, ti) => !claimed.has(ti) && Math.abs(t.foot - iv.P) < 1e-9); if (same >= 0) { claimed.add(same); survives = true; } else { const rival = kept.find((t) => Math.abs(t.foot - iv.P) < 0.6 * Math.max(t.wHalf, wHalf)); why = rival ? Math.abs(rival.foot - iv.P) < 1e-9 ? "same lock as an earlier group (whole and split both offered)" : `overlaps a lock already taken (support ${rival.sup} vs ${sol.sup})` : "dropped in overlap resolution"; } } return { gi, x0: xs[lo], x1: xs[hi], n: hi - lo + 1, iv, sol, why, survives }; }); return { y, w, h, edges, groups, kept, thr }; }4b:T1427,rowWalkFrame = { // Where the row is. The strip down the right says what the detector gets out of // each row, so the slider can be aimed rather than hunted with. It carries the // circles' colours because locating a mark is not decoding one: a strip that goes // green on a hit reads as success on rows that returned no id at all. const b = hexFrameBank[rowWalkCfg.frame]; const { y, w, h, kept } = rowWalkRow; const rows = rowWalkScan.rows; const MUT = "var(--theme-foreground-muted,#888)"; const { STRIP, boxW } = rowWalkBox; let s = ``; // The recorded labels, not detections. They were faint white, which reads as one more // overlay rather than as a different KIND of thing -- so they get their own hue and a // dashed stroke, and green and amber stay reserved for what this row measured. // // A rim on a tilted sheet images as an ellipse, and a circle of the mean radius sits // visibly off it. The labels are their own homography: fit one from the recorded // centres to the sheet's millimetres, then push the mm-space rim through it, which // draws the true imaged conic including its rotation. Nothing here consults the // detector -- ground truth stays ground truth. const truthFit = (() => { const ps = b.truth.filter((t) => hexTarget.byId.has(t.id)); if (ps.length < 4) return null; const f = fitHomography(ps.map((t) => { const m = hexTarget.byId.get(t.id); return { sx: m.xMm, sy: m.yMm, dx: t.x, dy: t.y }; })); return f && f.rmsResidual < 8 ? f : null; // a bad fit is worse than a circle })(); const RIM = `fill="none" stroke="#e05ad0" stroke-opacity="0.8" stroke-width="2" stroke-dasharray="6 4"`; for (const t of b.truth) { const m = truthFit && hexTarget.byId.get(t.id); if (!m) { s += ``; continue; } const R = hexTarget.radiusMm; const pts = []; for (let i = 0; i < 64; i++) { const a = (i / 64) * 2 * Math.PI; const [px, py] = truthFit.map(m.xMm + R * Math.cos(a), m.yMm + R * Math.sin(a)); pts.push(`${px.toFixed(1)},${py.toFixed(1)}`); } s += ``; } s += ``; for (const k of kept) s += ``; for (const r of rows) { const idd = r.hits.some((hit) => hit.id != null); const on = r.hits.length > 0; s += ``; } s += ``; const el = htl.html`

`; el.innerHTML = ``; // Click or drag anywhere on the frame to put the scan row there. Drives the // slider rather than shadowing it, so the two can never disagree. Write to // the Inputs.range FORM, not its -- the form's setter is what holds // the value the rest is re-synced from it. const svg = el.firstChild; const rowForm = viewof rowWalkCfg.querySelectorAll("input[type=range]")[0]?.closest("form"); const aim = (ev) => { const ctm = svg.getScreenCTM(); if (!ctm || !rowForm) return; const pt = svg.createSVGPoint(); pt.x = ev.clientX; pt.y = ev.clientY; const frac = pt.matrixTransform(ctm.inverse()).y / (h - 1); rowForm.value = +Math.min(1, Math.max(0, frac)).toFixed(3); rowForm.dispatchEvent(new Event("input", { bubbles: true })); }; svg.addEventListener("pointerdown", (ev) => { svg.setPointerCapture(ev.pointerId); aim(ev); }); svg.addEventListener("pointermove", (ev) => { if (svg.hasPointerCapture(ev.pointerId)) aim(ev); }); svg.addEventListener("pointerup", (ev) => svg.releasePointerCapture(ev.pointerId)); const dec = kept.filter((k) => k.id != null).length; const rowsDecoded = rows.filter((r) => r.hits.some((hit) => hit.id != null)).length; return htl.html`

${el}

${b.name} · ${w}×${h} · row y = ${y} · ${rowWalkScan.locked} of ${rowWalkScan.total} scanned rows lock at least one barcode, ${rowsDecoded} of them decode an id · this row locks ${kept.length}${dec ? `, ${dec} of them with an id` : ", none with an id"}. Click or drag on the frame to move the scan row. Green carries an id, amber is located but undecoded — for the circles and for the strip alike. Magenta dashed rims are the frame's recorded labels, drawn as the ellipse the sheet's own homography puts them on: ground truth, not something the detector produced.

`; }4c:Tb33,rowWalkEdges = { // Stage A. The row is one line of grey; the detector never sees more than // this. First differences, peaks past the threshold, each refined by a // parabola through the peak — which is the whole of edges1Dsub. const b = hexFrameBank[rowWalkCfg.frame]; const { y, w, edges, thr } = rowWalkRow; const sig = b.frame.gray.subarray(y * w, (y + 1) * w); const MUT = "var(--theme-foreground-muted,#888)"; const RISE = "#5ac8fa", FALL = "#ffb454"; const TOP = 10, H1 = 58, GAP = 18, H2 = 64; const yI = (v) => TOP + H1 - (v / 255) * H1; let mx = thr * 1.5; const diff = new Float32Array(w); for (let i = 1; i < w; i++) { diff[i] = sig[i] - sig[i - 1]; mx = Math.max(mx, Math.abs(diff[i])); } const base = TOP + H1 + GAP + H2 / 2; const yD = (v) => base - (v / mx) * (H2 / 2); const pts = (get) => { const a = []; for (let i = 0; i < w; i++) a.push(i + "," + get(i).toFixed(2)); return a.join(" "); }; let s = ``; s += ``; for (const t of [thr, -thr]) s += ``; s += ``; for (const e of edges) { const c = e.s > 0 ? RISE : FALL; s += ``; } const lab = (x, ly, t) => `${t}`; s += lab(4, TOP + 10, "intensity along the row (0-255)"); s += lab(4, TOP + H1 + GAP + 10, `first difference · dashed = ±${thr} threshold`); const el = htl.html`

`; // boxW, not w: the frame above reserves 30px on the right for its strip, and an edge // tick has to land under the pixel it came from. el.innerHTML = ``; return htl.html`

${el}

${edges.length} edges out of ${w} pixels. Blue rises, amber falls — the sign is not decoration, it is what carries the bit at a mid tooth. Sub-pixel positions are worth the trouble: integer ones cost about 0.03 of cross ratio at small barcode scales, which is past what the gate downstream tolerates.

`; }4d:T12f5,pruningTable = { // Every geometric gate between "edges on a row" and "a mark locked", with its // value and what it costs ON THE ROW THE FIGURES ABOVE ARE SHOWING. Move the // frame or row slider and these numbers move with it. // // Nothing here restates a constant by hand. The values are recomputed from // manLayout exactly as manRowGroups computes them, and the counts come from // re-running the REAL manRowGroups with one gate relaxed and diffing, so a // gate that changes in the code changes here too. That is the whole point -- // a table of hand-copied thresholds is wrong the first time anyone tunes one. const L = manLayout; const { edges, groups, kept } = rowWalkRow; const xs = new Float64Array(edges.length); edges.forEach((e, i) => { xs[i] = e.x; }); const base = manRowGroups(xs, {}).length; const withOpt = (o) => manRowGroups(xs, o).length; const MUT = "var(--theme-foreground-muted,#888)"; const FG = "var(--theme-foreground,#ccc)"; const GRN = "#2fe08a", AMB = "#f5a524"; // A relaxed gate can add groups (it was refusing them) or remove them (it was // forcing a split). The sign is the interesting part, so it is shown, not // hidden behind an absolute "removed N". const seg = [ ["minEdges", 6, withOpt({ minEdges: 0 }), "an involution needs three pairs, so five edges cannot lock whatever they are"], ["minSpan", "14px", withOpt({ minSpan: 0 }), "a barcode narrower than this has its rings inside one pixel of each other"], ["gapFrac", 0.2, withOpt({ gapFrac: 1 }), `the widest gap INSIDE one barcode is the dark disc, 2·${L.teeth[0]} of a 2·${L.R} span — at most 0.21 of it, so a wider gap separates barcodes rather than rings`], ["maxEdges", 2 * (L.nT + 1) + 6, withOpt({ maxEdges: Infinity }), `one barcode presents at most 2·(nT+1) = ${2 * (L.nT + 1)} edges; more than that plus slack is more than one barcode, so split`], ["groupCap", 2 * (L.nT + 1) + 3, withOpt({ groupCap: Infinity }), "the same bound as a refusal to OFFER: an over-cap run cannot be one barcode, and fitting it is the expensive case"] ]; const why = (m) => groups.filter((g) => g.why && m.test(g.why)).length; const perGroup = [ ["opposite signs, P inside both pairs, Q outside the span ±2%, tolPx 1.1, ≥6 inliers", why(/no involution/), "no involution fits"], [`tooth index within [0, ${L.nT}], positive slope, ≥3 lattice inliers and within 2 of the pairs offered`, why(/no lattice/), "no lattice assignment"], ["lattice support ≥ 5", why(/lattice support/), "too little support"], ["one lock per foot: |Δfoot| < 0.6 · max(wHalf)", why(/overlap|same lock|dropped in overlap/), "duplicate or rival"] ]; const th = (s, w) => htl.html`${s}`; const td = (s, o = {}) => htl.html`${s}`; const delta = (n) => { const d = n - base; if (d === 0) return htl.html`no change`; return htl.html`${d > 0 ? "+" : ""}${d}`; }; return htl.html`

On the row above: ${edges.length} edges → ${base} candidate groups → ${kept.length} locked.

${th("segmentation gate", "9em")}${th("value", "6em")}${th("groups if relaxed", "9em")}${th("why the geometry says so")} ${seg.map(([name, val, relaxed, reason]) => htl.html` ${td(name, { mono: true })}${td(val, { mono: true })}${td(delta(relaxed))}${td(reason, { c: MUT })}`)}

${th("per-group gate", "18em")}${th("killed here", "6em")}${th("reported as")} ${perGroup.map(([name, n, label]) => htl.html` ${td(name, { c: n ? FG : MUT })}${td(n || "—", { mono: true, c: n ? AMB : MUT })}${td(label, { c: MUT })}`)}

Relaxing a gate can ADD groups it was refusing or REMOVE ones it was forcing a split into, which is why the column is signed. Values are recomputed from the layout, not copied. The stages themselves are drawn in ${ref("scanline")}.

`; }4e:Te6f,rowWalkGroups = { // Stage B. findInvolution can only lock one mark per call, so the row is cut // first. Groups overlap on purpose: the segmenter cuts below the isolated // bound and offers the unsplit run alongside the halves, letting lattice // support settle it. That is why two brackets here can cover the same edges. const { edges, groups, w } = rowWalkRow; const MUT = "var(--theme-foreground-muted,#888)"; const GRN = "#2fe08a", AMB = "#f5a524", DIM = "#8a8a8a"; // Lane pitch was 26 against 11px type, which left 4px of clear space between a // label's descenders and the bracket under it -- reported as bunched on 2026-08-10. // 36 gives 14. LEAD is the gap from the edge ticks down to the first lane. const LANE = 36, TICK = 16, LEAD = 16, FONT = 11; const { boxW } = rowWalkBox; // Lanes are packed against the LABEL, not the bracket. A label is several times wider than the // span it describes, so packing by span alone put two of them on the same line overlapping. const CH = FONT * 0.6; // monospace advance for (const g of groups) { g.txt = g.why ? `${g.n} edges · dropped: ${g.why}` : g.sol.id != null ? `${g.n} edges · id ${g.sol.id} · support ${g.sol.sup} · d = ${g.sol.dHat.toFixed(1)}` : `${g.n} edges · located, no id · support ${g.sol.sup} · d = ${g.sol.dHat.toFixed(1)}`; const half = (g.txt.length * CH) / 2; g.cx = Math.min(w - half, Math.max(half, (g.x0 + g.x1) / 2)); g.lx0 = Math.min(g.x0, g.cx - half); g.lx1 = Math.max(g.x1, g.cx + half); } const lanes = []; for (const g of groups) { let li = lanes.findIndex((L) => L.every((o) => g.lx0 > o.lx1 + 8 || g.lx1 < o.lx0 - 8)); if (li < 0) { lanes.push([]); li = lanes.length - 1; } lanes[li].push(g); g.lane = li; } let s = ""; for (const e of edges) s += ``; for (const g of groups) { const y = TICK + LEAD + g.lane * LANE; const col = g.sol && g.sol.id != null ? GRN : g.survives ? AMB : DIM; const dash = g.survives ? "none" : "4 3"; s += ``; s += `${g.txt}`; } const H = TICK + LEAD + lanes.length * LANE + 6; const el = htl.html`

`; el.innerHTML = ``; const locked = groups.filter((g) => g.survives).length; // Box, viewBox and cap all come from rowWalkBox, which the frame and the edge ticks // above also use -- see that cell for why they have to be the same. return htl.html`

${el}

${groups.length} candidate groups, ${locked} of them lock. The split rule is the widest gap: inside one barcode the widest gap is the dark disc, at most 0.21 of the barcode's own span, so anything wider separates barcodes rather than rings. The threshold sits below that bound on purpose, which sometimes cuts a real barcode in half — so the unsplit run is offered as well, and brackets overlap. A wrong split loses a barcode; a wrong merge just fails to lock and is discarded.

`; }4f:T1436,rowWalkLock = { // Stages C-E for each group that survived: the involution's mirror pairs and // its fixed point P, then those pairs' u values against the tooth lattice, // then the payload. r is recovered from the fit itself -- u = A r² + B with // B = -A d², so r̂ = sqrt(u/A + d²) -- and the point of the middle chart is // whether those r̂ land on teeth or between them. const { groups, y } = rowWalkRow; const L = manLayout; const MUT = "var(--theme-foreground-muted,#888)"; const FG = "var(--theme-foreground,#ccc)"; const RISE = "#5ac8fa", FALL = "#ffb454", GRN = "#2fe08a", BLU = "#5af"; const locks = groups.filter((g) => g.survives); if (!locks.length) return htl.html`

Nothing locks on row ${y}. Move the scan row to a green tick in the strip beside the frame.

`; const panel = (g) => { const iv = g.iv, sol = g.sol, d = sol.dHat, A = sol.A, B = -A * d * d; const pairs = iv.up.map((p) => { const rHat = Math.sqrt(Math.max(0, p.u / A + d * d)); let k = 0; for (let i = 1; i < L.teeth.length; i++) if (Math.abs(L.teeth[i] - rHat) < Math.abs(L.teeth[k] - rHat)) k = i; return { ...p, rHat, k, err: (rHat - L.teeth[k]) / L.half }; }); const worst = Math.max(...pairs.map((p) => Math.abs(p.err))); const W = 690, H = 152; const pad = (g.x1 - g.x0) * 0.06 + 2; const lo = g.x0 - pad, hi = g.x1 + pad; const sx = (x) => 10 + ((x - lo) / (hi - lo)) * 310; const BASE = 118; let s = ``; for (let i = 0; i < iv.xs.length; i++) s += ``; pairs.forEach((p, i) => { const a = sx(iv.xs[p.e]), b2 = sx(iv.xs[p.f]); const h = 10 + (i / Math.max(1, pairs.length - 1)) * 78; s += ``; }); if (iv.P > lo && iv.P < hi) s += ` P`; s += ` ${pairs.length} mirror pairs · ${iv.xs.length} edges · ${isFinite(iv.Q) ? `Q at ${iv.Q.toFixed(0)}` : "Q at infinity"}`; const X0 = 390, X1 = 676, Y0 = 118, Y1 = 26; const xmax = L.R * L.R * 1.06; const ymax = Math.max(...pairs.map((p) => p.u)) * 1.12; const px = (v) => X0 + (v / xmax) * (X1 - X0); const py = (v) => Y0 - (v / ymax) * (Y0 - Y1); s += ``; s += ``; for (const t2 of L.teeth2) s += ``; s += ``; for (const p of pairs) s += ``; s += ` u against the tooth lattice · ticks are the ${L.teeth2.length} teeth · worst miss ${worst.toFixed(2)} of a half-cell`; const el = htl.html`

`; el.innerHTML = ``; const bit = (v) => htl.html`${v}`; return htl.html`

${el}

${sol.id != null ? htl.html`id ${sol.id} ${sol.bits.map(bit)} ·` : htl.html`no id emitted ·`} support ${sol.sup} · d = ${d.toFixed(2)} · ${sol.nDirect} of ${L.nBits} bits read directly, ${sol.viol} violation${sol.viol === 1 ? "" : "s"}, ${sol.checks} checks · A = ${A.toExponential(3)}, B = ${B.toExponential(3)}

`; }; return htl.html`

${locks.map(panel)}

`; }50:T62f,edges1Dsub = function edges1Dsub(sig, thr = 6) { // Part II's edges1D with parabolic sub-pixel refinement of each gradient peak. // Integer edge positions cost ~0.03 of cross ratio at 2px-per-template-unit // mark scales — past the CR gate's tolerance — so the quarter-pixel accuracy // here is what lets small on-screen marks through detection at all. // // d is a BACKWARD difference, so d[i] is the gradient at i - 0.5 and the // parabola through |d[i-1..i+1]| has its vertex there too. Reporting the peak // at i put every edge half a pixel late along the scan. Because the 12 scan // directions of §4.7 span 180° and not 360°, that bias does not cancel: it // lands as (0, 4b/π) ≈ 0.64px on an intersected centre. The correction is a // translation of a whole row, so involutions, cross ratios and decoded bits // are untouched — the bank reads 85/112 either way — only positions move. const n = sig.length; const d = new Float32Array(n); for (let i = 1; i < n; i++) d[i] = sig[i] - sig[i - 1]; const idx = []; for (let i = 2; i < n - 2; i++) { const v = d[i]; if (Math.abs(v) < thr) continue; if ( (v > 0 && d[i] >= d[i - 1] && d[i] >= d[i + 1]) || (v < 0 && d[i] <= d[i - 1] && d[i] <= d[i + 1]) ) { const y1 = Math.abs(d[i - 1]), y2 = Math.abs(d[i]), y3 = Math.abs(d[i + 1]); const den = y1 - 2 * y2 + y3; const off = Math.abs(den) > 1e-6 ? (0.5 * (y1 - y3)) / den : 0; idx.push({ x: i - 0.5 + Math.max(-0.5, Math.min(0.5, off)), s: Math.sign(v) }); } } return idx; }51:T1061,findInvolution = function findInvolution(edges, opts = {}) { // Stage 1+2 of the redesign cascade: mirror pairing + involution, design- // independent (any symmetric ring pattern induces one). // // Hypotheses are GEOMETRY-BOUNDED, not blind RANSAC: mirror pairs cannot // cross, so candidates come only from the ends inward (outer pair from the // outermost 3 edges each side, second pair from the next 4 inward), and a // pair must have opposite gradient signs. Each 2-pair involution is gated // -- real fixed points, foot P inside both pairs, vanishing point Q outside // the outer pair -- before verification against every edge. const involutionFrom = (x1, x1p, x2, x2p) => { const r1 = [x1 * x1p, x1 + x1p, 1]; const r2 = [x2 * x2p, x2 + x2p, 1]; return [ r1[1] * r2[2] - r1[2] * r2[1], r1[2] * r2[0] - r1[0] * r2[2], r1[0] * r2[1] - r1[1] * r2[0] ]; }; const fixedPoints = (co, span) => { const al = co[0], be = co[1], ga = co[2]; if (Math.abs(al) * span < 1e-4 * Math.abs(be)) return { P: -ga / (2 * be), Q: Infinity }; const disc = be * be - al * ga; if (disc <= 0) return null; const sq = Math.sqrt(disc); return { P: (-be + sq) / al, Q: (-be - sq) / al }; }; const n = edges.length; if (n < 6) return null; const xs = edges.map((e) => (typeof e === "number" ? e : e.x)); const ss = edges.map((e) => (typeof e === "number" ? 1 : e.s)); const span = xs[n - 1] - xs[0]; const tolPx = opts.tolPx ?? 1.1; const minInliers = opts.minInliers ?? 6; let best = null; const consider = (i, j, a, b) => { if (ss[i] === ss[j] || ss[a] === ss[b]) return; const inv = involutionFrom(xs[i], xs[j], xs[a], xs[b]); const fp = fixedPoints(inv, span); if (!fp) return; let P = fp.P, Q = fp.Q; const mid = (xs[i] + xs[j]) / 2; if (isFinite(Q) && Math.abs(P - mid) > Math.abs(Q - mid)) { const t = P; P = Q; Q = t; } if (!(P > xs[i] && P < xs[j] && P > xs[a] && P < xs[b])) return; if (isFinite(Q) && Q > xs[i] - 0.02 * span && Q < xs[j] + 0.02 * span) return; const affine = !isFinite(Q); const img = affine ? (x) => 2 * P - x : (x) => -(inv[1] * x + inv[2]) / (inv[0] * x + inv[1]); let inl = 0; const pairs = []; for (let e = 0; e < n; e++) { if (xs[e] >= P) break; const y = img(xs[e]); if (!isFinite(y)) continue; // Nearest opposite-sign edge right of P. Counts DOWN from n-1 and takes // strictly-smaller distances only, so among equal distances the higher // index wins -- anything replacing this has to match that or the // detector answers differently. // // A binary search over sign-partitioned index lists was written, held to // all 42984 recorded calls bit-for-bit, and measured: 427ms against // 424ms. No gain. A row carries 13 edges at the median and 33 at the // most, and a linear walk of 13 contiguous doubles with a predictable // branch beats two binary searches with unpredictable ones. Asymptotics // need an n this problem does not have. let bi = -1, bd = Infinity; for (let f = n - 1; f >= 0 && xs[f] > P; f--) { const dd = Math.abs(xs[f] - y); if (dd < bd && ss[f] === -ss[e]) { bd = dd; bi = f; } } if (bi >= 0 && bd <= tolPx) { inl += 2; pairs.push([e, bi]); } } if (inl >= minInliers && (!best || inl > best.inl)) best = { P, Q, affine, inl, pairs }; }; for (let i = 0; i < Math.min(3, n); i++) for (let j = n - 1; j >= Math.max(n - 3, i + 3); j--) { if (ss[i] === ss[j]) continue; for (let a = i + 1; a <= Math.min(i + 4, j - 2); a++) for (let b = j - 1; b >= Math.max(j - 4, a + 1); b--) consider(i, j, a, b); } if (!best) return null; const P = best.P, Q = best.Q; const tOf = best.affine ? (x) => x - P : (x) => (x - P) / (x - Q); // u per mirror pair via the geometric mean: t_L = -c k, t_R = +c k const up = best.pairs .map(([e, f]) => ({ u: -tOf(xs[e]) * tOf(xs[f]), e, f, sR: ss[f] })) .filter((p) => p.u > 0) .sort((a, b) => a.u - b.u); return up.length >= 3 ? { P, Q, up, inl: best.inl, xs, ss } : null; }52:T1399,solveMan = function solveMan(iv, L = manLayout, opts = {}) { // Stage 3+4: tooth correspondence + payload for the Manchester lattice. // // (outer, inner) tooth anchors are enumerated, but each candidate (A,B) is // then LEAST-SQUARES REFIT over all mirror pairs with nearest-tooth // reassignment -- anchoring on the two extremal pairs alone runs away when // blur merges rim teeth. Scoring: lattice inliers minus a penalty for // guaranteed teeth (mids, framing) the assignment says should be visible // but aren't; sign gates on the payload-independent framing teeth. // // Payload: mid-tooth gradient sign = bit. Boundary teeth repair erasures // (present iff neighbours equal) -- but repair is circular with the check // that would catch a bad repair, so an id is only EMITTED with nBits-1 // direct reads, zero violations, and >=3 checks. That gate measured 0 wrong // ids and 0/2000 clutter false positives. const T = L.teeth, T2 = L.teeth2, nT = L.nT, nBits = L.nBits, half = L.half; const up = iv.up; const uIn = up[0].u, uOut = up[up.length - 1].u; const nPairs = up.length; let asg = null; for (let o = nT; o >= Math.max(4, nT - 10); o--) for (let ii = 0; ii < o; ii++) { if (o - ii + 1 < nPairs - 2 || o - ii > nPairs + 7) continue; let A = (uOut - uIn) / (T2[o] - T2[ii]); if (!(A > 0)) continue; let B = uIn - A * T2[ii]; let fit = null; for (let round = 0; round < 2; round++) { const d2 = -B / A; if (d2 < -1.5) { fit = null; break; } const dHat = Math.sqrt(Math.max(0, d2)); const hits = []; let sx = 0, sy = 0, sxx = 0, sxy = 0, m = 0; for (const p of up) { const r = Math.sqrt(Math.max(0, p.u / A + d2)); const t = Math.round((r - 6) / half); if (t < 0 || t > nT) continue; const err = Math.abs(r - T[t]); if (err < 0.45) { hits.push([p, t, err]); sx += T2[t]; sy += p.u; sxx += T2[t] * T2[t]; sxy += T2[t] * p.u; m++; } } if (m < 3) { fit = null; break; } const den = m * sxx - sx * sx; if (Math.abs(den) > 1e-9) { const A2 = (m * sxy - sx * sy) / den; if (A2 > 0) { A = A2; B = (sy - A * sx) / m; } } fit = { A, B, dHat, hits }; } if (!fit) continue; let bad = false; const claimed = new Set(); let resid = 0; for (const [p, t, err] of fit.hits) { if ((t === 0 || t === nT) && p.sR <= 0) { bad = true; break; } claimed.add(t); resid += err; } if (bad) continue; const rHi = Math.sqrt(uOut / fit.A + Math.max(0, -fit.B / fit.A)) + 0.7; let missing = 0; for (const t of L.guaranteed) if (T[t] > fit.dHat + 0.8 && T[t] < rHi && !claimed.has(t)) missing++; const score = fit.hits.length - 0.7 * missing; if (!asg || score > asg.score || (score === asg.score && resid < asg.resid)) asg = { A: fit.A, B: fit.B, dHat: fit.dHat, hits: fit.hits, score, resid, inliers: fit.hits.length }; } if (!asg || asg.inliers < 3 || asg.inliers < up.length - 2) return { ok: false, why: "no-lattice" }; const byTooth = new Map(); for (const [p, t, err] of asg.hits) { const prev = byTooth.get(t); if (!prev || err < prev.err) byTooth.set(t, { u: p.u, e: p.e, f: p.f, sR: p.sR, err }); } const bits = new Array(nBits).fill(null); for (let j = 0; j < nBits; j++) { const p = byTooth.get(2 + 2 * j); if (p) bits[j] = p.sR > 0 ? 1 : 0; } const nDirect = bits.filter((b) => b != null).length; const visible = (t) => T[t] > asg.dHat + 0.6; for (let pass = 0; pass < nBits; pass++) { let fixed = 0; for (let j = 0; j < nBits; j++) { if (bits[j] != null) continue; if (j > 0 && bits[j - 1] != null && visible(3 + 2 * (j - 1))) { bits[j] = byTooth.has(3 + 2 * (j - 1)) ? bits[j - 1] : 1 - bits[j - 1]; fixed++; } else if (j < nBits - 1 && bits[j + 1] != null && visible(3 + 2 * j)) { bits[j] = byTooth.has(3 + 2 * j) ? bits[j + 1] : 1 - bits[j + 1]; fixed++; } } if (!fixed) break; } let viol = 0, checks = 0; for (let j = 0; j + 1 < nBits; j++) { const t = 3 + 2 * j; if (bits[j] == null || bits[j + 1] == null || !visible(t)) continue; checks++; if (byTooth.has(t) !== (bits[j] === bits[j + 1])) viol++; } if (bits[0] != null && visible(1)) { checks++; if (byTooth.has(1) !== (bits[0] === 1)) viol++; } if (bits[nBits - 1] != null && visible(nT - 1)) { checks++; if (byTooth.has(nT - 1) !== (bits[nBits - 1] === 1)) viol++; } const nVis = bits.filter((b) => b != null).length; const minDirect = opts.minDirect ?? nBits - 1; const emit = nVis === nBits && viol === 0 && nDirect >= minDirect && checks >= 3; return { ok: true, dHat: asg.dHat, A: asg.A, bits, nVis, nDirect, viol, checks, sup: asg.inliers, id: emit ? bits.reduce((a, b) => 2 * a + b, 0) : null }; }53:T1b6d,manRowGroups = function manRowGroups(xs, opts = {}) { // Split one row's edge positions into candidate per-mark groups. // // findInvolution enumerates its outer pair from the outermost few edges of // whatever it is given, so it can only ever lock ONE mark per call: with two // marks in a row the outermost pair straddles both and no involution fits. // A live frame has several marks, so the row must be segmented first. // // The widest gap INSIDE a mark is the dark disc, crossed only near the // equator: 2*6 units of a 2*R span, so at most 0.21 of the mark's own span // (largest at d=0, and the disc is not crossed at all past d=6). A gap // wider than that separates marks, not rings. The edge-count cap is the // same argument from the other side: a man mark can present at most // 2*(nT+1) edges, so a group holding more than that plus slack is holding // more than one thing. // // gapFrac WAS 0.3, chosen as that 0.21 bound plus slack. That derivation is // about one mark IN ISOLATION, and it is the wrong half of the problem on a // dense target: two marks whose gap is narrower than gapFrac of the combined // span are never separated, and then NEITHER locks, because the outer pair // straddles both. The hex calibration sheet is exactly that regime. // // 0.2 sits BELOW the 0.21 intra-mark bound, so it WILL sometimes cut a mark // at its equator. offerWhole is what makes that safe: it offers the unsplit // run ALONGSIDE the halves, so a split that cuts a real mark does not delete // it. A split is a guess at how many marks are present; offering both lets // lattice support decide, which detectRowMan already does and which already // happened for count-forced splits. The asymmetry is real -- a wrong split // LOSES a mark, a wrong merge merely fails to lock and is discarded. // // THE TWO ARE A PAIR AND MUST SHIP TOGETHER. 0.2 on its own is faster than // the old 0.3 (33ms against 45ms, measured live on one frame) and reads 14 // more marks across the archive, which makes it look like the better buy -- // but on the rendered scene in manSceneTest it drops a mark at stride 4 and // invents a SPURIOUS one at stride 6. That is the equator cut, and no frame // rate is worth a false positive in a positioning system. // // Measured over a 36-case archive of printed-sheet captures, against 252 // marks that should be read: // gapFrac 0.3, offerWhole off (was) 196 read, 0 wrong, median LOO 1.9px // gapFrac 0.2, offerWhole off 210 read, 0 wrong -- but see above // gapFrac 0.2, offerWhole on (now) 216 read, 0 wrong, median LOO 2.0px // // offerWhole also makes duplicate ids possible, since one mark can lock in // both the split and the unsplit group; analyzeFrameMan dedupes by id. // // ---- groupCap: never OFFER a group bigger than one mark can be ---------- // // The 2*(nT+1) bound above was used only to decide to SPLIT, and then // offerWhole pushed the unsplit parent out anyway, at every level of the // recursion. So the groups the layout says cannot be one mark were still // handed to findInvolution -- and they are the expensive ones, because that // fit is O(pair hypotheses * n^2). Over the 70-frame archive the over-cap // parents are 19% of candidate groups and 72% of sum(n^2). // // Refusing to emit them is the single best change measured on this cascade, // and it is NOT only a speed change (70 archived frames, plus 10 captured // after the cap was written and never tuned against): // // read 391/490 -> 412, wrong 6 -> 4, median 27.7ms -> 15.5, p90 47 -> 22.5 // held-out read 58/70 -> 61, worst leave-one-out 0.91 -> 0.26 radii // rendered scenes 24 read / 5 wrong -> 37 / 0 // // The reason accuracy IMPROVES is the interesting half. An over-cap group // spans two or more marks; when it locks at all it lands at a foot between // them carrying a decoded id belonging to neither, and that hit then poisons // the cluster's id vote and the duplicate-id dedup downstream. Those locks // looked like detections and were noise, which is why deleting 2055 of 7092 // locking groups RAISES the number of marks read. // // Slack 3 rather than maxEdges' 6 because 32..35 is a flat plateau on read // and 33 is the cheapest of them; 30 (no slack) starts dropping real marks. // Four cheaper structural tests were measured and all failed -- sign // alternation keeps only 913 of 7092 locking groups, even parity 3722, // mirror-sign consistency 1574 -- because edges1Dsub at thr=12 emits // consecutive same-sign peaks freely and a real mark's group routinely // carries clutter edges the involution simply does not use. const L = opts.layout ?? manLayout; const gapFrac = opts.gapFrac ?? 0.2; const maxEdges = opts.maxEdges ?? 2 * (L.nT + 1) + 6; const groupCap = opts.groupCap ?? 2 * (L.nT + 1) + 3; const minEdges = opts.minEdges ?? 6; const minSpan = opts.minSpan ?? 14; const offerWhole = opts.offerWhole ?? true; const out = []; const emit = (lo, hi) => { if (hi - lo + 1 <= groupCap) out.push([lo, hi]); }; const split = (lo, hi, depth) => { const n = hi - lo + 1; if (n < minEdges) return; const span = xs[hi] - xs[lo]; if (span < minSpan) return; let worst = -1, worstGap = 0; for (let i = lo; i < hi; i++) { const g = xs[i + 1] - xs[i]; if (g > worstGap) { worstGap = g; worst = i; } } const tooWide = worstGap > gapFrac * span; // maxEdges triggers the SPLIT, groupCap is what emit refuses above, and they // were derived independently -- 2*(nT+1)+6 against +3. That left a dead band: // a node of 34..36 edges is not tooMany, so it never splits, and is over cap, // so it is never emitted. It was dropped whole, taking every mark inside it. // Observed on hexcase-5ivq-04 row 429: the 36-edge node at x 503..760 held // BOTH marks and no candidate group was offered for either. If a node cannot // be emitted, keep splitting it. // // Measured over the 16-frame bank, against the frozen per-frame truth: // marks read 88/112 -> 88/112, wrong 0 -> 0, spurious 5 -> 5 // rows that lock at least one mark RISE on 11 of 16 frames (e.g. 90 -> 97) // whole-frame time about 8% higher (16.2 -> 18.5ms on hexcase-5ivq-04) // So this buys redundancy per mark, not new marks, on this bank. It is // kept because a node vanishing whole is a correctness hole, not a tuning // choice: which marks it eats depends on where clutter lands in the row. const tooMany = n > Math.min(maxEdges, groupCap); if ((tooWide || tooMany) && worst >= lo && depth < 8) { split(lo, worst, depth + 1); split(worst + 1, hi, depth + 1); // a mark straddling the cut would be lost, so also offer the whole run if ((tooMany && !tooWide) || offerWhole) emit(lo, hi); return; } emit(lo, hi); }; split(0, xs.length - 1, 0); return out; }54:T580,detectRowMan = function detectRowMan(scanEdges, opts = {}) { // One scan row, any number of man marks: segment, then run the scanline // cascade per group. Overlapping locks are resolved by lattice support, so a group // offered twice (the count-split fallback) cannot yield the mark twice. const L = opts.layout ?? manLayout; const n = scanEdges.length; if (n < 6) return []; const xs = new Float64Array(n), ss = new Int8Array(n); for (let i = 0; i < n; i++) { const e = scanEdges[i]; xs[i] = typeof e === "number" ? e : e.x; ss[i] = typeof e === "number" ? 1 : e.s; } const groups = manRowGroups(xs, opts); const hits = []; for (const [lo, hi] of groups) { const sub = []; for (let i = lo; i <= hi; i++) sub.push({ x: xs[i], s: ss[i] }); const iv = findInvolution(sub, opts); if (!iv) continue; const r = solveMan(iv, L, opts); if (!r.ok || r.sup < 5) continue; const pOut = iv.up[iv.up.length - 1]; const wHalf = (iv.xs[pOut.f] - iv.xs[pOut.e]) / 2; hits.push({ foot: iv.P, d: r.dHat, sup: r.sup, wHalf, id: r.id, x0: iv.xs[0], x1: iv.xs[iv.xs.length - 1] }); } // strongest lattice support wins an overlap hits.sort((a, b) => b.sup - a.sup); const kept = []; for (const h of hits) if (!kept.some((k) => Math.abs(k.foot - h.foot) < 0.6 * Math.max(k.wHalf, h.wHalf))) kept.push(h); return kept; }55:T1056,detectFrameMan = function detectFrameMan(frame, opts = {}) { // Frame-level fusion for man marks: rows at fineStride, id by vote with a // 2x margin over the runner-up, then geometry. // // The pose fit is the section's payoff. Each geometry-locked row measures // its chord offset |d| directly, so a V-fit in d-space gives the vertical // scale and centre: |d| = |y - yc| / S_v, b = S_v R. Fit in d (not d^2) -- // d^2 residuals grow with d, far rows dominate, and MAD trimming gets // masked. Rows whose d disagrees with the d implied by their own rim // half-width (via a global S_h) are translated lattice locks -- two // independent measurements of the same quantity, so disagreement identifies // a bad lock with no tuning. This is what makes acos(a/b) usable: measured // yaw tracked true yaw to a few degrees from 0 to 60. const L = opts.layout ?? manLayout; const stride = opts.stride ?? 6; const thr = opts.edgeThreshold ?? 12; const gray = frame.gray, w = frame.w, h = frame.h; const votes = new Map(); const geo = []; let rowsTried = 0, rowsLocked = 0; for (let y = Math.floor(stride / 2); y < h; y += stride) { rowsTried++; const se = edges1Dsub(gray.subarray(y * w, (y + 1) * w), thr); const iv = findInvolution(se); if (!iv) continue; const r = solveMan(iv, L, opts); if (!r.ok) continue; rowsLocked++; if (r.sup >= 5) { const pOut = iv.up[iv.up.length - 1]; geo.push({ y, d: r.dHat, dHat: r.dHat, sup: r.sup, foot: iv.P, wHalf: (iv.xs[pOut.f] - iv.xs[pOut.e]) / 2 }); } if (r.id != null) votes.set(r.id, (votes.get(r.id) ?? 0) + 1); } let bestId = null, bestN = 0, secondN = 0; for (const [id, n] of votes) { if (n > bestN) { secondN = bestN; bestN = n; bestId = id; } else if (n > secondN) secondN = n; } const id = bestN >= 2 && bestN >= 2 * secondN ? bestId : null; // reject translated locks via the wHalf cross-check let geoV = geo; const shs = geo .filter((g) => g.sup >= 9 && g.dHat < L.R - 3) .map((g) => g.wHalf / Math.sqrt(L.R * L.R - g.dHat * g.dHat)) .sort((x, z) => x - z); if (shs.length >= 3) { const sh = shs[shs.length >> 1]; const filtered = geo.filter((g) => { const q = L.R * L.R - (g.wHalf / sh) * (g.wHalf / sh); return Math.abs(g.dHat - Math.sqrt(Math.max(0, q))) < 3; }); if (filtered.length >= 5) geoV = filtered; } // V-fit in d-space: yc by grid search, slope by LS, MAD trim, refit const vFit = (pts) => { let best = null; const yLo = Math.min(...pts.map((g) => g.y)), yHi = Math.max(...pts.map((g) => g.y)); for (let yc = yLo; yc <= yHi; yc += 1) { let sz2 = 0, szd = 0; for (const g of pts) { const z = Math.abs(g.y - yc); sz2 += z * z; szd += z * g.d; } if (sz2 < 1e-9) continue; const gS = szd / sz2; if (!(gS > 0)) continue; let rss = 0; for (const g of pts) { const e = g.d - Math.abs(g.y - yc) * gS; rss += e * e; } if (!best || rss < best.rss) best = { yc, gS, rss }; } return best; }; let aEst = null, bEst = null, ycEst = null, xcEst = null, tiltDeg = null; if (geoV.length >= 5) { let pts = geoV, fit = vFit(pts); if (fit) { const resid = pts.map((g) => Math.abs(g.d - Math.abs(g.y - fit.yc) * fit.gS)); const mad = resid.slice().sort((x, z) => x - z)[resid.length >> 1] || 0.5; const kept = pts.filter((g, i) => resid[i] <= 2.5 * mad); if (kept.length >= 5) { pts = kept; fit = vFit(pts) ?? fit; } bEst = L.R / fit.gS; ycEst = fit.yc; const feet = pts.map((g) => g.foot).sort((x, z) => x - z); xcEst = feet[feet.length >> 1]; const ws = []; for (const g of pts) { const q = 1 - ((g.y - ycEst) / bEst) ** 2; if (q > 0.15) ws.push(g.wHalf / Math.sqrt(q)); } if (ws.length >= 3) { aEst = ws.sort((x, z) => x - z)[ws.length >> 1]; tiltDeg = (Math.acos(Math.min(1, aEst / bEst)) * 180) / Math.PI; } } } return { id, votes: bestN, rowsTried, rowsLocked, geoRows: geoV.length, xcEst, ycEst, aEst, bEst, tiltDeg }; }56:T1e01,combineDiagram = { // The join rule, run rather than drawn: this is the shipping stage 1 and stage 2 // over the same synthetic scene manSceneTest uses, so if the rule changes the // picture changes with it and nothing here has to be kept in step by hand. const stride = 6; const frame = { gray: manScene.gray, w: manScene.w, h: manScene.h }; const rowResults = scanRowsMan(frame, manScanRows(frame, { stride }), { stride }); const res = clusterManRows(rowResults, { stride, keepRows: true }); const GRN = "#2fe08a", AMB = "#f5a524", DIM = "#8a8a8a", BLU = "#5ac8fa"; const MUT = "var(--theme-foreground-muted,#888)"; const txt = (x, y, str, o = {}) => `${str}`; // The frame's own pixels behind the marks: a dot at a foot means nothing without // the mark it sits on. const cv = htl.html`