VideoAnnotationAPI¶

class VideoAnnotationAPI(api)[source]¶

Bases: EntityAnnotationAPI

API for working with video annotations.

Parameters:

api¶

Api object to use for API connection.

Usage Example:

import supervisely as sly
api = sly.Api.from_env()
ann_info = api.video.annotation.download(video_id)

Methods

append	Loads an VideoAnnotation to a given video ID in the API.
convert_info_to_json	Convert information about an entity to a dictionary.
copy_batch	Copy annotations from one images IDs to another in API.
download	Download information about VideoAnnotation by video ID from API.
download_async	Download information about VideoAnnotation by video ID from API asynchronously.
download_bulk	Download a list of content (annotations with given ids from dataset with given id).
download_bulk_async	Download information about VideoAnnotation in bulk by video IDs from API asynchronously.
exists	Checks if an entity with the given parent_id and name exists
get_free_name	Generates a free name for an entity with the given parent_id and name.
get_info_by_id	Get information about an entity by its ID from the Supervisely server.
get_info_by_name	Get information about an entity by its name from the Supervisely server.
get_list	Get list of entities in parent entity with given parent ID.
get_list_all_pages	Get list of all or limited quantity entities from the Supervisely server.
get_list_all_pages_generator	This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved
get_list_idx_page_async	Get the list of items for a given page number.
get_list_page_generator_async	Yields list of images in dataset asynchronously page by page.
info_sequence	Get list of all class field names.
info_tuple_name	Get string name of NamedTuple.
upload_anns_multiview	Upload already constructed VideoAnnotation objects for multi-view video project.
upload_paths	Loads an VideoAnnotations from a given paths to a given videos IDs in the API.
upload_paths_multiview	Upload VideoAnnotations for multi-view video project.

Attributes

MAX_WAIT_ATTEMPTS	Maximum number of attempts that will be made to wait for a certain condition to be met.
WAIT_ATTEMPT_TIMEOUT_SEC	Number of seconds for intervals between attempts.

classmethod convert_info_to_json(info)¶

Convert information about an entity to a dictionary.

Parameters:

info : NamedTuple¶

Information about the entity.

Returns:

Dictionary with information about the entity.

Return type:

dict

static info_sequence()¶

Get list of all class field names.

static info_tuple_name()¶

Get string name of NamedTuple.

append(video_id, ann, key_id_map=None, progress_cb=None)[source]¶

Loads an VideoAnnotation to a given video ID in the API.

Parameters:

video_id : int¶

Video ID in Supervisely.

ann¶

VideoAnnotation object.

key_id_map=None¶

KeyIdMap object.

progress : Optional[Union[tqdm, Callable]]

Progress.

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198704259
api.video.annotation.append(video_id, video_ann)

copy_batch(src_video_ids, dst_video_ids, progress_cb=None)[source]¶

Copy annotations from one images IDs to another in API.

Parameters:

src_video_ids : List[int]¶

Images IDs in Supervisely.

dst_video_ids : List[int]¶

Unique IDs of images in API.

progress_cb : tqdm or callable, optional¶

Function for tracking download progress.

:raises RuntimeError, if len(src_video_ids) != len(dst_video_ids) :returns: None :rtype: None

Usage Example:

import os
from tqdm import tqdm
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

src_ids = [121236918, 121236919]
dst_ids = [547837053, 547837054]
p = tqdm(desc="Annotations copy: ", total=len(src_ids))

copy_anns = api.annotation.copy_batch(src_ids, dst_ids, progress_cb=p)
# Output:
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Annotations copy: ", "current": 0, "total": 2, "timestamp": "2021-03-16T15:24:31.286Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Annotations copy: ", "current": 2, "total": 2, "timestamp": "2021-03-16T15:24:31.288Z", "level": "info"}

download(video_id)[source]¶

Download information about VideoAnnotation by video ID from API.

Parameters:

video_id : int¶

Video ID in Supervisely.

Returns:

Information about VideoAnnotation in json format

Return type:

dict

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198702499
ann_info = api.video.annotation.download(video_id)
print(ann_info)
# Output: {
#     "videoId": 198702499,
#     "videoName": "Videos_dataset_cars_cars.mp4",
#     "createdAt": "2021-03-23T13:14:25.536Z",
#     "updatedAt": "2021-03-23T13:16:43.300Z",
#     "description": "",
#     "tags": [],
#     "objects": [],
#     "size": {
#         "height": 2160,
#         "width": 3840
#     },
#     "framesCount": 326,
#     "frames": []
# }

