poseinterface.clips.extract_clip#

poseinterface.clips.extract_clip(video_path, start_frame, duration)[source]#

Extract a video clip (and its clip labels if available).

Reads the source video and saves a .mp4 clip to a Clips/ subdirectory next to the source video. If a sibling *_videolabels.json file exists (holding labels for the entire session video, using the same schema as cliplabels.json), a matching _cliplabels.json containing only the annotations within the requested frame range is also written.

Parameters:

  • video_path (str | Path) – Path to the input .mp4 video. The filename should follow the convention sub-<subjectID>_ses-<sessionID>_cam-<camID>.mp4, and if a sibling labels file exists, its filename should be sub-<subjectID>_ses-<sessionID>_cam-<camID>_videolabels.json.

  • start_frame (int) – Index of the first frame to include in the clip (0-based).

  • duration (int) – Number of frames to include in the clip. If start_frame + duration exceeds the video length, the duration is clamped to the remaining frames and a warning is logged.

Return type:

tuple[Path, Path | None]

Returns:

  • clip_path (Path) – Path to the output clip file.

  • clip_json (Path | None) – Path to the _cliplabels.json file for the clip if extracted, None otherwise.

Raises:

ValueError – If start_frame is negative or duration is not positive.

Notes

This function optionally consumes a *_videolabels.json file, sibling to the input video file and holding labels for the entire video. This file is an intermediate cache useful for data contributors: it follows the same schema as cliplabels.json but it refers to the full video, rather than to a clip of it. The *_videolabels.json file is not part of the published benchmark dataset. For further details, see the “Intermediate file: videolabels.json” section of the benchmark dataset specification.

This function assumes that the id field in the images list of the source *_videolabels.json corresponds to 0-based global frame indices of the full video.