swarmflow op• Data kinds: any × scalar × scalar → table
• Call: import fullseye as fs; fs.ledger.swarm_field_from_tracks(frames, res: 'float', frame_dt: 'float', center=(0.0, 0.0), grid_step=None, h=None, threshold: 'float' = 0.3, max_disp_px=None, min_count: 'int' = 3, outlier_k: 'int' = 12, outlier_threshold: 'float' = 3.0) -> 'dict' (to call the implementation directly, import swarmflow; swarmflow.swarm_field_from_tracks(frames, res: 'float', frame_dt: 'float', center=(0.0, 0.0), grid_step=None, h=None, threshold: 'float' = 0.3, max_disp_px=None, min_count: 'int' = 3, outlier_k: 'int' = 12, outlier_threshold: 'float' = 3.0) -> 'dict'; from the registry, opsdrive.get("swarm_field_from_tracks"))
Overhead frame sequence → detect individuals (connected components of blob2d + brightness centroid) → link to the adjacent frame by mutual nearest neighbors → transfer velocities onto a grid with the SPH kernel.
Linking condition: the nearest neighbour of a point in A is a point in B, and the nearest neighbour of that B point is also the A point (mutual), and the displacement is at most max_disp_px (default = 0.45 times the median nearest-neighbour spacing between detected points. If the motion in one frame exceeds this, points get mismatched = the limit of tracking). The velocities of the pairs from all frames are pooled into one population and averaged (assumption of steady flow). Mismatched pairs have velocities off by an order of magnitude (measured: with 1300 uniformly scattered points, 2 % of the pairs were off by 1-3 m/s and the grid rms error became 16 % of U), so before transferring to the grid they are discarded by a normalised median test (PIV practice: deviation from the median of the velocities of the outlier_k nearest ones / median of the deviations of that neighbourhood > outlier_threshold).
Args:
frames: sequence of (H, W) frames of the same size (2 or more).
res: pixel size [m/px].
frame_dt: frame interval [s].
center: world coordinates of the image centre [m].
grid_step: grid spacing [m] (default = estimated spacing between individuals).
h: kernel h for transferring to the grid [m] (default = grid_step).
threshold: binarisation threshold (fraction between min and max).
max_disp_px: upper limit of motion in one frame [px].
min_count: number of velocities required within the grid support.
outlier_k: number of neighbours used for the median test (0 = no test).
outlier_threshold: threshold of the test.
Returns:
velocity-field dict (module convention) + points (M, 2) / point_velocity (M, 2) (midpoints and velocities of linked pairs),
n_detected (per frame), n_linked, n_outliers (pairs discarded by the median test), n_rejected_blobs,
spacing (estimated spacing between individuals [m]).
• 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_piv · 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.