from_coco_file#

movement.io.load_poses.from_coco_file(file, fps=None, *, annotations_file=None, category_as_track=False, use_frame_numbers_from_file=False)[source]#

Create a movement poses dataset from a COCO keypoint results file.

Parameters:

  • file (str | Path) – Path to the COCO keypoint detection results JSON file.

  • fps (float | None) – Frames per second. If None (default), time coordinates are frame numbers.

  • annotations_file (str | Path | None) – Optional path to a COCO annotations JSON file, used for keypoint and individual names (see Notes).

  • category_as_track (bool) – If True, treat each category_id as one individual tracked across frames. If False (default), assign individuals by order of detection within each frame (see Notes).

  • use_frame_numbers_from_file (bool) – Frame numbers are taken from the image_id of each detection. If False (default), frame numbers are offset so that the lowest image ID becomes frame 0. If True, frame numbers are kept as the image IDs in the file. This may be useful if only a subset of the video’s frames were processed, but you want to keep the start of the video as the time origin. In both cases, the spacing between images is preserved, so any gaps show up in the time coordinates. For example, image IDs [5, 6, 9] in the file become [0, 1, 4] by default and remain [5, 6, 9] if True.

Returns:

movement pose tracks and confidence scores.

Return type:

Dataset

Notes

COCO keypoint results do not contain track identities. By default, the i-th detection of each image (in file order) is assigned to individual i (named id_i), so an individual does not necessarily correspond to the same animal across frames. How to handle this depends on your data:

  • One animal per frame: no action needed, all detections are assigned to id_0.

  • Multiple animals, one category per animal: set category_as_track=True. Each category present in the results then becomes one individual, named after the category if annotations_file is provided, or after its category_id (e.g. "3") otherwise. Multiple detections of the same category in the same image raise a ValueError.

  • Multiple animals sharing a category: identities are not reliable across frames. Assign them with a tracking tool before analyses that follow individuals over time (e.g. kinematics), and load the tracked output instead of the raw COCO results.

In movement, pose data can currently only be loaded if all individuals share the same set of keypoints. All detections in the results must therefore have the same number of keypoints. If annotations_file is provided, all its categories must also have the same keypoints list (same names, in the same order), with one name per keypoint in each detection. Otherwise, a ValueError is raised. Without an annotations file, keypoints are assigned default names keypoint_0, keypoint_1, etc. in file order.

Each keypoint in COCO results is stored as (x, y, v), where v is a visibility flag. As COCO recommends setting v=1 for all predicted keypoints, v carries no information in results files and is discarded. Only x and y are loaded as position. The per-detection score is loaded as individual-wise confidence, with dimensions (time, individual).

Examples

Create a dataset from the COCO results file at “path/to/results.json”, with the time coordinates in seconds, and the keypoints named after the categories in the annotations file at “path/to/annotations.json”.

>>> from movement.io import load_poses
>>> ds = load_poses.from_coco_file(
...     "path/to/results.json",
...     fps=30,
...     annotations_file="path/to/annotations.json",
... )

Create a dataset where each category identifies one individual tracked across frames, with individuals named after the categories in the annotations file.

>>> ds = load_poses.from_coco_file(
...     "path/to/results.json",
...     annotations_file="path/to/annotations.json",
...     category_as_track=True,
... )

Create a dataset using the image IDs as frame numbers, so that t = 0 seconds corresponds to image ID 0 (e.g. the first frame of the full video).

>>> ds = load_poses.from_coco_file(
...     "path/to/results.json",
...     fps=30,
...     use_frame_numbers_from_file=True,
... )