Tator Python Client Documentation

Utility Functions

Shortcuts

get_api

tator.get_api(host=‘https://cloud.tator.io’, token=None)

Retrieves a tator.api instance using the given host and token.

• Parameters

  • host – URL of host. Default is https://cloud.tator.io.
  • token – API token.

• Returns

  tator.api object.

get_parser

tator.get_parser(parser=None, description=None)

Returns an argument parser that includes host and token.

• Returns

  argparse.ArgumentParser object that includes host and token arguments.

download_media

tator.download_media(api, media, out_path, quality=None, media_type=None, codec_or_mime=None)

Download a media file from Tator to an off-line location.

Example:

api = tator.get_api(host, token)
media = api.get_media(media_id)
out_path = f'/tmp/{media.name}'
for progress in tator.util.download_media(api, media, out_path):
    print(f"Download progress: {progress}%")

#download 720p version streaming
for progress in tator.util.download_media(api,
                                          media,
                                          out_path,
                                          720,
                                          'streaming'):
    print(f"Download progress: {progress}%")

• Parameters

  • api – tator.TatorApi object.
  • media – tator.Media object.
  • out_path (path-like) – Path to where to download.
  • quality (int) – Attempts to fetch this resolution (defaults to best)
  • media_type (str) – The desired item to download (archival, streaming, image, thumbnail, or thumbnail_gif). Not all types are valid for all media.
  • codec_or_mime (str) – The desired codec or mime if multiple exist at the same resolution. e.g. h264 for video or image/jpeg for images.

• Returns

  Generator the yields progress (0-100).

Full utility Library

Utility functions for interacting with the Tator platform

MediaUtil

class tator.util.MediaUtil(temp_dir)

Top-level class to construct to handle per-media manipulations

get_animation(frames, fps, roi=None, render_format=‘mp4’, force_scale=None)

Return an animation of frames at a given FPS.

• Parameters
  • frames – list of frames
  • fps – FPS of output animation

get_clip(frame_ranges)

Given a list of frame ranges generate a temporary mp4

• Parameters frame_ranges – tuple or list of tuples representing (begin, end) – range is inclusive!

get_tile_image(frames, rois=None, tile_size=None, render_format=‘jpg’, force_scale=None)

Generate a tile jpeg of the given frame/rois

load_from_media_object(media_obj, quality=None)

Initialize the MediaUtil with a tator media object (loaded with presigned URLs)

• image or video, no live or multi
• Parameters
  • media_obj – The a :ref models.Media: object with presigned URLs
  • quality – Vertical resolution to use as source, will find closest match. Defaults to highest.

load_from_url(video_url, segment_url, height, width, fps)

Setup the MediaUtil instance with primitive types

• Parameters
  • video_url – Publically accessible URL to the raw segmented mp4 file to use
  • segment_url – Publically accessible URL for the segmentation map file.
  • height – The vertical resolution of the video
  • width – The horizontal resolution of the video
  • fps – The frames per second of the video

chunked_create

tator.util.chunked_create(func: Callable, project: int, chunk_size: int = 500, **kwargs)

Breaks a create_*_list operation into chunks. Example:

created_ids = [
    new_id
    for response in tator.util.chunked_create(
        api.create_localization_list, chunk_size=100, body=my_long_list
    )
    for new_id in response.id
]

• Parameters

  • func – Function to call on each chunk.
  • project – Unique integer identifying a project.
  • chunk_size – [Optional] Sets the size of the chunks, defaults to 500.
  • kwargs – Exactly one keyword argument should be set, which contains the list of specs to create and is passed to func

• Returns

  Generator that yields a response.

chunked_file_list

tator.util.chunked_file_list(paths, chunk_size=100)

Breaks file list into chunks for upload via media archive.

Example:

api = tator.get_api(host, token)
batch_num = 0
for batch in tator.util.chunked_file_list(paths):
    print(f"Uploading file {batch_num*100} / {len(paths)}")
    for progress, response in tator.util.upload_media_archive(api, project_id, batch):
        print(f"Upload progress: {progress}%")
    print(response.message)
    batch_num += 1

• Parameters

  • paths – List of file paths.
  • chunk_size – [Optional] Size of batches for file upload. Archive uploads are created in memory, so this should be set to a reasonable value based on file size. Default is 100.

• Returns

  Generator that yields batches of file paths.

clone_leaf_list

tator.util.clone_leaf_list(src_api, query_params, dest_project, parent_mapping, leaf_type_mapping, dest_api=None)

Clone leaf list.

This can be used to clone leaves from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
query_params = {'project': 1, 'depth': 1}
dest_project = 1
created_ids = []
parent_mapping = {1: 10} # Mapping of parent leaf IDs
leaf_type_mapping = {1: 10} # Source leaf type ID -> Dest leaf type ID
generator = clone_leaf_list(src_api, query_params, dest_project, parent_mapping,
                            leaf_type_mapping, dest_api)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} leafs...")
    created_ids.append(response.id)
