spot_finding: find connected components on the GPU

The spot finder flagged strong pixels on the device and then labelled them on the
host, so every frame sent the packed bitmask back - 2.26 MB on a large detector -
and the host walked all of it to recover a few hundred pixels. Do the labelling on
the device instead: compact the bitmask into a flat-index-sorted list, find each
pixel's backward neighbours by binary search, union them lock-free with path
halving, then label, accumulate and filter in one kernel. Only the spot list comes
back, and only one stream synchronisation per frame.

The gain in the ordinary case is modest - about a quarter off per-image spot
finding - because the host algorithm is genuinely fast on a normal frame. What
justifies it is the frame that is not ordinary. The host labels a sorted sparse
list through a window spanning two detector lines, so its cost is quadratic in how
many strong pixels share a line. A lit band of detector rows - a hot module, a
panel edge - costs 33 ms at two rows and 377 ms at fifteen, all of it under the
pixel cap that was supposed to bound this, and none of it maskable when the cause
is a diffraction ring rather than a defect: a ring runs tangent to a row at its
top and bottom, which is exactly the shape that hurts. The device version is flat
at 0.05 to 0.64 ms across every geometry tried, so an online run no longer stalls
a quarter of a second on an ice ring. Rejecting an over-cap frame is now free too,
since the count is known before any pixel is written.

Also label once and filter three times. The per-image minimum-pixel search runs the
extraction at three settings, but that setting only decides which components are
kept - it does not change the components - so the search itself need not be
repeated. This helps the host path as much as the device one.

The resolution mask moves to the device as a bit mask, uploaded when the limits
change rather than per frame, since the compaction needs it there.

Parity is asserted permanently rather than argued: five cases covering realistic
frames, occupancy from a hundred pixels to past the cap, the pathological
geometries including rings, the resolution mask, and a hundred-repeat determinism
check - requiring the same partition, the same spot order, and identical counts.
The centroid is a float sum and therefore order-dependent, so the device walks each
component from its root in ascending order and fuses its multiply-add the way the
host's does; note that whether the host fuses at all depends on the architecture
flags, so exact centroid equality is asserted where the compiler fuses and a
two-ulp bound otherwise. Making those accumulators integer would remove that
dependence entirely and is worth doing separately.

Regression set: all 37 crystals identical to the last printed digit. Unit suite
passes with the new cases.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

tests/ImageSpotFinderGPUTest.cpp

@@ -18,7 +18,7 @@ static void fill_test_image(ImagePreprocessorBuffer& buffer, size_t width, size_
     buffer[width * 75 + 25] = 12;
 }
 
-// Helper to run GPU and get DiffractionSpot list via StrongPixelSet -> FindSpotsImage
+// Helper to run the GPU finder and collect its spot list
 static std::vector<DiffractionSpot> run_gpu_and_collect_spots(ImagePreprocessorBufferGPU &buffer,
                                                               size_t width, size_t height,
                                                               const SpotFindingSettings &settings,
@@ -26,6 +26,7 @@ static std::vector<DiffractionSpot> run_gpu_and_collect_spots(ImagePreprocessorB
     auto stream = std::make_shared<CudaStream>();
     ImageSpotFinderGPU gpu(static_cast<int32_t>(width), static_cast<int32_t>(height), stream);
     REQUIRE(get_gpu_count() > 0);
+    gpu.SetResolutionMask(res_mask);
 
     REQUIRE(cudaMemcpyAsync(buffer.getGPUBuffer(),
         buffer.getBuffer().data(),
@@ -33,7 +34,7 @@ static std::vector<DiffractionSpot> run_gpu_and_collect_spots(ImagePreprocessorB
         cudaMemcpyHostToDevice,
         *stream) == cudaSuccess);
 
-    return gpu.Run(buffer, settings, res_mask);
+    return gpu.Run(buffer, settings);
 }
 
 // Mirror of ImageSpotFinder_SignalToNoise
@@ -59,8 +60,8 @@ TEST_CASE("ImageSpotFinderGPU_SignalToNoise") {
         .low_resolution_limit = 3.0,
     };
 
-    // GPU produces strong pixels; FindSpotsImage uses mask/resolution implicit in StrongPixelSet.
-    // StrongPixelSet doesn't carry resolution/mask by itself, but FindSpotsImage(settings, vec)
+    // GPU produces strong pixels; the resolution mask is handed to the finder separately and the
+    // connected-component search then runs on the device (SpotExtractorGPU). The spot-level filter
     // matches CPU ImageSpotFinder test behavior for these synthetic inputs.
     auto spots = run_gpu_and_collect_spots(buffer, width, height, settings, res_mask);
 
@@ -91,8 +92,8 @@ TEST_CASE("ImageSpotFinderGPU_CountThreshold") {
         .low_resolution_limit = 3.0,
     };
 
-    // GPU produces strong pixels; FindSpotsImage uses mask/resolution implicit in StrongPixelSet.
-    // StrongPixelSet doesn't carry resolution/mask by itself, but FindSpotsImage(settings, vec)
+    // GPU produces strong pixels; the resolution mask is handed to the finder separately and the
+    // connected-component search then runs on the device (SpotExtractorGPU). The spot-level filter
     // matches CPU ImageSpotFinder test behavior for these synthetic inputs.
     auto spots = run_gpu_and_collect_spots(buffer, width, height, settings, res_mask);
 
@@ -124,8 +125,8 @@ TEST_CASE("ImageSpotFinderGPU_20M") {
         .low_resolution_limit = 3.0,
     };
 
-    // GPU produces strong pixels; FindSpotsImage uses mask/resolution implicit in StrongPixelSet.
-    // StrongPixelSet doesn't carry resolution/mask by itself, but FindSpotsImage(settings, vec)
+    // GPU produces strong pixels; the resolution mask is handed to the finder separately and the
+    // connected-component search then runs on the device (SpotExtractorGPU). The spot-level filter
     // matches CPU ImageSpotFinder test behavior for these synthetic inputs.
     auto spots = run_gpu_and_collect_spots(buffer, width, height, settings, res_mask);
 
@@ -187,7 +188,8 @@ TEST_CASE("ImageSpotFinder_CPU_GPU_Parity", "[ImageSpotFinder]") {
     const std::vector<bool> res_mask(width * height, false);
 
     ImageSpotFinderCPU cpu(static_cast<int32_t>(width), static_cast<int32_t>(height));
-    const auto cpu_spots = cpu.Run(cpu_buffer, settings, res_mask);
+    cpu.SetResolutionMask(res_mask);
+    const auto cpu_spots = cpu.Run(cpu_buffer, settings);
 
     const auto gpu_spots = run_gpu_and_collect_spots(gpu_buffer, width, height, settings, res_mask);