Skip to content

perf: cluster & quad-fit core rework (1/4) - #1

Closed
bouk wants to merge 10 commits into
masterfrom
perf/cluster-quadfit-core
Closed

perf: cluster & quad-fit core rework (1/4)#1
bouk wants to merge 10 commits into
masterfrom
perf/cluster-quadfit-core

Conversation

@bouk

@bouk bouk commented Jun 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Detector optimization campaign — Part 1/4: cluster & quad-fit core rework

First of four stacked code PRs that together take the detector from
88 ms → 39.8 ms/image (2.21×) on the 133-image vide_images corpus (4 threads,
default params, tagStandard52h13). Output stays byte-equivalent to baseline at every
commit (4583/4583 detections; coords within 1e-4 px, FMA-contraction noise only).

The measurement harness and per-stage notes used to validate the campaign are in a
separate, independent PR: #5 (benchmark harness & optimization notes).

This PR establishes the core data-structure rework that everything else builds on.

What's here

  • Quad fitting (fit quads 34.6 → 25.9 ms): memoized segment fits, per-task
    scratch replacing per-cluster mallocs, ping-pong ptsort that copies only at leaves.
  • Gradient clustering: lazy union-find rep lookup, power-of-two masked hash
    buckets, parallelized merge tree, -fno-math-errno build flag.
  • Packed u64 sort keys (slope<<32 | ~idx) reproducing the legacy take-right-on-tie
    merge order exactly; points gathered once at the end.
  • Run-driven clusters with chunk-pool point storage (no more doubling zarrays).
  • Heads-only union-find + threshold buffers cached across frames.
  • Branchless merge, single-pass k-way heap merge replacing the pairwise tree,
    8-byte struct pt, and SIMD tile min/max + blur in the threshold stage.

Each commit notes its verification (byte-identical or within-1e-4-px over the corpus).

Stacked PR 1 of 4. Base: master. Followed by perf/simd-and-run-tables.

bouk and others added 10 commits June 10, 2026 18:43
@bouk @claude
Speed up quad fitting: memoize segment fits, reuse scratch, cut sort …
f3aa015 
…copies

- quad_segment_maxima: memoize fit_line results over maxima pairs (the
  4-deep candidate loop re-fit identical segments for every outer
  combination), hoist the constant Gaussian kernel into a per-thread
  table, and replace modulo indexing in the error/filter/maxima loops
  with wrap adjustments.
- fit_quad/do_quad_task: per-task scratch buffers replace five
  mallocs + one calloc per cluster.
- ptsort: ping-pong merge sort copies data only at <=5-element leaves
  instead of the whole range at every recursion level. Same splits,
  leaf networks, and merge tie behavior, so the result is bit-identical.

Output verified byte-identical over the 133-image corpus.
fit quads stage: 34.6 -> 25.9 ms/image.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Speed up gradient clustering: lazy rep lookup, masked buckets, parall…
a335d94 
…el merge

- Defer the pixel's union-find representative lookup until a black/white
  boundary neighbor is actually found; most pixels are interior to a
  region and never needed it.
- Size the per-task cluster hash table to the slab (power of two), so
  bucket selection is a mask instead of an integer divide and the table
  stays cache resident instead of 0.2*w*h spread across 10MB of callocs.
- Reuse the bucket index for cluster_hash->hash instead of rehashing.
- Cache the last-hit cluster entry; consecutive boundary points almost
  always extend the same cluster.
- Run the cluster merge tree levels on the worker pool instead of
  serially on the calling thread.
- Destroy clusters inside the quad tasks (parallel, cache-warm) instead
  of a serial 11k-free loop after fit_quads.
- Build with -fno-math-errno so sqrt compiles to bare instructions.