print(f"Finished creating {num_created} leafs!")

Example for same host:

api = tator.get_api(host, token)
query_params = {'project': 1, 'depth': 1}
dest_project = 1
parent_mapping = {1: 10}
leaf_type_mapping = {1: 10} # Source leaf type ID -> Dest leaf type ID
created_ids = []
generator = clone_leaf_list(api, query_params, dest_project, parent_mapping)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} leafs...")
    created_ids += response.id
print(f"Finished creating {num_created} leafs!")

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • query_params – Dictionary containing query parameters for source leaf list.
  • dest_project – Unique integer identifying destination project.
  • parent_mapping – Dictionary mapping source parent leaf IDs to destination parent leaf IDs. If the source leaf list contains a parent ID for which a destination parent ID is not supplied, an exception is raised.
  • leaf_type_mapping – Dictionary mapping source leaf type IDs to destination leaf_type IDs. If the source leaf list contains a leaf type ID for which a destination leaf type ID is not supplied, an exception is raised.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Generator containing number of leafs created, number of leafs total, most recent response from leaf creation operation, and mapping between original IDs and created IDs.

clone_leaf_type

tator.util.clone_leaf_type(src_api, src_type_id, dest_project, dest_api=None)

Clone leaf type.

This can be used to clone leaf types from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
src_type_id = 1
dest_project = 1
response = tator.util.clone_leaf_type(src_api, src_type_id, dest_project, dest_api)
print(response.message)

Example for same host:

api = tator.get_api(host, token)
src_type_id = 1
dest_project = 1
response = tator.util.clone_leaf_type(src_api, src_type_id, dest_project)
print(response.message)

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • src_type_id – Unique integer identifying leaf type to clone.
  • dest_project – Unique integer identifying destination project.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Response from leaf type creation request.

clone_localization_list

tator.util.clone_localization_list(src_api, query_params, dest_project, version_mapping, media_mapping, localization_type_mapping, dest_api=None)

Clone localization list.

This can be used to clone localizations from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
query_params = {'project': 1, 'media_id': [1]}
version_mapping = {1: 10} # Source version ID -> Dest version ID
media_mapping = {1: 10} # Source media ID -> Dest media ID
localization_type_mapping = {1: 10} # Source localization type ID -> Dest type ID
dest_project = 1
created_ids = []
generator = clone_localization_list(src_api, query_params, dest_project, version_mapping,
                                    media_mapping, localization_type_mapping, dest_api)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} localizations...")
    created_ids.append(response.id)
print(f"Finished creating {num_created} localizations!")

Example for same host:

api = tator.get_api(host, token)
query_params = {'media_id': [1]}
dest_project = 1
version_mapping = {1: 10}
media_mapping = {1: 10}
localization_type_mapping = {1: 10} # Source localization type ID -> Dest type ID
created_ids = []
generator = clone_localization_list(src_api, query_params, dest_project, version_mapping,
                                    media_mapping, localization_type_mapping)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} localizations...")
    created_ids += response.id
print(f"Finished creating {num_created} localizations!")

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • query_params – Dictionary containing query parameters for source localization list.
  • dest_project – Unique integer identifying destination project.
  • version_mapping – Dictionary mapping source version IDs to destination version IDs. If the source localization list contains a version ID for which a destination version is not supplied, an exception is raised.
  • media_mapping – Dictionary mapping source media IDs to destination media IDs. If the source localization list contains a media ID for which a destination media is not supplied, an exception is raised.
  • localization_type_mapping – Dictionary mapping source localization type IDs to destination localization_type IDs. If the source localization list contains a localization type ID for which a destination localization type ID is not supplied, an exception is raised.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Generator containing number of localizations created, number of localizations total, most recent response from localization creation operation, and mapping between original IDs and created IDs.

