API Details¶

Initialization Objects¶

class pytator.Tator(url, token, project)[source]¶

Top-level module for access Tator API endpoints

baseURL()[source]¶: Returns the URL for accessing site content

whoami()[source]¶: Returns current user

class pytator.Auth[source]¶

Configuration Objects¶

pytator.tator.cli_parser(parser=None)[source]¶

Convenience function to return an argument parser with boiler-plate required arguments for initializing a pytator.Tator

Parameters:	parser (argparse.ArgumentParser) – A constructed parser (or None)

Endpoint Manipulation Objects¶

Each type of API endpoint (media, localization, state) is exposed as a unique API object.

API Implementation Module

The implementation of each endpoint type is in this module. Each type derives off of APIElement, which provides basic functions such as APIElement.get() and APIElement.new().

Some endpoints classes have additional methods that are specific to it, such as Media which provides Media.uploadFile and Media.downloadFile

These endpoints do not need to be manually constructed and instead can be accessed via pytator.Tator.

class pytator.api.APIElement(api, list_endpoint, detail_endpoint)[source]¶

Bases: object

Base API element that provides generic capability to any of the: derived endpoint objects. Each Element is instantiated per project so concepts of all refer to all within a project.

Parameters:	api – Tuple provided from `pytator.Tator` object construction, represents the Tator webservice endpoint, authorization token, and project number. endpoint (str) – Name of the endpoint provided from derived class.

all()[source]¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)[source]¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)[source]¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)[source]¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)[source]¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)[source]¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)[source]¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)[source]¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)[source]¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)[source]¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)[source]¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)[source]¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.Algorithm(api)[source]¶

Bases: pytator.api.APIElement

Endpoint for launching Algorithm pipelines on media elements rest/Algorithms endpoint.

all()[source]¶: Warning

Not supported for algorithms endpoint

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)[source]¶: Warning

Not supported for algorithms endpoint

get(pk)[source]¶: Warning

Not supported for algorithm endpoint

getMany(endpoint, params)[source]¶: Warning

Not supported for algorithms endpoint

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

launch_on_media(algorithm_name, media_id)[source]¶

Launch a given algorithm on an individual media

Parameters:	algorithm_name (str) – Name of the algorithm media_id (int) – id of the media to launch algorithm on

launch_on_medias(algorithm_name, media_ids)[source]¶

Launch a given algorithm on an individual media

Parameters:	algorithm_name (str) – Name of the algorithm media_ids (list) – list of ids of the media to launch algorithm on

new(obj)[source]¶: Warning

Not supported for algorithm endpoint

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)[source]¶: Warning

Not supported for algorithms endpoint

class pytator.api.GetFrame(api)[source]¶

Bases: object

Interface for fetching frames from media server

get_bgr(media_element_or_id, frames, roi=None)[source]¶

Return a list of np.arrays representing bgr data for each requested frame

media_element_or_id : dict or int: Represents the media to fetch (either a dict with ‘id’ or just the integer itself)
frames : list: Represents the frames to fetch
roi : tuple: Represents the (w,h,x,y) of a bounding box (applies to all frames in a multi-frame request).

get_encoded_img(media_element_or_id, frames, roi=None, tile=None, animate=None)[source]¶

Return an encoded image (jpg,gif) from the media server

media_element_or_id : dict or int: Represents the media to fetch (either a dict with ‘id’ or just the integer itself)
frames : list: Represents the frames to fetch
roi : tuple or list of tuples: Represents the (w,h,x,y) of a bounding box (applies to all frames in a multi-frame request).
tile : tuple: Represents the (w,h) of the tile arrangement of frames. If w*h is less than the len(frames), the server ignores the requested size.
animate : int: Represents fps of the requested animation

class pytator.api.Localization(api)[source]¶

Bases: pytator.api.APIElement

Object to deal with Localizations in database rest/Localizations

Localizations are boxes, lines, or dots made by annotators on images or videos.

add(mediaId, typeId, attrs)[source]¶: Add a new localization to a media element.

Deprecated since version 0.0.2: Use APIElement.new() instead

addMany(listObj)[source]¶

Add many localizations to a media element.

This is a shortcut function that allows to the bulk ingestion of many annotations on a media element, without there having to be a request for each box, line or dot. Each element of the list needs to match the syntax for APIElement.new() for a localization