async download_async(video_id, video_info=None, semaphore=None, force_metadata_for_links=True, integer_coords=True, progress_cb=None)[source]¶

Download information about VideoAnnotation by video ID from API asynchronously.

Parameters:

video_id : int¶

Video ID in Supervisely.

video_info=None¶

Does not affect the result, but is left for compatibility with the method signature.

semaphore : asyncio.Semaphore, optional¶

Semaphore to limit the number of parallel downloads.

force_metadata_for_links : bool, optional¶

If True, updates meta for videos with links.

integer_coords : bool, optional¶

If True, returns coordinates as integers for objects. If False, returns as floats.

progress_cb : Union[tqdm, Callable], optional¶

Progress callback to track download progress.

Returns:

Information about VideoAnnotation in json format

Return type:

dict

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_id = 198702499
loop = sly.utils.get_or_create_event_loop()
ann_info = loop.run_until_complete(api.video.annotation.download_async(video_id))

download_bulk(dataset_id, entity_ids)¶

Download a list of content (annotations with given ids from dataset with given id).

Parameters:

dataset_id¶

int

entity_ids¶

list of integers

Returns:

list of content(annotations with given ids from dataset with given id), received after execution post request

async download_bulk_async(video_ids, semaphore=None, force_metadata_for_links=True, integer_coords=True, batch_size=10, progress_cb=None)[source]¶

Download information about VideoAnnotation in bulk by video IDs from API asynchronously.

Parameters:

video_ids : int¶

List of Video IDs in Supervisely. All videos must be from the same dataset.

semaphore : asyncio.Semaphore, optional¶

Semaphore to limit the number of parallel downloads.

force_metadata_for_links : bool, optional¶

If True, updates meta for videos with links.

integer_coords : bool, optional¶

If True, returns coordinates as integers for objects. If False, returns as floats.

batch_size : int, optional¶

Batch size for parallel downloads. Default is 10 as an optimal value.

progress_cb : tqdm or callable, optional¶

Function for tracking download progress.

Returns:

Information about VideoAnnotations in json format

Return type:

list

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_ids = [198702499, 198702500, 198702501]
loop = sly.utils.get_or_create_event_loop()
ann_infos = loop.run_until_complete(api.video.annotation.download_bulk_async(video_ids))

exists(parent_id, name)¶

Checks if an entity with the given parent_id and name exists

Parameters:

parent_id : int¶

ID of the parent entity.

name : str¶

Name of the entity.

Returns:

Returns True if entity exists, and False if not

Return type:

bool

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
exists = api.image.exists(dataset_id, name)
print(exists) # True

get_free_name(parent_id, name)¶

Generates a free name for an entity with the given parent_id and name. Adds an increasing suffix to original name until a unique name is found.

Parameters:

parent_id : int¶

ID of the parent entity.

name : str¶

Name of the entity.

Returns:

Returns free name.

Return type:

str

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

name = "IMG_0315.jpeg"
dataset_id = 55832
free_name = api.image.get_free_name(dataset_id, name)
print(free_name) # IMG_0315_001.jpeg

get_info_by_id(id)¶

Get information about an entity by its ID from the Supervisely server.

Parameters:

id : int¶

ID of the entity.

get_info_by_name(parent_id, name, fields=[])¶

Get information about an entity by its name from the Supervisely server.

Parameters:

parent_id : int¶

ID of the parent entity.

name : str¶

Name of the entity for which the information is being retrieved.

fields : List[str]¶

The list of api fields which will be returned with the response.

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55832
name = "IMG_0315.jpeg"
info = api.image.get_info_by_name(dataset_id, name)
print(info)
# Output: ImageInfo(id=19369643, name='IMG_0315.jpeg', ...)

get_list(parent_id, filters=None)¶

Get list of entities in parent entity with given parent ID.

Parameters:

parent_id : int¶

parent ID in Supervisely.

filters : List[Dict[str, str]], optional¶

List of parameters to sort output entities.

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 55832
images = api.image.get_list(dataset_id)
print(images)
# Output: [
    ImageInfo(id=19369642, ...)
    ImageInfo(id=19369643, ...)
    ImageInfo(id=19369644, ...)
]

