Module scan 

The scan pass (pass 1): per-frame motion evidence and region learning.

The host decodes frames in order and, for each one, writes its native RGBA into ScanSession::frame_buffer, optionally asks ScanSession::is_duplicate (so it can skip work of its own, such as a WebGPU downscale, on an exact repeat), then calls ScanSession::push with the frame’s index and timing and, when it already has one, the analysis gray. The step returns the scan/<frame> record, the scan-features/<frame> row (not for a duplicate), and the per-frame diagnostics. After the last frame, ScanSession::finish builds the run’s regions and the diagnostics about their shape.

What stays with the host: decoding, the geometry check against the run’s frame size, storing rows (in batches), error classification, progress, pause and stop, and the facts only it knows (the compute backend, how frames were converted, the frame-reference image).

Structs

CompactFeatures

The scan-features/<frame> row: a frame’s features as three flat arrays (analysis-pixel x, y pairs as i16, scores as f32, eight descriptor words each).

FrameMeta

The index and timing of one decoded frame.

ScanRecord

The scan/<frame> row.

ScanRegions

The run’s regions and the diagnostics about their shape.

ScanSession

The scan pass of one run.

ScanStep

What one frame produced.

Enums

FieldLayout

Which branch first laid out a motion field. The page persists the field as an object whose key order follows the branch that built it (a duplicate frame keeps its predecessor’s), and the scenario fingerprint hashes key order, so the host rebuilds the object in this layout.

ScanError

Functions

estimate_motion

Motion from analysis frame a to b, matching the given features (extracted here when absent). A paused pair (mean change below 0.12) skips feature matching altogether.

informative_field

A field carries real evidence only once some model moved more than analysis jitter and is reasonably well matched. Squared length against 1, not a hypot: plain IEEE multiply and add, identical on every engine.