Deprecated since version 0.0.15.

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

query(params)[source]¶: Queries for a list of localizations.

Deprecated since version 0.0.2: Use APIElement.filter() instead.

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.LocalizationType(api)[source]¶

Bases: pytator.api.APIElement

Class to support operations to rest/LocalizationTypes

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.Media(api)[source]¶

Bases: pytator.api.APIElement

Defines interactions to Media elements at /rest/Medias

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

applyAttribute(media_id, attributes)[source]¶: Returns a media element with a matching md5

Deprecated since version 0.0.2: Use APIElement.patch() instead

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

byId(pk)[source]¶: Returns a media element with a given id

Deprecated since version 0.0.2: Use APIElement.get() instead

byMd5(md5)[source]¶: Returns a media element with a matching md5

Deprecated since version 0.0.2: Use APIElement.filter() instead

byName(name)[source]¶: Returns a media element with a matching name

Deprecated since version 0.0.2: Use APIElement.filter() instead

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

downloadFile_v2(element, out_path)[source]¶

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

TODO: Support which file to download

Parameters:	element (dict) – Dictionary from `Media.filter()` out_path (path-like) – Path to where to download

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

uploadFile(typeId, filePath, waitForTranscode=True, progressBars=True, md5=None, section=None, fname=None)[source]¶: Upload a new file to Tator

class pytator.api.MediaSection(api)[source]¶

Bases: pytator.api.APIElement

Describes elements from rest/MediaSections

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.MediaType(api)[source]¶

Bases: pytator.api.APIElement

Describes elements from rest/MediaTypes

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.Membership(api)[source]¶

Bases: pytator.api.APIElement

Describes elements from rest/Memberships

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.Project(api)[source]¶

Bases: pytator.api.APIElement

Describes elements from rest/Projects

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.State(api)[source]¶

Bases: pytator.api.APIElement

Class to support operations to rest/States

add(typeId, medias, attrs, localizations=[], version=None)[source]¶: Adds a new state element

Deprecated since version 0.0.2: Use APIElement.new() instead

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

byAttr(key, value)[source]¶: Returns a state element with a matching name

Deprecated since version 0.0.2: Use APIElement.filter() instead

dataframe(params)[source]¶: State objects are nested, this function will flatten them prior to conversion to a dataframe. Otherwise the same as the parent function

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.StateGraphic(api)[source]¶

Bases: object

Interface for fetching frames from media server

get_bgr(state_element_or_id, **kwargs)[source]¶

Return a list of np.arrays representing bgr data for each requested frame

state_element_or_id : dict or int: Represents the media to fetch (either a dict with ‘id’ or just the integer itself)
kwargs : Maps to argument of StateGraphic endpoint.: mode : [tile, animate], default = tile forceScale : WxH default = None

get_encoded_img(state_element_or_id, mode='tile', forceScale=None)[source]¶

Return an encoded image (jpg,gif) from the media server

media_element_or_id : dict or int: Represents the media to fetch (either a dict with ‘id’ or just the integer itself)

class pytator.api.StateType(api)[source]¶

Bases: pytator.api.APIElement

Class to support operations to rest/StateTypes

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

byTypeId(typeId)[source]¶: Returns a state type element with a matching type id

Deprecated since version 0.0.2: Use APIElement.get() instead

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.TemporaryFile(api)[source]¶

Bases: pytator.api.APIElement

Defines interactions to Media elements at /rest/TemporaryFiles

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

downloadFile(element, out_path)[source]¶

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

Parameters:	element (dict) – Dictionary from `TemporaryFile.filter()` out_path (path-like) – Path to where to download

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

uploadFile(filePath, lookup=None, hours=24, name=None)[source]¶: Upload a file to the temporary file storage location

class pytator.api.Track(api)[source]¶

Bases: pytator.api.State

Object that deals with State objects that relate to Localizations.

These types of objects are referred to as tracks. One example is tracking an object across multiple frames of a video.

add(typeId, medias, attrs, localizations=[], version=None)¶: Adds a new state element

Deprecated since version 0.0.2: Use APIElement.new() instead

addLocalizations(trackObj, localizations)[source]¶: Given a track state object, associate it with a list of localizations :param dict trackObj: Track object returned from API :param iterable localizations: List or set of localization ids.

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

