fix: live decode starved by runaway QR fallbacks on cluttered crops

Real-capture repro (anyd-capture-1 (6): Suntory bottle, EAN-13 4901777300521):
the locator boxed the barcode perfectly and tracked it for 376 cycles, yet
nothing ever decoded. The crop worker processed crops in order and scan_all
spent 4.5 s NATIVE (10 s+ in wasm) on a 336x672 kanji ingredient panel before
reaching the barcode crop, which decodes in 1.3 ms. Every dispatch starved the
same way, so locks either never appeared or expired between reads.

The hog was the QR fourth-corner refinement sweep: its grid radius grows with
the (falsely estimated, often huge) module size of clutter triples, and it
full-samples + RS-decodes every placement for up to four bogus hypotheses.

Library:
- refine_fourth_corner now walks placements nearest-first from the affine
  prediction (a genuine curved capture decodes within a step or two) under a
  global work budget counted in sampled modules, and caps the sweep radius;
  the busy text crop drops 4486 ms -> 208 ms native (~600 ms wasm) with every
  curved/real-world QR test still passing
- new decode1d wasm export: 1D-only scan for crops the locator already
  classified as linear — 7 ms in wasm on the repro EAN crop

Demo:
- crop worker routes by candidate family (linear -> decode1d, else full
  decode) and runs linear crops first
- results stream per crop instead of per batch, so a decoded barcode shows
  up immediately rather than after the slowest clutter crop
- worker onerror clears the busy flag — a dead worker no longer silently
  disables decoding for the rest of the session
- cropdecode diagnostic example (crop + per-stage timing + raw luma dump)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: MagicalTux

Cargo.toml

@@ -62,6 +62,10 @@ required-features = ["cli"]
 name = "locdebug"
 required-features = ["cli"]
 
+[[example]]
+name = "cropdecode"
+required-features = ["cli"]
+
 [[example]]
 name = "scan1ddebug"
 required-features = ["cli"]

examples/cropdecode.rs

@@ -0,0 +1,76 @@
+// Diagnostic: reproduce the live demo's crop-worker decode on a captured frame.
+// Usage: cropdecode <png> [x0 y0 x1 y1] [--dump out.raw]
+// Box in pixels, padded 16px like the demo; --dump writes the crop as raw luma
+// (w and h printed) for feeding other harnesses, e.g. the wasm build under Node.
+use std::time::Instant;
+
+fn main() {
+    let mut raw_args: Vec<String> = std::env::args().skip(1).collect();
+    let dump = raw_args
+        .iter()
+        .position(|a| a == "--dump")
+        .map(|i| raw_args.remove(i + 1))
+        .inspect(|_| {
+            raw_args.retain(|a| a != "--dump");
+        });
+    let mut args = raw_args.into_iter();
+    let path = args.next().expect("usage: cropdecode <png> [x0 y0 x1 y1]");
+    let rgba = oxideav_png::decode_png_to_rgba(&std::fs::read(&path).unwrap()).unwrap();
+    let (w, h) = (rgba.width as usize, rgba.height as usize);
+    let luma: Vec<u8> = rgba
+        .data
+        .chunks_exact(4)
+        .map(|p| ((p[0] as u32 * 299 + p[1] as u32 * 587 + p[2] as u32 * 114) / 1000) as u8)
+        .collect();
+
+    let boxed: Vec<usize> = args.map(|a| a.parse().unwrap()).collect();
+    let (x0, y0, x1, y1) = if boxed.len() == 4 {
+        (
+            boxed[0].saturating_sub(16),
+            boxed[1].saturating_sub(16),
+            (boxed[2] + 16).min(w),
+            (boxed[3] + 16).min(h),
+        )
+    } else {
+        (0, 0, w, h)
+    };
+    let (cw, ch) = (x1 - x0, y1 - y0);
+    let mut crop = vec![0u8; cw * ch];
+    for y in 0..ch {
+        crop[y * cw..(y + 1) * cw]
+            .copy_from_slice(&luma[(y0 + y) * w + x0..(y0 + y) * w + x1]);
+    }
+    let frame = anyd::GrayFrame::new(&crop, cw, ch).unwrap();
+    if let Some(out) = dump {
+        std::fs::write(&out, &crop).unwrap();
+        println!("dumped {cw}x{ch} raw luma to {out}");
+    }
+
+    let t = Instant::now();
+    let found = anyd::pipeline::scan_all(&frame);
+    println!(
+        "scan_all on {cw}x{ch} crop ({x0},{y0})-({x1},{y1}): {} results in {:.1}ms",
+        found.len(),
+        t.elapsed().as_secs_f64() * 1000.0
+    );
+    for s in &found {
+        println!("  {}: {:?}", s.symbology, s.text());
+    }
+
+    // Break the 1D path down so a miss can be attributed.
+    let t = Instant::now();
+    let ean = anyd::codes::ean::scan(&frame, &anyd::scan1d::ScanOptions::default());
+    println!(
+        "ean::scan (width-ratio edge path): {:?} in {:.1}ms",
+        ean.and_then(|s| s.text()),
+        t.elapsed().as_secs_f64() * 1000.0
+    );
+    let t = Instant::now();
+    let lines = anyd::scan1d::scan_lines(&frame, &anyd::scan1d::ScanOptions::default());
+    println!(
+        "scan1d::scan_lines: {} candidates in {:.1}ms (conf: {:?})",
+        lines.len(),
+        t.elapsed().as_secs_f64() * 1000.0,
+        lines.iter().map(|c| c.confidence).collect::<Vec<_>>()
+    );
+}

