dataeval.core.track_stats¶

dataeval.core.track_stats(tracks, frame_width=None, frame_height=None, edge_threshold=5.0, jitter_min_frames=10, jitter_fc=0.5)¶

Compute per-track statistics for a single video sequence.

Results are returned as lists indexed by position in sorted track ID order. The track_ids field maps each position back to its original track ID:

stats["track_ids"][i]  # the track ID at position i
stats["mean_speed"][i]  # mean speed for that track

Parameters:¶

tracks : collections.abc.Mapping[int, dataeval.types.Track]¶

Mapping from track ID to Track, as returned by build_tracks().

frame_width : int | None¶

Frame dimensions in pixels. Required for entry_at_edge and exit_at_edge; if either is None those fields will be populated with False for every track and a warning is logged.

frame_height : int | None¶

Frame dimensions in pixels. Required for entry_at_edge and exit_at_edge; if either is None those fields will be populated with False for every track and a warning is logged.

edge_threshold : float¶

A bounding box is considered to touch the frame border when any edge is within this many pixels of the frame boundary (inclusive). Default is 5 px.

jitter_min_frames : int¶

Minimum number of observed frames required to compute jitter. Default is 10.

jitter_fc : float¶

Hard upper frequency cutoff as a fraction of Nyquist (i.e. cycles-per-frame divided by 0.5). Must be in (0, 1]. Default is 0.5, meaning no hard cutoff beyond Nyquist (use only adaptive cutoff). Set lower to exclude high-frequency noise, e.g. 0.4 excludes the top 20% of the spectrum.

Returns:¶

A TrackStatsResult dict where every stat field is a Sequence indexed by position in sorted track ID order. Use track_ids[i] to recover the original track ID for position i.

Return type:¶

TrackStatsResult

Raises:¶

ValueError – When frame dimensions are not positive.