byAttr(key, value)¶: Returns a state element with a matching name

Deprecated since version 0.0.2: Use APIElement.filter() instead

dataframe(params)¶: State objects are nested, this function will flatten them prior to conversion to a dataframe. Otherwise the same as the parent function

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.TreeLeaf(api)[source]¶

Bases: pytator.api.APIElement

Interfaces to tree leaf elements. rest/TreeLeaves

Treeleaves are used to support aribitrary leveled data types and can be used to drive autocomplete/typeahead suggestions. An example use of a TreeLeaf tree is a taxonomic structure.

addIfNotPresent(name, parent, typeid, attr=None)[source]¶

Add a tree leaf if not already present

Parameters:	name (str) – The name of the element parent (str) – The name of the parent typeid (int) – The type id of the tree leaf attr (dict) – Attributes to apply to the element upon creation

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

isPresent(name)[source]¶: Acquire a tree leaf element by its name

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

tree(ancestor)[source]¶: Acquire a tree listing by an ancestor

Deprecated since version 0.0.2: Use APIElement.filter() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.TreeLeafType(api)[source]¶

Bases: pytator.api.APIElement

Interface to tree leaf type elements. rest/TreeLeafTypes

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.User(api)[source]¶

Bases: pytator.api.APIElement

Describes elements from rest/Users

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

class pytator.api.Version(api)[source]¶

Bases: pytator.api.APIElement

Describes elements from rest/Versions

all()¶

Get list of all the elements of an endpoint as a list

Returns:	None if there are no elements, else a list

bulk_delete(params)¶

Given a filter object, delete the matching elements.

Parameters:	params – Query parameters for the objects to be deleted.
Returns:	A tuple containing the status code and JSON response from server

bulk_update(params, patch)¶

Given a filter and patch object, update the matching elements.

Parameters:	params – Query parameters for the objects to be updated. patch – Object attributes to apply.
Returns:	A tuple containing the status code and JSON response from server

dataframe(params)¶

Given a filter object, return the matching elements as a pd.DataFrame or None.

This function is equivilant to the following:

allObjects=self.filter(params)
if allObjects:
    return pd.DataFrame(data=allObjects,
                     columns=allObjects[0].keys())
else:
    return None

delete(pk)¶

Delete an individual object from the database.

Parameters:	pk (int) – The id of the object to delete
Returns:	A status code from server

filter(params)¶

Given a filter object, return the matching elements (or None)

Filtering may require knowledge of the underlying user-defined type. See rest/EntityTypeSchema.

get(pk)¶

Acquire an individual item from the database.

Parameters:	pk (int) – The id of the object to acquire
Returns:	A python dictionary representing the object

getMany(endpoint, params)¶: Returns a list of elements at a given endpoint.

Deprecated since version 0.0.2: Do not call this function directly, use APIElement.filter() or APIElement.all() instead

getSingleElement(endpoint, params)¶: Shortcut method to get the first element from a list

Deprecated since version 0.0.2: Use APIElement.filter() instead

new(obj)¶

Add a new object to the database.

To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	obj (dict) – The object to add to the database.

newSingleElement(endpoint, obj)¶: Adds a new element to an arbitrary endpoint

Deprecated since version 0.0.2: Use APIElement.new() instead

update(pk, patch)¶

Update an element. To understand what fields apply to a given object type, rest/EntityTypeSchema/<type id> can be used.

Parameters:	pk (int) – ID of element to update patch (dict) – Object delta to apply
Returns:	A tuple of the status code and JSON response from server

User-defined types¶

The various endpoints each support filtering via the APIElement.filter() function. The params object is often type specific; and maps to the REST endpoints documented at Tator REST API Details.

When dealing with a user-defined type it is useful to inspect the attribute_types field of the MediaType, LocalizationType, StateType, or LeafType endpoints, to determine required fields for a .new() or .patch() operation.

Searching for media¶

To search for media, the Medias endpoint accepts lucene style searches using the search parameter. An example usage of this is:

results = tator.Media.filter({"search": "<LUCENE QUERY HERE">})

API Details¶

Initialization Objects¶

Configuration Objects¶

Endpoint Manipulation Objects¶

User-defined types¶

Searching for media¶

By location queries¶