clone_localization_type

tator.util.clone_localization_type(src_api, src_type_id, dest_project, media_type_mapping, dest_api=None)

Clone localization type.

This can be used to clone localization types from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
src_type_id = 1
dest_project = 1
media_type_mapping = {1: 10}
response = tator.util.clone_localization_type(src_api, src_type_id, dest_project,
                                              media_type_mapping, dest_api)
print(response.message)

Example for same host:

api = tator.get_api(host, token)
src_type_id = 1
dest_project = 1
response = tator.util.clone_localization_type(src_api, src_type_id, dest_project,
                                              media_type_mapping)
print(response.message)

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • src_type_id – Unique integer identifying localization type to clone.
  • dest_project – Unique integer identifying destination project.
  • media_type_mapping – Dictionary mapping source media types to destination media types.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Response from localization type creation request.

clone_media_list

tator.util.clone_media_list(src_api, query_params, dest_project, media_mapping={}, dest_type=-1, dest_section=”, dest_api=None, ignore_transfer=False)

Clone media list.

This can be used to clone media from one project to another or from one host to another. In the case of the same host, the media files are not copied. If the destination host is different (dest_api is a tator.TatorApi object), the transcoded files for each media object is downloaded and then uploaded to the other host, and a new tator.Media object is created.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
query_params = {'project': 1, 'media_id': [1]}
media_mapping = {} # Only required if query contains multi media types
dest_project = 1
dest_type = -1
dest_section = 'My cloned media'
created_ids = []
generator = clone_media_list(src_api, query_params, dest_project, media_mapping,
                             dest_type, dest_section, dest_api)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} files...")
    created_ids.append(response.id[0])
print(f"Finished creating {num_created} files!")

Example for same host:

api = tator.get_api(host, token)
query_params = {'media_id': [1]}
dest_project = 1
created_ids = []
generator = clone_media_list(src_api, query_params, dest_project)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} files...")
    created_ids += response.id[0] # This response is from the CloneMedia endpoint.
print(f"Finished creating {num_created} files!")

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • query_params – Dictionary containing query parameters for source media list.
  • dest_project – Unique integer identifying destination project.
  • media_mapping – Mapping between source and destination media IDs. Only used if the media list contains multi media types and the clone is being done for different hosts.
  • dest_type – Unique integer identifying destination media type. If set to -1, the media type is set to the first media type in the project.
  • dest_section – Name of destination section.
  • dest_api – tator.TatorApi object corresponding to destination host.
  • ignore_transfer – True if media files should not be transferred. Media object will still be created. Paths in media_files will be invalid.

• Returns

  Generator containing number of files created, number of files total, most recent response from media creation operation, and mapping between original IDs and created IDs.

clone_media_type

tator.util.clone_media_type(src_api, src_type_id, dest_project, dest_api=None)

Clone media type.

This can be used to clone media types from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
src_type_id = 1
dest_project = 1
response = tator.util.clone_media_type(src_api, src_type_id, dest_project, dest_api)
print(response.message)

Example for same host:

api = tator.get_api(host, token)
src_type_id = 1
dest_project = 1
response = tator.util.clone_media_type(src_api, src_type_id, dest_project)
print(response.message)

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • src_type_id – Unique integer identifying media type to clone.
  • dest_project – Unique integer identifying destination project.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Response from media type creation request.

clone_membership

tator.util.clone_membership(src_api, src_membership_id, dest_project, user_mapping=None, dest_api=None)

Clone membership.

This can be used to clone memberships from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
src_membership_id = 1
dest_project = 1
user_mapping = {1: 10} # Mapping between user ID on source host and destination host.
response = tator.util.clone_membership(src_api, src_membership_id, dest_project,
                                       user_mapping, dest_api)
print(response.message)

Example for same host:

