from_via_tracks_file#

movement.io.load_bboxes.from_via_tracks_file(file_path, fps=None, use_frame_numbers_from_file=False, frame_regexp='(0\\\\d*)\\\\.\\\\w+$')[source]#

Create a movement dataset from a VIA tracks .csv file.

Parameters:

  • file_path (pathlib.Path or str) – Path to the VIA tracks .csv file with the tracked bounding boxes. For more information on the VIA tracks .csv file format, see the VIA tutorial for tracking [1].

  • fps (float, optional) – The video sampling rate. If None (default), the time coordinates of the resulting movement dataset will be in frame numbers. If fps is provided, the time coordinates will be in seconds. If the time coordinates are in seconds, they will indicate the elapsed time from the capture of the first frame (assumed to be frame 0).

  • use_frame_numbers_from_file (bool, optional) – If True, the frame numbers in the resulting dataset are the same as the ones in the VIA tracks .csv file. This may be useful if the bounding boxes are tracked for a subset of frames in a video, but you want to maintain the start of the full video as the time origin. If False (default), the frame numbers in the VIA tracks .csv file are instead mapped to a 0-based sequence of consecutive integers.

  • frame_regexp (str, optional) – Regular expression pattern to extract the frame number from the frame filename. By default, the frame number is expected to be encoded in the filename as an integer number led by at least one zero, followed by the file extension. Only used if use_frame_numbers_from_file is True.

Returns:

movement dataset containing the position, shape, and confidence scores of the tracked bounding boxes, and any associated metadata.

Return type:

xarray.Dataset

Notes

The bounding boxes’ IDs specified in the “track” field of the VIA tracks .csv file are mapped to the “individual_name” column of the movement dataset. The individual names follow the format id_<N>, with N being the bounding box ID.

References

Examples

Create a dataset from the VIA tracks .csv file at “path/to/file.csv”, with the time coordinates in frames, and setting the first tracked frame in the file as frame 0.

>>> from movement.io import load_bboxes
>>> ds = load_bboxes.from_via_tracks_file(
...     "path/to/file.csv",
... )

Create a dataset from the VIA tracks .csv file at “path/to/file.csv”, with the time coordinates in seconds, and assuming t = 0 seconds corresponds to the first tracked frame in the file.

>>> from movement.io import load_bboxes
>>> ds = load_bboxes.from_via_tracks_file(
...     "path/to/file.csv",
...     fps=30,
... )

Create a dataset from the VIA tracks .csv file at “path/to/file.csv”, with the time coordinates in frames, and using the same frame numbers as in the VIA tracks .csv file.

>>> from movement.io import load_bboxes
>>> ds = load_bboxes.from_via_tracks_file(
...     "path/to/file.csv",
...     use_frame_numbers_from_file=True.
... )

Create a dataset from the VIA tracks .csv file at “path/to/file.csv”, with the time coordinates in seconds, and assuming t = 0 seconds corresponds to the 0th frame in the full video.

>>> from movement.io import load_bboxes
>>> ds = load_bboxes.from_via_tracks_file(
...     "path/to/file.csv",
...     fps=30,
...     use_frame_numbers_from_file=True,
... )