Skip to content

Commit

Permalink
bounding boxes tracks --> bounding box tracks
Browse files Browse the repository at this point in the history
  • Loading branch information
sfmig committed Jan 29, 2025
1 parent bae58ff commit afb4105
Show file tree
Hide file tree
Showing 6 changed files with 16 additions and 16 deletions.
2 changes: 1 addition & 1 deletion docs/source/blog/movement-v0_0_21.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ install the latest version or upgrade from an existing installation.
__Input/Output__

- We have added the {func}`movement.io.load_poses.from_multiview_files` function to support loading pose tracking data from multiple camera views.
- We have made several small improvements to reading bounding boxes tracks. See our new {ref}`example <sphx_glr_examples_load_and_upsample_bboxes.py>` to learn more about working with bounding boxes.
- We have made several small improvements to reading bounding box tracks. See our new {ref}`example <sphx_glr_examples_load_and_upsample_bboxes.py>` to learn more about working with bounding boxes.
- We have added a new {ref}`example <sphx_glr_examples_convert_file_formats.py>` on using `movement` to convert pose tracking data between different file formats.

__Kinematics__
Expand Down
2 changes: 1 addition & 1 deletion docs/source/community/mission-scope.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Animal tracking frameworks such as [DeepLabCut](dlc:) or [SLEAP](sleap:) can
generate keypoint representations from video data by detecting body parts and
tracking them across frames. In the context of `movement`, we refer to these
trajectories as _tracks_: we use _pose tracks_ to refer to the trajectories
of a set of keypoints, _bounding boxes tracks_ to refer to the trajectories
of a set of keypoints, _bounding box tracks_ to refer to the trajectories
of bounding boxes centroids, or _motion tracks_ in the more general case.

Our vision is to present a **consistent interface for representing motion
Expand Down
14 changes: 7 additions & 7 deletions docs/source/user_guide/input_output.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@
(target-formats)=
## Supported formats
(target-supported-formats)=
`movement` supports the analysis of trajectories of keypoints (_pose tracks_) and of bounding boxes centroids (_bounding boxes tracks_).
`movement` supports the analysis of trajectories of keypoints (_pose tracks_) and of bounding boxes centroids (_bounding box tracks_).

To analyse pose tracks, `movement` supports loading data from various frameworks:
- [DeepLabCut](dlc:) (DLC)
- [SLEAP](sleap:) (SLEAP)
- [LightingPose](lp:) (LP)
- [Anipose](anipose:) (Anipose)

To analyse bounding boxes tracks, `movement` currently supports the [VGG Image Annotator](via:) (VIA) format for [tracks annotation](via:docs/face_track_annotation.html).
To analyse bounding box tracks, `movement` currently supports the [VGG Image Annotator](via:) (VIA) format for [tracks annotation](via:docs/face_track_annotation.html).

:::{note}
At the moment `movement` only deals with tracked data: either keypoints or bounding boxes whose identities are known from one frame to the next, for a consecutive set of frames. For the pose estimation case, this means it only deals with the predictions output by the software packages above. It currently does not support loading manually labelled data (since this is most often defined over a non-continuous set of frames).
:::

Below we explain how you can load pose tracks and bounding boxes tracks into `movement`, and how you can export a `movement` poses dataset to different file formats. You can also try `movement` out on some [sample data](target-sample-data)
Below we explain how you can load pose tracks and bounding box tracks into `movement`, and how you can export a `movement` poses dataset to different file formats. You can also try `movement` out on some [sample data](target-sample-data)
included with the package.