api = tator.get_api(host, token)
src_membership_id = 1
dest_project = 1
response = tator.util.clone_membership(src_api, src_membership_id, dest_project)
print(response.message)

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • src_membership_id – Unique integer identifying membership to clone.
  • dest_project – Unique integer identifying destination project.
  • user_mapping – If cloning to different host, the mapping between source and destination user IDs.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Response from membership creation request.

clone_section

tator.util.clone_section(src_api, src_section_id, dest_project, dest_api=None)

Clone section.

This can be used to clone sections from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
src_section_id = 1
dest_project = 1
response = tator.util.clone_section(src_api, src_section_id, dest_project, dest_api)
print(response.message)

Example for same host:

api = tator.get_api(host, token)
src_section_id = 1
dest_project = 1
response = tator.util.clone_section(src_api, src_section_id, dest_project)
print(response.message)

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • src_section_id – Unique integer identifying section to clone.
  • dest_project – Unique integer identifying destination project.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Response from section creation request.

clone_state_list

tator.util.clone_state_list(src_api, query_params, dest_project, version_mapping, media_mapping, localization_mapping, state_type_mapping, dest_api=None)

Clone state list.

This can be used to clone states from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
query_params = {'project': 1, 'media_id': [1]}
version_mapping = {1: 10} # Source version ID -> Dest version ID
media_mapping = {1: 10} # Source media ID -> dest media ID
localization_mapping = {} # For tracks, source localization ID -> dest localization ID
state_type_mapping = {1: 10} # Source state type ID -> Dest state type ID
dest_project = 1
dest_version = -1
created_ids = []
generator = clone_state_list(src_api, query_params, dest_project, version_mapping,
                             media_mapping, localization_mapping, state_type_mapping,
                             dest_api)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} states...")
    created_ids.append(response.id)
print(f"Finished creating {num_created} states!")

Example for same host:

api = tator.get_api(host, token)
query_params = {'media_id': [1]}
dest_project = 1
version_mapping = {1: 10} # Source version ID -> Dest version ID
media_mapping = {1: 10}
localization_mapping = {}
state_type_mapping = {1: 10} # Source state type ID -> Dest state type ID
created_ids = []
generator = clone_state_list(src_api, query_params, dest_project, version_mapping,
                             media_mapping, localization_mapping, state_type_mapping)
for num_created, num_total, response, id_map in generator:
    print(f"Created {num_created} of {num_total} states...")
    created_ids += response.id
print(f"Finished creating {num_created} states!")

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • query_params – Dictionary containing query parameters for source state list.
  • dest_project – Unique integer identifying destination project.
  • version_mapping – Dictionary mapping source version IDs to destination version IDs. If the source localization list contains a version ID for which a destination version is not supplied, an exception is raised.
  • media_mapping – Dictionary mapping source media IDs to destination media IDs. If the source state list contains a media ID for which a destination media is not supplied, an exception is raised.
  • localization_mapping – Dictionary mapping source localization IDs to destination localization IDs. If the source state list contains a localization ID for which a destination localization ID is not supplied, an exception is raised.
  • state_type_mapping – Dictionary mapping source state type IDs to destination state_type IDs. If the source state list contains a state type ID for which a destination state type ID is not supplied, an exception is raised.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Generator containing number of states created, number of states total, most recent response from state creation operation, and mapping between original IDs and created IDs.

clone_state_type

tator.util.clone_state_type(src_api, src_type_id, dest_project, media_type_mapping, dest_api=None)

Clone state type.

This can be used to clone state types from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
src_type_id = 1
dest_project = 1
media_type_mapping = {1: 10}
response = tator.util.clone_state_type(src_api, src_type_id, dest_project,
                                              media_type_mapping, dest_api)
print(response.message)

Example for same host:

api = tator.get_api(host, token)
src_type_id = 1
dest_project = 1
response = tator.util.clone_state_type(src_api, src_type_id, dest_project,
                                              media_type_mapping)
print(response.message)

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • src_type_id – Unique integer identifying state type to clone.
  • dest_project – Unique integer identifying destination project.
  • media_type_mapping – Dictionary mapping source media types to destination media types.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Response from state type creation request.

clone_version

tator.util.clone_version(src_api, src_version_id, dest_project, version_mapping={}, dest_api=None)

Clone version.