src/codes/qr/sample.rs

@@ -157,18 +157,34 @@ pub fn scan(frame: &GrayFrame<'_>) -> Result<Symbol> {
     // parallelogram places wrongly and whose alignment pattern is too degraded to
     // detect: sweep that free corner and let Reed–Solomon accept the geometry that
     // reads. Reached only when every direct hypothesis failed, so clean renders never
-    // pay for it.
+    // pay for it. The shared budget bounds the sweep's worst case: on a genuinely
+    // curved symbol the winning placement sits within a step or two of the affine
+    // prediction (the sweep walks outward from it), while a cluttered no-QR crop —
+    // whose false triples would otherwise sweep huge grids at large estimated module
+    // sizes — exhausts the budget in bounded time (this stage alone cost ~4.5 s on a
+    // busy 336×672 text crop before the cap; the whole scan is now ~100 ms there).
+    let mut budget = REFINE_MODULE_BUDGET;
     for located in &pending {
-        if let Some(sym) = refine_fourth_corner(frame, located, &integral, &decoder) {
+        if let Some(sym) = refine_fourth_corner(frame, located, &integral, &decoder, &mut budget) {
             return Ok(sym);
         }
+        if budget == 0 {
+            break;
+        }
     }
     Err(last)
 }
 
 /// Located hypotheses (dim > 21) retained for the fourth-corner refinement fallback.
 const REFINE_HYPOTHESES: usize = 4;
 
+/// Total work the fourth-corner sweep may spend across *all* retained hypotheses,
+/// counted in sampled grid modules (one candidate placement of a dim×dim symbol costs
+/// `dim²`). A genuine curved capture decodes within the first few placements around the
+/// affine prediction; this cap only bites on cluttered crops whose false triples would
+/// otherwise sweep hundreds of placements each. ≈350k modules ≲ 100 ms native.
+const REFINE_MODULE_BUDGET: usize = 350_000;
+
 /// Per binarization pass, how many failed hypotheses may pay for the expensive non-planar
 /// (thin-plate-spline) dewarp. Candidates are tried best-score first, so a genuine
 /// curved symbol's correct triple is dewarped within this budget, while a cluttered frame
@@ -190,6 +206,7 @@ fn refine_fourth_corner(
     located: &Located,
     integral: &IntegralImage,
     decoder: &QrDecoder,
+    budget: &mut usize,
 ) -> Option<Symbol> {
     let [tl, tr, _, bl] = located.corners;
     let dim = located.dimension;
@@ -215,31 +232,40 @@ fn refine_fourth_corner(
     ];
     let reach = ms * 3.0;
     let step = (ms * 0.4).clamp(0.75, 3.0);
-    let n = (reach / step) as i32;
-    for thr in &thresholds {
-        for gy in -n..=n {
-            for gx in -n..=n {
-                let ax = ex + gx as f32 * step;
-                let ay = ey + gy as f32 * step;
-                let dst = [
-                    (tl.x as f64, tl.y as f64),
-                    (tr.x as f64, tr.y as f64),
-                    (ax as f64, ay as f64),
-                    (bl.x as f64, bl.y as f64),
-                ];
-                let projection = Projection::quad_to_quad(src, dst);
-                let trial = Located {
-                    projection,
-                    dimension: dim,
-                    threshold: located.threshold,
-                    local: located.local,
-                    corners: located.corners,
-                    module_size: located.module_size,
-                };
-                let matrix = trial.sample(frame, thr);
-                if let Ok(sym) = decoder.decode_matrix(&matrix) {
-                    return Some(sym);
-                }
+    let n = ((reach / step) as i32).min(8);
+    // Walk the grid nearest-first: on a genuine curved capture the true placement sits
+    // within a step or two of the affine prediction, so it is found long before the
+    // budget matters. Both thresholds are tried per placement, closest ones first.
+    let mut offsets: Vec<(i32, i32)> = (-n..=n)
+        .flat_map(|gy| (-n..=n).map(move |gx| (gx, gy)))
+        .collect();
+    offsets.sort_by_key(|&(gx, gy)| gx * gx + gy * gy);
+    for (gx, gy) in offsets {
+        let ax = ex + gx as f32 * step;
+        let ay = ey + gy as f32 * step;
+        let dst = [
+            (tl.x as f64, tl.y as f64),
+            (tr.x as f64, tr.y as f64),
+            (ax as f64, ay as f64),
+            (bl.x as f64, bl.y as f64),
+        ];
+        let projection = Projection::quad_to_quad(src, dst);
+        let trial = Located {
+            projection,
+            dimension: dim,
+            threshold: located.threshold,
+            local: located.local,
+            corners: located.corners,
+            module_size: located.module_size,
+        };
+        for thr in &thresholds {
+            *budget = budget.saturating_sub(dim * dim);
+            let matrix = trial.sample(frame, thr);
+            if let Ok(sym) = decoder.decode_matrix(&matrix) {
+                return Some(sym);
+            }
+            if *budget == 0 {
+                return None;
             }
         }
     }

src/wasm.rs

@@ -102,8 +102,32 @@ pub unsafe extern "C" fn decode(w: usize, h: usize, luma_ptr: *const u8) -> u64
 
     // Same shared decode entry point as the CLI (`crate::pipeline::scan_all`), so the
     // demo and the command line always agree on what a frame decodes to.
-    let out = crate::pipeline::scan_all(&frame);
+    export(symbols_json(&crate::pipeline::scan_all(&frame)))
+}
+
+/// Decode only the **1D / linear** symbologies in a `w`×`h` luminance frame; returns
+/// the same JSON shape as `decode`.
+///
+/// This exists for the live pipeline: a crop the locator classified as *linear* should
+/// never pay for the 2D samplers — their finder/geometry fallbacks are the expensive
+/// part of a scan, and on a text-heavy crop they can dominate the whole dispatch while
+/// the 1D read itself takes a millisecond (see [`crate::pipeline::scan_1d`]).
+///
+/// # Safety
+/// `luma_ptr` must point to `w*h` readable bytes.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn decode1d(w: usize, h: usize, luma_ptr: *const u8) -> u64 {
+    let luma = unsafe { input(luma_ptr, w * h) };
+    let frame = match GrayFrame::new(luma, w, h) {
+        Ok(f) => f,
+        Err(_) => return export(b"[]".to_vec()),
+    };
+    export(symbols_json(&crate::pipeline::scan_1d(&frame)))
+}
 
+/// Serialize decoded symbols as the `[{"symbology":..,"text":..}]` JSON both decode
+/// entry points return.
+fn symbols_json(out: &[crate::Symbol]) -> Vec<u8> {
     let mut json = String::from("[");
     for (i, sym) in out.iter().enumerate() {
         if i > 0 {
@@ -116,7 +140,7 @@ pub unsafe extern "C" fn decode(w: usize, h: usize, luma_ptr: *const u8) -> u64
         json.push('}');
     }
     json.push(']');
-    export(json.into_bytes())
+    json.into_bytes()
 }
 
 /// Decode only the **2D** codes (QR, Data Matrix, PDF417) in a `w`×`h` luminance frame,

web/index.html

@@ -438,14 +438,17 @@ <h2>Decode an image</h2>
 const ready = fetch(${JSON.stringify(WASM_URL)}).then(r => WebAssembly.instantiateStreaming(r, {})).then(x => { w = x.instance.exports; });
 function wr(b){ const p = w.alloc(b.length); mem().set(b, p); return p; }
 function take(pk){ const ptr = Number(pk >> 32n), len = Number(pk & 0xffffffffn); const o = mem().slice(ptr, ptr + len); w.dealloc(ptr, len); return o; }
-function decLuma(cw, ch, luma){ const p = wr(luma); const pk = w.decode(cw, ch, p); w.dealloc(p, luma.length); return JSON.parse(new TextDecoder().decode(take(pk)) || '[]'); }
+function decLuma(fn, cw, ch, luma){ const p = wr(luma); const pk = fn(cw, ch, p); w.dealloc(p, luma.length); return JSON.parse(new TextDecoder().decode(take(pk)) || '[]'); }
 self.onmessage = async (e) => {
   await ready;
   const { width, height, rgba, crops } = e.data;
   const data = new Uint8Array(rgba);
   const seen = new Set(), found = [];
   const add = (r, box) => { const k = r.symbology + '|' + r.text; if (!seen.has(k)) { seen.add(k); found.push({ symbology: r.symbology, text: r.text, box }); } };
-  for (const b of crops.slice(0, 6)) {
+  // Linear crops first: they decode in ~a millisecond, so a slow matrix crop later in
+  // the batch can never delay the barcode read that motivated the dispatch.
+  const batch = crops.slice(0, 6).sort((a, b) => (a.family === 'linear' ? 0 : 1) - (b.family === 'linear' ? 0 : 1));
+  for (const b of batch) {
     const x0 = Math.max(0, b.x0 | 0), y0 = Math.max(0, b.y0 | 0), x1 = Math.min(width, Math.ceil(b.x1)), y1 = Math.min(height, Math.ceil(b.y1));
     const cw = x1 - x0, ch = y1 - y0; if (cw < 12 || ch < 12) continue;
     const crop = new Uint8Array(cw * ch);
@@ -454,17 +457,29 @@ <h2>Decode an image</h2>
       const d = y * cw;
       for (let x = 0; x < cw; x++, s += 4) crop[d + x] = (data[s] * 299 + data[s + 1] * 587 + data[s + 2] * 114) / 1000 | 0;
     }
-    for (const r of decLuma(cw, ch, crop)) add(r, b);
+    // Route by the locator's family guess: a linear crop skips the 2D samplers, whose
+    // geometry fallbacks dominate scan time on busy crops (1D reads are ~1ms).
+    const fn = b.family === 'linear' ? w.decode1d : w.decode;
+    found.length = 0;
+    for (const r of decLuma(fn, cw, ch, crop)) add(r, b);
+    // Stream each crop's hits immediately: a decoded barcode must not wait on a slow
+    // matrix crop later in the batch (worst case ~600ms each on dense print).
+    if (found.length) self.postMessage({ results: found.slice() });
   }
-  self.postMessage(found);
+  self.postMessage({ done: true });
 };
 `;
 const decodeWorker = new Worker(URL.createObjectURL(new Blob([workerSrc], { type: 'text/javascript' })));
 decodeWorker.onmessage = (e) => {
-  workerBusy = false;
-  // Merge this batch into the persistent tracks; expiry happens in the render loop.
-  mergeDecoded(e.data, performance.now());
+  const { results, done } = e.data;
+  // Streamed per-crop results merge as they arrive; the dispatch slot only frees once
+  // the whole batch is done.
+  if (results) mergeDecoded(results, performance.now());
+  if (done) workerBusy = false;
 };
+// A worker that dies (failed wasm fetch, OOM) must not wedge the dispatch flag shut —
+// that would silently disable decoding for the rest of the session.
+decodeWorker.onerror = () => { workerBusy = false; };
 
 // A second, parallel worker reads 2D codes (QR / Data Matrix / PDF417) directly off the
 // whole frame — they self-localize, so they do not need the coarse locator, which fixes
@@ -492,6 +507,7 @@ <h2>Decode an image</h2>
 `;
 const worker2d = new Worker(URL.createObjectURL(new Blob([worker2dSrc], { type: 'text/javascript' })));
 worker2d.onmessage = (e) => { worker2dBusy = false; mergeDecoded(e.data, performance.now()); };
+worker2d.onerror = () => { worker2dBusy = false; };
 
 function bbox(corners) {
   const xs = corners.map(p => p[0]), ys = corners.map(p => p[1]);
@@ -725,10 +741,10 @@ <h2>Decode an image</h2>
       const sctx = scratch.getContext('2d', { willReadFrequently: true });
       sctx.drawImage(video, 0, 0, pw, ph);
       const img = sctx.getImageData(0, 0, pw, ph);
-      const crops = liveCands.map(c => { const b = bbox(c.corners); return { x0: b.x0 - 16, y0: b.y0 - 16, x1: b.x1 + 16, y1: b.y1 + 16 }; });
+      const crops = liveCands.map(c => { const b = bbox(c.corners); return { x0: b.x0 - 16, y0: b.y0 - 16, x1: b.x1 + 16, y1: b.y1 + 16, family: c.family }; });
       // No candidate this tick (e.g. motion blur wiped the texture pass) — still try
       // the centre band, where a user aiming at a code will have put it.
-      if (!crops.length) crops.push({ x0: 0, y0: ph * 0.2, x1: pw, y1: ph * 0.8 });
+      if (!crops.length) crops.push({ x0: 0, y0: ph * 0.2, x1: pw, y1: ph * 0.8, family: 'any' });
       decodeWorker.postMessage({ width: pw, height: ph, rgba: img.data.buffer, crops }, [img.data.buffer]);
     }
   }