CVAT User Guide

Setting up CVAT

We chose to set up a self-hosted instance of CVAT on a remote server. We chose this option so we could manage our data more easily, and every person on our team could access the server remotely to complete their annotations. We set up our instance of CVAT on a server with a AMD EPYC 7513 32-Core Processor, running Ubuntu 20.04.6 LTS (GNU/Linux 5.4.0-190-generic x86_64). Please have a look at the CVAT Installation Guide for instructions to set up the tool using Docker on a computer running Ubuntu OS.

Note: CVAT may also be accessed online using CVAT Cloud or installed locally on Microsoft, Apple, and Linux computers. See the CVAT Getting Started documentation for instructions.

See CVAT's Manuals for further information.

Detailed Installation Instructions

Retrieve the CVAT source code. As of writing, the latest release of CVAT is v2.17.0. CVAT is updated frequently with new features and bug fixes. You may retrieve this (or any) specific version using wget:

CVAT_VERSION="v2.17.0" && CVAT_V="${CVAT_VERSION#v}"
wget https://github.com/cvat-ai/cvat/archive/refs/tags/${CVAT_VERSION}.zip && unzip ${CVAT_VERSION}.zip && mv cvat-${CVAT_V} cvat && rm ${CVAT_VERSION}.zip && cd cvat

Set the CVAT_HOST environment variable.

This should only be done once. Skip this if upgrading.

echo "export CVAT_HOST=localhost" >> ~/.bashrc
source ~/.bashrc

Optionally mount a host volume. To access data within CVAT from the host machine (rather than needing to upload through the browser), create the file docker-compose.override.yml in the same directory as docker-compose.yml. Add the following to the docker-compose.override.yml file:

services:
  cvat_server:
    volumes:
      - cvat_share:/home/django/share:ro
  cvat_worker_import:
    volumes:
      - cvat_share:/home/django/share:ro
  cvat_worker_export:
    volumes:
      - cvat_share:/home/django/share:ro
  cvat_worker_annotation:
    volumes:
      - cvat_share:/home/django/share:ro

volumes:
  cvat_share:
    driver_opts:
      type: none
      device: /abs/path/to/host/data/directory # Edit this line
      o: bind

Build CVAT.

Exclude the -f docker-compose.override.yml below if not mounting a host volume.

docker compose -f docker-compose.yml -f docker-compose.override.yml --build -d

Accessing CVAT

After CVAT was set up on our remote server, users ran the following commands in their terminal to use the CVAT web interface: ssh username@servername -N -L 8080:localhost:8080

Next, users navigated to Chrome, and entered 'http://localhost:8080/' into their browser to open the CVAT GUI.

Creating tasks in CVAT

1. Open CVAT web GUI by navigating to http://localhost:8080/ in Chrome.
2. Login to CVAT.
3. Navigate to Projects and click on your project.
4. Click on ‘Create multi tasks’
5. Navigate to ‘Connected file share’ and select the files you want to upload to create tasks. Note: this may take some time if the files are large.
6. Once a task is created for the video, you may delete the original video file from the server since CVAT will save the data in a different location.

Detections in CVAT

1. Once you login to CVAT, navigate to the Projects tab where you should see your assigned tasks. Click on the task to open it.

2. Choose a task to work and assign it to yourself under ‘Assignee’. Click on ‘Job #’ to open task.

3. Optional: Select a region of interest to zoom in on the scene.

4. Click on the rectangle and select the correct species. Check the filename if you aren’t sure. Make sure to select “Track”.

5. Draw a box around each animal in view.

6. Use the >> button, or press ‘V’ on your keyboard to advance 10 frames. Update the bounding boxes by dragging them to the correct positions as required. Make sure to save frequently!! You can stop, save, and start working on the video later at any time.

7. Continue until all the frames have been annotated. Save your results.

8. Once you are done, select “Validation” so the project lead knows the tasks is complete.

Behavior labeling in CVAT

1. Once you login to CVAT, navigate to the Projects tab where you should see your assigned tasks. Click on the task to open it.

2. Click on “Draw new points” (1) then select the appropriate animal (2). Next, select “Track”.

3. Place your dot anywhere on the screen and select the appropriate behavior. Here, the zebra is “Head Up” 

4. Continue annotating the video, updating the object label as the animal changes behavior. See the Updated Ethogram for explanations of the different behavior categories. Pay particular attention to the caveats on any “out of sight” sub-categories. Make sure to save current changes frequently. You can annotate part of a video and come back to complete it later.

5. Once you are done annotating, save the annotations for a final time change the job status to “completed” and then select “Finish the job.”

Downloading Annotations

You may download annotations for individual tasks, or the entire project.

1. Click on the 3 vertical dots in the lower right corner of the project or task.

2. Select "Export dataset" to export a project, or "Export task dataset" to export a task.

3. Export in "CVAT for video 1.1" format, deselect the option to "Save images", and click "Ok".

4. Once the export request is complete, navigate to the "Requests" tab and download the dataset.

5. To use your annotations.

For detections: You may use your detections to create mini-scenes using tracks_extractor. These mini-scenes be automatically annotated with behavior labels using KABR model.

For behaviors: You may use your annotated behaviors to fine-tune a behavior recognition model, such as X3D, or create time-budgets with notebooks/time_budget.ipynb.

Data Management for CVAT

See Data-Management-Tips for details.