Skip to main content

Extract localization images and track animations

Tator is able to quickly extract sub-images associated with localizations from both video and images for uses such as data validation, analytics, algorithm training, and algorithm inference. This tutorial will walk you through how to retrieve localization images from a video, then how to retrieve animations of a track using tator-py. To get started you will need the media ID of the videos you want to extract frames from. The video must contain localizations and tracks, which can be created using the web interface.

Retrieve localization images

Localization images can be extracted using the API member function get_localization_graphic. The function automatically stores the image locally and returns the file path. The example below extracts all localizations from the given media.

import tator
api = tator.get_api(host='', token=MY_TOKEN)
localizations = api.get_localization_list(PROJECT_ID, media_id=[MEDIA_ID])
img_paths = []
for localization in localizations:
img_path = api.get_localization_graphic(

Retrieve track animations

Track animations are GIFs that have been created from a time-sequence of localizations in a track. These can be created with the API member function get_state_graphic. Like get_localization_graphic, a file path is returned.

tracks = api.get_state_list(PROJECT_ID, media_id=[MEDIA_ID])
img_paths = []
for track in tracks:
img_path = api.get_state_graphic(

A separate utility is available called full_state_graphic that can retrieve localization sub-images for long tracks. This utility should be used if you want to retrieve a series of separate images rather than an animated GIF.

images = []
for track in tracks:
images += tator.util.full_state_graphic(