API Reference#

BEEhaviourLab package.

Tracking#

beehaviourlab.tracking.extract_flow_info_df(df)#

Extracts flow information from the DataFrame, including velocity and speed.

Computes movement vectors (dx, dy), instantaneous speed, and smoothed speed for each tracked object across frames. Handles both corner coordinate format (x1, y1, x2, y2) and centre coordinate format (x, y).

Parameters:

df (pl.DataFrame) – The DataFrame containing bounding box data with columns: - stable_id: Object identifier - frame_id: Frame number - Either (x, y) centre coordinates OR (x1, y1, x2, y2) corner coordinates

Returns:

The DataFrame with additional flow information columns:

  • dx, dy: Movement vectors between consecutive frames

  • speed: Instantaneous speed (Euclidean distance moved)

  • speed_smoothed: Median-filtered speed over 5-frame window

  • x, y: Centre coordinates (converted from corners if needed)

  • w, h: Width and height (computed from corners if needed)

Return type:

pl.DataFrame

Note

  • Speed calculations use frame-to-frame differences within each stable_id

  • Missing values are filled with 0

  • Smoothing uses a rolling median filter with window size 5

  • Empty DataFrames will cause the function to exit with an error message

beehaviourlab.tracking.fix_ids_df(df, num_objects)#

Fixes the IDs in the DataFrame by assigning stable IDs to objects across frames.

Uses the Hungarian algorithm to maintain consistent object identities across frames by minimising the total movement distance between consecutive frame assignments.

Parameters:

  • df (pl.DataFrame) – The DataFrame containing bounding box data with columns: - frame_id: Frame number - x, y: Object centre coordinates - Other detection columns (class_id, conf, etc.)

  • num_objects (int) – Maximum number of objects to track with stable IDs.

Returns:

The DataFrame with fixed stable IDs and interpolated positions

for missing detections. Includes a new ‘stable_id’ column with consistent object identifiers from 1 to num_objects.

Return type:

pl.DataFrame

Note

  • Missing detections are filled with interpolated positions

  • Objects are assigned stable IDs from 1 to num_objects

  • Assignment is based on minimising Euclidean distance between frames

beehaviourlab.tracking.save_bboxes_to_file(model_path, source_video, output_path, conf_threshold, xywh=False, track=False)[source]#

Save bounding box detections from a video to a CSV file.

Processes a video using a YOLO model to detect objects and optionally track them across frames. The resulting bounding box data is saved to a CSV file with configurable output formats.

Parameters:

  • model_path (str) – Path to the YOLO model file (.pt format).

  • source_video (str) – Path to the input video file.

  • output_path (str) – Path where the output CSV file will be saved.

  • conf_threshold (float) – Confidence threshold for filtering detections (0.0-1.0).

  • xywh (bool) – Whether to output bounding boxes in x,y,w,h format instead of x1,y1,x2,y2 format. Only applies when tracking is disabled.

  • track (bool) – Whether to enable object tracking across frames.

Return type:

DataFrame

Returns:

A Polars DataFrame containing the detection/tracking data with columns depending on the configuration: - With tracking: [“frame_id”, “class_id”, “x”, “y”, “w”, “h”, “track_id”, “conf”] - Without tracking + xywh=True: [“frame_id”, “class_id”, “x”, “y”, “w”, “h”, “conf”] - Without tracking + xywh=False: [“frame_id”, “class_id”, “x1”, “y1”, “x2”, “y2”, “conf”]

Raises:

  • FileNotFoundError – If the model file or video file doesn’t exist.

  • ValueError – If the confidence threshold is not between 0.0 and 1.0.

  • RuntimeError – If the video cannot be opened or processed.

Note

When tracking is enabled, all detections are saved regardless of confidence threshold. The threshold only applies to non-tracking mode.