This can be used to clone versions from one project to another or from one host to another.

Example for different host:

src_api = tator.get_api(host, token)
dest_api = tator.get_api(other_host, other_token)
src_version_id = 1
dest_project = 1
version_mapping = {} # Necessary if source version has base versions.
response = tator.util.clone_version(src_api, src_version_id, dest_project,
                                    version_mapping, dest_api)
print(response.message)

Example for same host:

api = tator.get_api(host, token)
src_version_id = 1
dest_project = 1
response = tator.util.clone_version(src_api, src_version_id, dest_project)
print(response.message)

• Parameters

  • src_api – tator.TatorApi object corresponding to source host or only host if this is a clone on same host.
  • src_version_id – Unique integer identifying version to clone.
  • dest_project – Unique integer identifying destination project.
  • version_mapping – Dictionary mapping source version IDs to destination version IDs. Necessary if source version defines bases field.
  • dest_api – tator.TatorApi object corresponding to destination host.

• Returns

  Response from version creation request.

download_attachment

tator.util.download_attachment(api, media, out_path, index=0)

Download an attachment from Tator to an off-line location.

Example:

api = tator.get_api(host, token)
media = api.get_media(media_id)
out_path = f'/tmp/{media.name}'
for progress in tator.util.download_attachment(api, media, out_path):
    print(f"Download progress: {progress}%")

#download second attachment
for progress in tator.util.download_attachment(api, media, out_path, index=1):
    print(f"Download progress: {progress}%")

• Parameters

  • api – tator.TatorApi object.
  • media – tator.Media object.
  • out_path (path-like) – Path to where to download.
  • index – Integer indicating which attachment to download.

• Returns

  Generator that yields progress (0-100).

download_media

tator.util.download_media(api, media, out_path, quality=None, media_type=None, codec_or_mime=None)

Download a media file from Tator to an off-line location.

Example:

api = tator.get_api(host, token)
media = api.get_media(media_id)
out_path = f'/tmp/{media.name}'
for progress in tator.util.download_media(api, media, out_path):
    print(f"Download progress: {progress}%")

#download 720p version streaming
for progress in tator.util.download_media(api,
                                          media,
                                          out_path,
                                          720,
                                          'streaming'):
    print(f"Download progress: {progress}%")

• Parameters

  • api – tator.TatorApi object.
  • media – tator.Media object.
  • out_path (path-like) – Path to where to download.
  • quality (int) – Attempts to fetch this resolution (defaults to best)
  • media_type (str) – The desired item to download (archival, streaming, image, thumbnail, or thumbnail_gif). Not all types are valid for all media.
  • codec_or_mime (str) – The desired codec or mime if multiple exist at the same resolution. e.g. h264 for video or image/jpeg for images.

• Returns

  Generator the yields progress (0-100).

download_temporary_file

tator.util.download_temporary_file(api, temporary_file, out_path)

Download a temporary file from Tator to an off-line location.

Example:

api = tator.get_api(host, token)
temporary_file = api.get_temporary_file(temporary_file_id)
out_path = f'/tmp/{temporary_file.name}'
for progress in tator.util.download_temporary_file(api, temporary_file,
                                              out_path):
    print(f"Download progress: {progress}%")

• Parameters

  • api – tator.TatorApi object.
  • temporary_file – tator.models.TemporaryFile object.
  • out_path (path-like) – Path to where to download.

• Returns

  Generator that yields progress (0-100).

find_single_change

tator.util.find_single_change(api: tator.TatorApi, project_id: int, entity_id: int, field_name: str, old_value: Any | None = None, new_value: Any | None = None, find_last_change: bool = False)

Finds the ChangeLog containing the desired field/value combination.

Example:

api = tator.get_api(host, token)
change_log = tator.util.find_change(api, media_id, "_deleted", new_value=True)
print(change_log)

At least one of old_value and new_value must be specified; if both are specified, then the matching changelog must match both, not just one.

The field_name must be prefixed with an underscore if it is not a user-defined attribute, note how “_deleted” corresponds to the Media.deleted field.

