Compressed resident regional mean diffraction

Compressed resident regional mean diffraction#

MetalRuntimeANSResidentSource.meanDiffractionPattern(rows:columns:shape:) returns a detector-sized Float32 mean and exact UInt64 numerator, directly from compressed resident counts. This complements point diffraction; it does not change the encoded data or the SSB detector-column reduction.

Contract, version 1#

  • Bounds are half-open (row, column) ranges in the native scan.

  • Rectangle membership includes every position within both ranges.

  • Circle bounds are square. Pixel centers on or inside the circle are included with equal weights; the divisor is the actual selected count, not box area.

  • All detector pixels retain their original counts, including those excluded from virtual detectors. A one-position region equals raw point diffraction.

  • Integer sums are exact. Division uses double precision followed by one Float32 rounding. No scan/detector crop, binning or subsampling is implicit.

  • Omitted ranges select the full scan. Invalid regions fail before dispatch.

  • Queries and release must be serialized by the resident owner.

  • Only intersecting chunks are decoded. No dense 4D array is allocated; the reduction output is eight bytes per detector pixel. Full-scan results are not cached by this API.

Verification#

bash scripts/check_metal_region_mean.sh generates small uint8 and uint16 fixtures and tests rectangles, odd/even circles, one-point and boundary regions, repeatability, and full-scan sums across compression chunks. The independent oracle directly reads original array counts and checks every detector pixel.

For real data use bash scripts/check_metal_region_mean.sh original.dm4 copy.qem. The second argument must be a saved .qem copy. Integer sums and final Float32 means must match exactly; timings are reported separately, not used to relax parity. QGPU_TEST_BUILD_DIR can point to an already-built package consumer’s release directory to test its exact linked backend objects and resources.