Expand Down Expand Up @@ -129,15 +129,15 @@ For more information on the poses data structure, see the [movement poses datase


(target-loading-bbox-tracks)=
## Loading bounding boxes tracks
To load bounding boxes tracks into a [movement bounding boxes dataset](target-poses-and-bboxes-dataset), we need the functions from the
## Loading bounding box tracks
To load bounding box tracks into a [movement bounding boxes dataset](target-poses-and-bboxes-dataset), we need the functions from the
{mod}`movement.io.load_bboxes` module. This module can be imported as:

```python
from movement.io import load_bboxes
```

We currently support loading bounding boxes tracks in the VGG Image Annotator (VIA) format only. However, like in the poses datasets, we additionally provide a `from_numpy()` method, with which we can build a [movement bounding boxes dataset](target-poses-and-bboxes-dataset) from a set of NumPy arrays.
We currently support loading bounding box tracks in the VGG Image Annotator (VIA) format only. However, like in the poses datasets, we additionally provide a `from_numpy()` method, with which we can build a [movement bounding boxes dataset](target-poses-and-bboxes-dataset) from a set of NumPy arrays.

::::{tab-set}
:::{tab-item} VGG Image Annotator
Expand Down Expand Up @@ -280,7 +280,7 @@ Alternatively, we can convert the `movement` bounding boxes dataset to a pandas
## Sample data

`movement` includes some sample data files that you can use to
try the package out. These files contain pose and bounding boxes tracks from
try the package out. These files contain pose and bounding box tracks from
various [supported formats](target-supported-formats).

You can list the available sample data files using:
Expand Down
8 changes: 4 additions & 4 deletions docs/source/user_guide/movement_dataset.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
(target-poses-and-bboxes-dataset)=
# The movement datasets

In `movement`, poses or bounding boxes tracks are represented
In `movement`, poses or bounding box tracks are represented
as an {class}`xarray.Dataset` object.

An {class}`xarray.Dataset` object is a container for multiple arrays. Each array is an {class}`xarray.DataArray` object holding different aspects of the collected data (position, time, confidence scores...). You can think of a {class}`xarray.DataArray` object as a multi-dimensional {class}`numpy.ndarray`
with pandas-style indexing and labelling.

So a `movement` dataset is simply an {class}`xarray.Dataset` with a specific
structure to represent pose tracks or bounding boxes tracks. Because pose data and bounding boxes data are somewhat different, `movement` provides two types of datasets: `poses` datasets and `bboxes` datasets.
structure to represent pose tracks or bounding box tracks. Because pose data and bounding box data are somewhat different, `movement` provides two types of datasets: `poses` datasets and `bboxes` datasets.

To discuss the specifics of both types of `movement` datasets, it is useful to clarify some concepts such as **data variables**, **dimensions**,
**coordinates** and **attributes**. In the next section, we will describe these concepts and the `movement` datasets' structure in some detail.
Expand Down Expand Up @@ -139,7 +139,7 @@ In both cases, appropriate **coordinates** are assigned to each **dimension**.
:icon: info
The above **dimensions** and **coordinates** are created
by default when loading a `movement` dataset from a single
file containing pose or bounding boxes tracks.
file containing pose or bounding box tracks.

In some cases, you may encounter or create datasets with extra
**dimensions**. For example, the
Expand Down Expand Up @@ -179,7 +179,7 @@ Both poses and bounding boxes datasets in `movement` have associated metadata. T
Right after loading a `movement` dataset, the following **attributes** are created:
- `fps`: the number of frames per second in the video. If not provided, it is set to `None`.
- `time_unit`: the unit of the `time` **coordinates** (either `frames` or `seconds`).
- `source_software`: the software that produced the pose or bounding boxes tracks.
- `source_software`: the software that produced the pose or bounding box tracks.
- `source_file`: the path to the file from which the data were loaded.
- `ds_type`: the type of dataset loaded (either `poses` or `bboxes`).

Expand Down
4 changes: 2 additions & 2 deletions examples/load_and_upsample_bboxes.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
"""Load and upsample bounding boxes tracks
"""Load and upsample bounding box tracks
==========================================
Load bounding boxes tracks and upsample them to match the video frame rate.
Load bounding box tracks and upsample them to match the video frame rate.
"""

# %%
Expand Down
2 changes: 1 addition & 1 deletion movement/io/load_bboxes.py
Original file line number Diff line number Diff line change
Expand Up @@ -391,7 +391,7 @@ def _numpy_arrays_from_via_tracks_file(
Parameters
----------
file_path : pathlib.Path
Path to the VIA tracks .csv file containing the bounding boxes tracks.
Path to the VIA tracks .csv file containing the bounding box tracks.
frame_regexp : str
Regular expression pattern to extract the frame number from the frame
Expand Down

0 comments on commit afb4105

Please sign in to comment.