GPU frontend + faster3 CPU fit: per-platform AprilTag acceleration

[jameshmcvay]

The OpenCL GPU AprilTag detector (#9) combined with Bouke's faster3 CPU + arm64 campaign, so the fit stage uses the best implementation per platform.

Based on master, so the full stack is visible together: the GPU frontend/fit work (#9, authored on james/gpu) and the faster3 integration. For the GPU detector on its own (implementation, correctness contract, fleet/soak validation), see #9 — this PR adds the per-platform fit routing and the bridge between the two.

Per-platform fit

The GPU frontend (#9) is used whenever a GPU is available; the fit is chosen by capability:

	frontend	fit
GPU + fp64 (NUC14/15)	GPU	GPU fp64 fit (#9); leftovers → Bouke's CPU fit
GPU, no fp64 (NUC13)	GPU	Bouke's faster CPU fit (bridged)
no GPU	Bouke's CPU frontend	Bouke's CPU fit

oclClustersToPtList bridges the GPU frontend's clusters into Bouke's packed pt_list (materializing only the leftovers the GPU fit hands back); struct pt / pt_list moved to apriltag_pt.h so the bridge can build them.

ctasks[16] stack overflow — carried by faster3

cluster_concat_task ctasks[16] was a fixed 16-slot stack array, but the task count is ~4 × nthreads — so it overflowed and segfaulted at nthreads ≥ 5 (≤4 is safe, which is why production nthreads=4 never tripped it). faster3 sizes it dynamically. We originally carried an identical malloc fix on the faster2 base; on faster3 it's Bouke's commit, so this branch just inherits it.

---

Benchmarks

All numbers measured fresh on the f0ba6e4 builds, both robots: vide stopped, 2-min cooldown before each scenario. Two loads — a synthetic single 32-tag fixture (nthreads=8, isolates per-frame engine cost) and the vide corpus (84 real frames, nthreads=4, production config). cores = average busy cores (CPU-seconds / wall-seconds); lower is more headroom for the rest of vide. pkg °C = median CPU package temperature (x86_pkg_temp) sampled across the run; the mean tracks it within ~1 °C.

Synthetic — single 32-tag fixture (nthreads=8)

32/32 tags every run.

W2 / NUC13 (Raptor Lake i5-1340P, no fp64)

Config	FPS	core-ms/detect	cores	pkg °C
Master (stock CPU)	12.6	452	5.71	85
GPU branch (#9): GPU frontend + original fit	18.1	239	4.34	89
This branch: GPU frontend + Bouke's CPU fit	17.8	190	3.39	80
faster3 pure CPU	24.8	259	6.41	88

W3 / NUC14 (Core Ultra 5 125H, fp64 GPU fit engaged)

Config	FPS	core-ms/detect	cores	pkg °C
Master (stock CPU)	15.7	326	5.12	101
GPU branch (#9): GPU + fp64 fit	23.9	47	1.13	83
This branch: GPU + fp64 fit + Bouke's tail	23.6	41	0.96	79
faster3 pure CPU	30.1	200	6.02	100

Vide corpus — 84 real frames (nthreads=4)

The whole corpus looped for 30 s per scenario; core-ms/frame and cores are per real frame.

W3 / NUC14 (fp64 GPU fit engaged)

Config	FPS	core-ms/frame	cores	pkg °C
Master (stock CPU)	8.6	382	3.30	102
GPU branch (#9): GPU + fp64 fit	16.9	53	0.90	97
This branch: GPU + fp64 fit + Bouke's tail	17.5	42	0.73	86
faster3 pure CPU	15.7	218	3.43	101

W2 / NUC13 (no fp64 → CPU fit)

Config	FPS	core-ms/frame	cores	pkg °C
Master (stock CPU)	8.2	415	3.41	98
GPU branch (#9): GPU frontend + original fit	11.4	261	2.97	100
This branch: GPU frontend + Bouke's CPU fit	14.3	166	2.36	97
faster3 pure CPU	14.6	242	3.55	96

On the corpus, this branch is the best FPS-per-core on both machines — W3 17.5 FPS at 0.73 cores (−78% CPU vs stock), W2 14.3 FPS at 2.36 cores — and on W3 it beats #9 outright (17.5 vs 16.9 FPS, 0.73 vs 0.90 cores). The single-fixture synthetic is closer between #9 and this branch (within ~1%); the corpus separates them because real frames carry more leftover clusters, where Bouke's faster fit + AVX2 decode pay off. faster3 pure CPU posts the highest raw FPS but saturates the CPU (3.4–6.4 cores).

On W3 the fp64 GPU fit drops the CPU below 1 core, and that offload also runs the package ~15–20 °C cooler than the CPU-bound configs (this branch 79–86 °C vs master / faster3 ~100–102 °C). On W2 (no fp64, fit on the CPU) the temperatures are closer.

Exactness

Bit-exact vs stock master, GPU path vs CPU path, across the full matrix — every case max_coord_diff=0, max_margin_diff=0:

• Both machines (W2 no-fp64; W3 with the fp64 GPU fit engaged) × both loads (vide corpus, 69 images / 1578 detections; the 32-tag fixture) × nthreads 1 and production (4 for the corpus, 8 for the fixture) × all three configs (GPU-accelerated AprilTag detection (OpenCL), bit-exact drop-in #9, this branch, faster3). 24 bit-exact checks per machine.