Output verified byte-identical over the 133-image corpus.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Sort cluster points as packed u64 keys
64fc38a 
key64 = monotone(slope) << 32 | ~index. Full-u64 merge comparisons
reproduce the historical merge's take-right-on-tie rule (left-run
elements always carry smaller original indices -> larger complements);
leaf networks compare the slope word only, matching no-swap-on-tie.
Bit-identical ordering, but the sort moves 8-byte keys instead of
12-byte structs and compares without function calls; points are
gathered once at the end.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Run-driven gradient clusters with chunk-pool point storage
0c71bb8 
Drive cluster construction from row runs: component representatives
resolve once per run (cached) instead of per boundary pixel, 127 spans
skip wholesale, and the same (y, x, neighbor) emission order is kept so
output is bit-identical.

Cluster points accumulate in fixed-size chunks bump-allocated from a
per-task pool instead of doubling zarrays (a frame can produce ~3M
points; growth reallocs were copying tens of MB per frame). Clusters
materialize into exact-size zarrays at collection.

Output verified byte-identical over the 133-image corpus.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Heads-only union-find and cached threshold buffers
425fc08 
Only run heads (plus the lazily-initialized last column) ever enter the
union-find: the run-driven cluster pass resolves representatives through
run heads, so the per-pixel parent fill (~25MB of writes per frame) was
pure waste. Unions operate on head ids -- the same union graph on the
same nodes, so roots, sizes, and output are identical. The serial stitch
becomes a run-pair pass; the per-pixel line code is gone.

threshim and the four tile min/max arrays are now cached on the detector
across detect calls instead of being allocated and freed every frame
(every entry is rewritten before use).

Output verified byte-identical over the 133-image corpus.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Batch interior overlap points in gradient clusters
3b9f803 
While a run and the run below keep overlapping, each pixel emits
exactly its (0,1) and (1,1) points into the same cluster entry, so emit
them in a tight loop without per-pixel pointer or gate checks.

Output verified byte-identical over the 133-image corpus.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Branchless sort merge, lean inline path for window fit errors
77fc3ff 
- key_merge selects with conditional moves; merge comparisons are
  data-dependent coin flips, so this avoids ~50% branch mispredicts.
- The per-point window error loop in quad_segment_maxima now uses an
  inlined, branch-free error computation (identical arithmetic) for all
  non-wrapping windows; only windows touching the ends go through the
  general fit_line.
- pt_compare_angle becomes static inline.

Output verified byte-identical over the 133-image corpus.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Replace pairwise cluster merge tree with single-pass k-way heap merge
aff3b78 
Same output: clusters ascend by (hash, id) and split clusters
concatenate their points in task order, exactly as the pairwise tree
produced. Saves a workerpool barrier per level and all intermediate
lists. Detections verified within 1e-4 px of baseline (the build now
uses -march=native, whose FMA contraction shifts coordinates by ~1e-4).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Shrink struct pt to 8 bytes; build sort keys in the slope loop
8315d11 
The slope was only ever used to order points, and the ordering now runs
on packed u64 keys built directly in fit_quad's angle loop, so the
stored float is dead weight. Dropping it cuts a third off all point
traffic (chunk storage, merges, collection copies, sort gathers).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk @claude
Sort keys only (lfps reads through key indices); SIMD tile min/max an…
8be0535 
…d blur

- The sorted point array was only consumed by compute_lfps; read points
  through the sorted key indices instead and skip materializing it.
- AVX2 paths (guarded by __AVX2__, scalar fallback kept) for the
  threshold stage's 4x4 tile min/max and the 3x3 tile blur. Integer
  min/max only, so results are exact.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@bouk
bouk force-pushed the perf/cluster-quadfit-core branch from 5989006 to 8be0535 Compare June 10, 2026 18:44
This was referenced Jun 10, 2026
Closed
Closed
Closed
@bouk

bouk commented Jun 10, 2026

Copy link
Copy Markdown
Member Author

Superseded by #6 — consolidated into a single branch (faster2) with one optimization per commit.

@bouk bouk closed this Jun 10, 2026
@bouk
bouk deleted the perf/cluster-quadfit-core branch June 10, 2026 19:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bouk