get_list_all_pages(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

Get list of all or limited quantity entities from the Supervisely server.

Parameters:

method : str¶

Request method name

data : dict¶

Dictionary with request body info

progress_cb : Progress, optional¶

Function for tracking download progress.

convert_json_info_cb : Callable, optional¶

Function for convert json info

limit : int, optional¶

Number of entity to retrieve

return_first_response : bool, optional¶

Specify if return first response

Returns:

List of entities.

Return type:

List[dict]

get_list_all_pages_generator(method, data, progress_cb=None, convert_json_info_cb=None, limit=None, return_first_response=False)¶

This generator function retrieves a list of all or a limited quantity of entities from the Supervisely server, yielding batches of entities as they are retrieved

Parameters:

method : str¶

Request method name

data : dict¶

Dictionary with request body info

progress_cb : Progress, optional¶

Function for tracking download progress.

convert_json_info_cb : Callable, optional¶

Function for convert json info

limit : int, optional¶

Number of entity to retrieve

return_first_response : bool, optional¶

Specify if return first response

async get_list_idx_page_async(method, data)¶

Get the list of items for a given page number. Page number is specified in the data dictionary.

Parameters:

method : str¶

Method to call for listing items.

data : dict¶

Data to pass to the API method.

Returns:

List of items.

Return type:

Tuple[int, List[NamedTuple]]

async get_list_page_generator_async(method, data, pages_count=None, semaphore=None)¶

Yields list of images in dataset asynchronously page by page.

Parameters:

method : str¶

Method to call for listing items.

data : dict¶

Data to pass to the API method.

pages_count : int, optional¶

Preferred number of pages to retrieve if used with a per_page limit. Will be automatically adjusted if the pagesCount differs from the requested number.

semaphore=None¶

Semaphore for limiting the number of simultaneous requests.

Returns:

List of images in dataset.

Return type:

AsyncGenerator[List[ImageInfo]]

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

method = 'images.list'
data = {'datasetId': 123456}

loop = sly.utils.get_or_create_event_loop()
images = loop.run_until_complete(api.image.get_list_generator_async(method, data))

upload_anns_multiview(video_ids, anns, progress_cb=None, key_id_map=None)[source]¶

Upload already constructed VideoAnnotation objects for multi-view video project. All provided video ids must belong to the same project and dataset.

Objects with the same key are created only once and shared between videos. In this mode annotation objects are created without binding to a specific entityId.

Parameters:

video_ids : List[int]¶

Video IDs in Supervisely.

anns : List[VideoAnnotation]¶

List of VideoAnnotation objects corresponding to the video_ids.

progress_cb : tqdm or callable, optional¶

Function for tracking upload progress (by number of figures).

key_id_map=None¶

KeyIdMap object.

Returns:

None

Return type:

None

upload_paths(video_ids, ann_paths, project_meta, progress_cb=None)[source]¶

Loads an VideoAnnotations from a given paths to a given videos IDs in the API. Videos IDs must be from one dataset.

Parameters:

video_ids : List[int]¶

Videos IDs in Supervisely.

ann_paths : List[str]¶

Paths to annotations on local machine.

project_meta¶

Input ProjectMeta for VideoAnnotations.

progress_cb : tqdm or callable, optional¶

Function for tracking download progress.

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

# Load secrets and create API object from .env file (recommended)
# Learn more here: https://developer.supervisely.com/getting-started/basics-of-authentication
if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

video_ids = [121236918, 121236919]
ann_paths = ['/home/admin/work/supervisely/example/ann1.json', '/home/admin/work/supervisely/example/ann2.json']
api.video.annotation.upload_paths(video_ids, ann_paths, meta)

upload_paths_multiview(video_ids, ann_paths, project_meta, progress_cb=None)[source]¶

Upload VideoAnnotations for multi-view video project. All provided video ids must belong to the same project and dataset.

Objects with the same key are created only once and shared between videos. In this mode annotation objects are created without binding to a specific entityId.

Parameters:

video_ids : List[int]¶

Video IDs in Supervisely.

ann_paths : List[str]¶

Paths to annotations on local machine.

project_meta¶

Input ProjectMeta for VideoAnnotations.

progress_cb : tqdm or callable, optional¶

Function for tracking upload progress.

Returns:

None

Return type:

None