Skip to main content

Archive uploads

This tutorial will guide you through uploading media and annotations with either a zip or tar archive using tator-py. We will start with an archive containing only media, then add annotations.

Upload media only​

Create a zip or tar archive of videos and/or images in a flat directory structure. For example:

.
├── video_1.mp4
├── video_2.mp4
└── image_1.jpg

Note that unlike the single file upload utility upload_media, the media type of media in archives is inferred by the backend. This means that images and videos can both be present in the same archive if the project defines a media type for each. However, it is recommended that archive uploads are not used for projects with multiple media types with the same dtype (i.e. multiple image types or multiple video types).

Now upload the archive using the upload_media_archive tator-py utility.

import tator
api = tator.get_api(host='https://cloud.tator.io', token=MY_TOKEN)
for progress, response in tator.util.upload_media_archive(api, PROJECT_ID, ARCHIVE_PATH):
    print(f"Archive upload progress: {progress}%")
print(response.message)

After this code executes, the archive has been uploaded and an extract and transcode workflow has been initiated. To monitor the job status with polling, take a look at the single file upload tutorial.

Upload media with annotations​

The archive can also include annotations. Annotations are defined in csv format, with one csv per media file per annotation type. The path of each csv file must be one of:

  • <media base name>/localizations/<localization type ID>.csv

    or

  • <media base name>/states/<state type ID>.csv

For example, a full archive with annotations may look like:

.
├── video_1.mp4
├── video_1
│   ├── localizations
│   │   └── 3.csv
│   └── states
│       ├── 4.csv
│       └── 5.csv
├── video_2.mp4
├── video_2
│   └── states
│       ├── 4.csv
│       └── 5.csv
└── image_1.jpg

The csv headers for localizations are frame,x,y,width,height plus any attribute values for the localization type. An example csv for localizations is:

frame,x,y,width,height,Name
30,400,20,40,40,Street Sign

The csv headers for states depend on whether the state is a frame associated state or media associated. Localization associated states are not currently supported for archive uploads. For frame states, the csv header is just frame plus any attribute values for the state type. For media associated states only the attribute values are required.

After creating an archive that includes annotations, it can be uploaded with upload_media_archive in the same way as above.