• Parameters

  • api (tator.TatorApi) – tator.TatorApi object.
  • project_id (int) – Unique integer identifying a project in tator.
  • entity_id (int) – Unique integer identifying an entity with tracked changes, must identify a leaf, localization, media, or state.
  • field_name (str) – The name of the field in which to look for the change(s).
  • old_value (Optional*[Any]*) – [Optional] The desired old value to find
  • new_value (Optional*[Any]*) – [Optional] The desired new value to find
  • find_last_change (bool) – If True, finds the last matching ChangeLog, otherwise finds the first.

• Returns

  The changelog corresponding to the desired value(s) to find or None if no matches are found.

• Return type

  Optional[ChangeLog]

full_state_graphic

tator.util.full_state_graphic(api, state_id, force_scale=None)

Retrieves all detection images for a state.

Example:

state_graphic = full_state_graphic(api, state_id)

• Parameters

  • api – tator.TatorApi object.
  • state_id – Unique integer identifying a localization-associated state.
  • force_scale – (Optional) wxh to force each tile prior to stitch.

• Returns

  List containing all detection images in this state.

get_api

tator.util.get_api(host=‘https://cloud.tator.io’, token=None)

Retrieves a tator.api instance using the given host and token.

• Parameters

  • host – URL of host. Default is https://cloud.tator.io.
  • token – API token.

• Returns

  tator.api object.

get_images

tator.util.get_images(file_path, media_or_state, num_images=None, width=None, height=None)

Loads image saved by tator.api.get_frame()

Can also be used with tator.api.get_state_graphic().

• Returns

  A list of PIL.Image.Image

• Parameters

  • file_path – Path to image file.
  • media_or_state – tator.Media or tator.State object.
  • num_images – [Optional] The number of images to unwrap if this is an image saved by tator.TatorApi.get_frame(), or if the offset or length parameters were used in tator.TatorApi.get_state_graphic().
  • width – [Optional] Width of ROI if this is an image saved by tator.TatorApi.get_frame().
  • height – [Optional] Height of ROI if this is an image saved by tator.TatorApi.get_frame().

get_paginator

tator.util.get_paginator(api, func_name: str, batch_size: int | None = 1000)

Returns a Paginator object that returns pages of results from the given func_name. Example:

import tator
api = tator.get_api(host, token)
media_paginator = tator.util.get_paginator(api, "get_media_list")
page_iterator = media_paginator.paginate(project=project_id)
all_media = []
for page in page_iterator:
    for media in page:
        all_media.append(media)

• Parameters

  • api – tator.TatorApi object.
  • func_name (str) –
  • batch_size (int) –

• Raises ValueError if the func_name does not match the expected pattern or if it does not exist.

• Returns

  Paginator object

import_media

tator.util.import_media(api, type_id, url, md5=None, section=None, fname=None, upload_gid=None, upload_uid=None, chunk_size=2097152, attributes=None, media_id=None, size=None, _request_timeout=10)

Imports a hosted media file.

Example:

api = tator.get_api(host, token)
response = tator.util.import_media(api, type_id, url)
print(response.message)

• Parameters
  • api – tator.TatorApi object.
  • type_id – Unique integer identifying a media type.
  • url – URL of the hosted media file.
  • md5 – [Optional] md5 sum of the media.
  • section – [Optional] Media section to upload to.
  • fname – [Optional] Filename to use for upload.
  • upload_gid – [Optional] Group ID of the upload.
  • upload_uid – [Optional] Unique ID of the upload.
  • chunk_size – [Optional] Chunk size in bytes. Default is 2MB.
  • attributes – [Optional] Attributes to apply to media object.
  • media_id – [Optional] Unique ID of existing media object.
  • size – [Optional] Size of the file in bytes. Required if the given URL does not accept HEAD requests.

make_concat

tator.util.make_concat(api, name, media_ids, section, offsets=None)

Uploads a single media file.

• Parameters

  • api – tator.TatorApi object.
  • name – Name of the file to use
  • media_ids – List of media_ids to multi-stream
  • section – Section name. If this section does not exist it will be created.
  • offsets – Section name. If this section does not exist it will be created.

• Returns

  Response from media object creation.

make_live_stream

tator.util.make_live_stream(api, type_id, layout, name, section, feedInfo)

Make a live stream tator media object.

• Parameters

  • api – tator.TatorApi object.
  • type_id – Unique integer identifying a multi-stream media type.
  • layout – 2 element list of integers defining layout as [rows, cols].
  • name – Name of the file to use
  • section – Section name. If this section does not exist it will be created.
  • feed_info – maybeList of tator.models.LiveDefinition object or dictionary.

• Returns

  Response from media object creation.

make_multi_stream

tator.util.make_multi_stream(api, type_id, layout, name, media_ids, section, quality=None, frame_offset=None)

Creates a multiview from the given arguments

• Parameters

  • api (tator.openapi.TatorApi) – The Tator client
  • type_id (int) – Unique integer identifying a multi-stream media type.
  • layout (List*[int]*) – 2 element list of integers defining layout as [rows, cols].
  • name (str) – Name of the file to use
  • media_ids (List*[int]*) – List of media_ids to multi-stream
  • section (str) – Section name; if it does not exist, it will be created.
  • quality (List*[int]*) – [Optional] The desired resolution to pull from the single media
  • frame_offset (List*[int]*) – [Optional] Frame offsets to apply to each stream.

• Returns

  Response from media object creation.

md5sum

tator.util.md5sum(fname, size=None)

Computes md5sum-based fingerprint of a file contents. The return

is the md5sum of the file contents (up to 100Mb) hashed along with
the file size.

• Parameters

  • fname – Path to file.
  • size – Size of file. Will be computed if not given.

• Returns

  md5 sum of the file.

register_algorithm

tator.util.register_algorithm(host: str, token: str, project: int, manifest: str, algorithm_name: str, files_per_job: int, categories: list = [], description: str = ”, cluster_id: int | None = None) layout: ../../../../layouts/DocLayout.astro

Registers an algorithm argo workflow using the provided parameters

This will upload the given manifest file, save it to tator, and the new server side URL will be used when registering the workflow. This may change the filename of the manifest file.

Args:

host: Host URL
token: User token used for connecting to the host
project: Unique identifier of project associated with algorithm
manifest: Local path to argo workflow manifest file to upload, save,

> and register the algorithm with

algorithm_name: Unique name of the workflow
files_per_job: Number of media to process per workflow created
description: Optional description of workflow

layout: ../../../../layouts/DocLayout.astro cluster_id: Optional unique integer identifying the job cluster

register_applet

tator.util.register_applet(host: str, token: str, project: int, html_file: str, applet_name: str, categories: list = [], description: str = ”) layout: ../../../../layouts/DocLayout.astro

Registers a applet using the provided parameters

This will upload the given html file, save it to tator, and the new server side URL will be used when registering the applet. This may change the filename of the uploaded file

• Parameters
  • host – Host URL
  • token – User token used for connecting to the host
  • project – Unique identifier of project associated with algorithm
  • html_file – Local path to applet html file
  • applet_name – Name of the applet
  • categories – Optional categories the applet belongs to
  • description – Optional applet description

supplement_video_to_media

tator.util.supplement_video_to_media(api, media_id, role, configuration, filepath: str, force=False)

This routine will transcode filepath based on configuration to media_object See tator.api.delete_video_file() for information on deleting resolutions from a media object

• Parameters
  • api – An initialized tator.api project
  • media_id – Id of the media to supplement to
  • role – One of ‘streaming’ or ‘archival’
  • configuration – For ‘streaming’ roles, must be a tator.models.ResolutionConfig, for ‘archival’ roles must be a tator.models.EncodeConfig
  • filepath – The local file path to the file to encode
  • force – If true, will ignore any differences in the source file compared to what was previously encoded. This is very dangerous as it could result in streams of different lengths or even different files.

to_dataframe

tator.util.to_dataframe(objects)

Converts list of objects to pandas.DataFrame.

• Parameters object – List of objects.

• Returns

  Pandas dataframe.

update_applet

tator.util.update_applet(host: str, token: str, applet_id: int, html_file: str | None = None, applet_name: str | None = None, categories: list | None = None, description: str | None = None) layout: ../../../../layouts/DocLayout.astro

Updates an existing applet using the provided parameters

• Parameters
  • host – Host URL
  • token – User token used for connecting to the host
  • project – Unique identifier of project associated with algorithm
  • html_file – Local path to applet html file
  • applet_name – Name of the applet
  • categories – Optional categories the applet belongs to
  • description – Optional applet description

upload_attachment

tator.util.upload_attachment(api, media, path, name=None, chunk_size=104857600)

Upload a file as an attachment to a media object. Example:

api = tator.get_api(host, token)
for progress, response in tator.util.upload_attachment(api, media_id, path):
    print(f"Upload progress: {progress}%")
print(response.message)

• Parameters

  • api – tator.TatorApi object.
  • media – Unique integer identifying a media.
  • path – Path to the file.
  • name – [Optional] Name of file in database. Defaults to basename of path.
  • chunk_size – [Optional] Chunk size in bytes. Default is 100MB.

• Returns

  Generator that yields tuple containing progress (0-100) and a response. The response is None until the last yield, when the response is the response object from tator.util.TatorApi.create_auxiliary_file().

upload_generic_file

tator.util.upload_generic_file(api, file_type, path, description, name=None, attributes=None, timeout=None)

Upload a file to the File storage location.

Example:

api = tator.get_api(host, token)
for progress, response in tator.util.upload_generic_file(api, project_id, path):
    print(f"Upload progress: {progress}%")
print(response)

• Parameters

  • api – tator.TatorApi object.
  • file_type – Unique integer identifying a FileType.
  • path – Path to the file.
  • description – Description of the file to be uploaded.
  • name – [Optional] Name of temporary file in database. Defaults to basename of path.
  • attributes – [Optional] Attributes to set on the uploaded file.
  • timeout – [Optional] Timeout for the tator.util._upload_file._upload_file() operation.

• Returns

  Generator that yields tuple containing progress (0-100) and a response. The response is None until the last yield, when the response is the updated response object from tator.util.TatorApi.get_file().

upload_media

tator.util.upload_media(api, type_id, path, md5=None, section=None, fname=None, upload_gid=None, upload_uid=None, chunk_size=10485760, attributes=None, email_spec=None, media_id=None, timeout=30, max_workers=10)

Uploads a single media file.

Example:

api = tator.get_api(host, token)
for progress, response in tator.util.upload_media(api, type_id, path):
    print(f"Upload progress: {progress}%")
print(response.message)

• Parameters

  • api – tator.TatorApi object.
  • type_id – Unique integer identifying a media type.
  • path – Path to the media file.
  • md5 – [Optional] md5 sum of the media.
  • section – [Optional] Section name. If a section with this name does not exist it will be created.
  • fname – [Optional] Filename to use for upload.
  • upload_gid – [Optional] Group ID of the upload.
  • upload_uid – [Optional] Unique ID of the upload.
  • chunk_size – [Optional] Chunk size in bytes. Default is 2MB.
  • attributes – [Optional] Attributes to apply to media object.
  • email_spec – [Optional] Spec for email to be sent upon transcode completion.
  • media_id – [Optional] Unique ID of existing media object.
  • timeout – [Optional] Request timeout for each upload chunk in seconds. Default is 30.
  • max_workers – [Optional] Max workers for concurrent requests.

• Returns

  Generator that yields tuple containing progress (0-100) and a response. The response is None until the last yield, when the response is the response object from tator.TatorApi.create_media_list() or tator.TatorApi.transcode().

upload_temporary_file

tator.util.upload_temporary_file(api, project, path, lookup=None, hours=24, name=None, chunk_size=104857600)

Upload a file to the temporary file storage location.

Example:

api = tator.get_api(host, token)
for progress, response in tator.util.upload_temporary_file(api, project_id, path):
    print(f"Upload progress: {progress}%")
print(response.message)

• Parameters

  • api – tator.TatorApi object.
  • project – Unique integer identifying a project.
  • path – Path to the file.
  • lookup – [Optional] md5hash of lookup parameters.
  • hours – [Optional] Number of hourse file is kept alive. Default is 24.
  • name – [Optional] Name of temporary file in database. Defaults to basename of path.
  • chunk_size – [Optional] Chunk size in bytes. Default is 100MB.

• Returns

  Generator that yields tuple containing progress (0-100) and a response. The response is None until the last yield, when the response is the response object from tator.util.TatorApi.create_temporary_file().