swarmflow op• Data kinds: any × scalar × scalar → table
• Call: import fullseye as fs; fs.ledger.swarm_field_from_piv(frames, res: 'float', frame_dt: 'float', center=(0.0, 0.0), window: 'int' = 24, overlap: 'float' = 0.5, min_peak_ratio: 'float' = 1.1, outlier_threshold=3.0) -> 'dict' (to call the implementation directly, import swarmflow; swarmflow.swarm_field_from_piv(frames, res: 'float', frame_dt: 'float', center=(0.0, 0.0), window: 'int' = 24, overlap: 'float' = 0.5, min_peak_ratio: 'float' = 1.1, outlier_threshold=3.0) -> 'dict'; from the registry, opsdrive.get("swarm_field_from_piv"))
Overhead frame sequence → PIV by cross-correlation of neighboring frames (pivops.piv_cross_correlate) → average over all pairs → velocity field in the world.
It does not distinguish individuals one by one (so it works even with overlaps), but fluctuations finer than the window (window px) are smoothed out. Windows whose peak ratio is below min_peak_ratio are missing (NaN). ★Swarms tend to line up like a lattice (pushing evens out the spacing), so correlation peaks also appear at neighbouring lattice positions and the peak ratio is close to 1. Measured (spacing 7.5 px, window 24): with threshold 0, mismatched windows creep in and the rms against individual velocities is 13.7 % of U; with 1.1 it is 1.9 % (85 % of windows measured); with 1.3 the measured windows drop to 18 % —— the default is 1.1. In addition, a per-pair normalised median test (pivops.piv_outlier_mask, threshold outlier_threshold, None to skip) marks outlying windows as missing before averaging. Following pivops' caution, 3 is used, looser than the customary 2, so that steep gradients (shoulders of obstacles) are not called outliers. The pivops components (dy, dx) [px/frame] are converted to u = dx·res/Δt, v = −dy·res/Δt.
Returns:
dict of the velocity field + valid_fraction (fraction of windows measured), n_pairs.
• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).
• Operator provenance and references — the sources of the research/methods this op family came from.
• The canonical algorithm (author, year) and its uses are named in the family usage guide above.
• poc_swarm_obstacle_from_flow — py -3.11 examples/poc_swarm_obstacle_from_flow.py
table as input)course_layout · course_occupancy · course_contains · world_build · world_camera · world_move · lidar_scan · rss_longitudinal_same
swarmflow)sph_kernel · sph_density_pressure · swarm_simulate · swarm_render_overhead · swarm_field_from_tracks · potential_flow_cylinder · velocity_deficit_map · stagnation_from_centerline
*Provenance: swarmflow.py — DRIVE operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.