VideoFigureApi¶

class VideoFigureApi[source]¶

Bases: supervisely.api.entity_annotation.figure_api.FigureApi

VideoFigure for a single video.

Methods

`append_bulk`	Add VideoFigures to given Video by ID.
`convert_info_to_json`	_convert_info_to_json
`create`	Create new VideoFigure for given frame in given video ID.
`create_bulk`	Create figures in Supervisely in bulk.
`download`	Method returns a dictionary with pairs of video ID and list of FigureInfo for the given dataset ID.
`download_geometries_batch`	Download figure geometries with given IDs from storage.
`download_geometries_batch_async`	Download figure geometries with given IDs from storage asynchronously.
`download_geometry`	Download figure geometry with given ID from storage.
`exists`	Checks if an entity with the given parent_id and name exists
`get_by_ids`	Get Figures information by IDs from given dataset ID.
`get_free_name`	Generates a free name for an entity with the given parent_id and name.
`get_info_by_id`	Get Figure information by ID.
`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`	NamedTuple FigureInfo information about Figure.
`info_tuple_name`	Get string name of NamedTuple for class.
`remove`	Remove an entity with the specified ID from the Supervisely server.
`remove_batch`	Remove entities in batches from the Supervisely server.
`update`	Updates figure feometry with given ID in Supervisely with new Geometry object.
`upload_geometries_batch`	Upload figure geometries with given figure IDs to storage.
`upload_geometry`	Upload figure geometry with given figure ID to storage.

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.

InfoType¶: alias of supervisely.api.module_api.FigureInfo

append_bulk(video_id, figures, key_id_map)[source]¶

Add VideoFigures to given Video by ID.

Parameters

video_id : int: Video ID in Supervisely.
figures : List[VideoFigure]: List of VideoFigures to append.
key_id_map : KeyIdMap: KeyIdMap object.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

project_id = 124976
meta_json = api.project.get_meta(project_id)
meta = sly.ProjectMeta.from_json(meta_json)
key_id_map = KeyIdMap()

video_id = 198703212
ann_info = api.video.annotation.download(video_id)
ann = sly.VideoAnnotation.from_json(ann_info, meta, key_id_map)
figures = ann.figures[:5]
api.video.figure.append_bulk(video_id, figures, key_id_map)

classmethod convert_info_to_json(info)¶

_convert_info_to_json

Return type: Dict

create(video_id, object_id, frame_index, geometry_json, geometry_type, track_id=None, meta=None)[source]¶

Create new VideoFigure for given frame in given video ID.

Parameters

video_id : int: Video ID in Supervisely.
object_id : int: ID of the object to which the VideoFigure belongs.
frame_index : int: Number of the frame to add VideoFigure.
geometry_json : dict: Parameters of geometry for VideoFigure.
geometry_type : str: Type of VideoFigure geometry.
track_id : int, optional: int, optional.

Returns

New figure ID

Return type

int

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

video_id = 198703211
object_id = 152118
frame_idx = 0
geometry_json = {'points': {'exterior': [[500, 500], [1555, 1500]], 'interior': []}}
geometry_type = 'rectangle'

figure_id = api.video.figure.create(video_id, object_id, frame_idx, geometry_json, geometry_type) # 643182610

create_bulk(figures_json, entity_id=None, dataset_id=None, batch_size=200)¶

Create figures in Supervisely in bulk. To optimize creation of a large number of figures use dataset ID instead of entity ID. In this case figure jsons list can contain figures from different entities for the same dataset. Every figure json must contain corresponding entity ID.

NOTE: Geometries for AlphaMask must be uploaded separately via upload_geometries_batch method.

Parameters

figures_json : List[dict]: List of figures in Supervisely JSON format.
entity_id : int: Entity ID.
dataset_id : int: Dataset ID.

Return type

List[int]

Returns

List of figure IDs.

download(dataset_id, video_ids=None, skip_geometry=False, **kwargs)[source]¶

Method returns a dictionary with pairs of video ID and list of FigureInfo for the given dataset ID. Can be filtered by video IDs.

Parameters

dataset_id : int: Dataset ID in Supervisely.
video_ids : List[int], optional: Specify the list of video IDs within the given dataset ID. If video_ids is None, the method returns all possible pairs of images with figures. Note: Consider using sly.batched() to ensure that no figures are lost in the response.
skip_geometry : bool: Skip the download of figure geometry. May be useful for a significant api request speed increase in the large datasets.

Returns

A dictionary where keys are video IDs and values are lists of figures.

Return type

class: Dict[int, List[FigureInfo]]

download_geometries_batch(ids, progress_cb=None)¶

Download figure geometries with given IDs from storage.

Parameters

ids : List[int]: List of figure IDs in Supervisely.
progress_cb : Union[tqdm, Callable], optional: Progress bar to show the download progress. Shows the number of bytes downloaded.

Returns

List of figure geometries in Supervisely JSON format.

Return type

List[dict]

async download_geometries_batch_async(ids, progress_cb=None, semaphore=None)¶

Download figure geometries with given IDs from storage asynchronously.

Parameters

ids : List[int]: List of figure IDs in Supervisely.
progress_cb : Union[tqdm, Callable], optional: Progress bar to show the download progress. Shows the number of bytes downloaded.
semaphore : Optional[asyncio.Semaphore], optional: Semaphore to limit the number of concurrent downloads.

Returns

List of figure geometries in Supervisely JSON format.

Return type

List[dict]

Usage example

import asyncio
import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

figure_ids = [642155547, 642155548, 642155549]
loop = sly.utils.get_or_create_event_loop()
geometries = loop.run_until_complete(
    api.figure.download_geometries_batch_async(
        figure_ids,
        progress_cb=tqdm(total=len(figure_ids), desc="Downloading geometries"),
        semaphore=asyncio.Semaphore(15),
    )
)

download_geometry(figure_id)¶

Download figure geometry with given ID from storage.

Parameters

figure_id : int: Figure ID in Supervisely.

Returns

Figure geometry in Supervisely JSON format.

Return type

dict

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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


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

get_by_ids(dataset_id, ids)¶

Get Figures information by IDs from given dataset ID.

Parameters

dataset_id : int: Dataset ID in Supervisely.
ids : List[int]: List of Figures IDs.

Returns

List of information about Figures. See info_sequence

Return type

List[NamedTuple]

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

dataset_id = 466642
figures_ids = [642155547, 642155548, 642155549]
figures_infos = api.video.figure.get_by_ids(dataset_id, figures_ids)
print(figures_infos)
# Output: [
#     [
#         642155547,
#         "2021-03-23T13:25:34.705Z",
#         "2021-03-23T13:25:34.705Z",
#         198703211,
#         152118,
#         124976,
#         466642,
#         0,
#         "rectangle",
#         {
#             "points": {
#                 "exterior": [
#                     [
#                         2240,
#                         1041
#                     ],
#                     [
#                         2463,
#                         1187
#                     ]
#                 ],
#                 "interior": []
#             }
#         }
#     ],
#     [
#         642155548,
#         "2021-03-23T13:25:34.705Z",
#         "2021-03-23T13:25:34.705Z",
#         198703211,
#         152118,
#         124976,
#         466642,
#         1,
#         "rectangle",
#         {
#             "points": {
#                 "exterior": [
#                     [
#                         2248,
#                         1048
#                     ],
#                     [
#                         2455,
#                         1176
#                     ]
#                 ],
#                 "interior": []
#             }
#         }
#     ],
#     [
#         642155549,
#         "2021-03-23T13:25:34.705Z",
#         "2021-03-23T13:25:34.705Z",
#         198703211,
#         152118,
#         124976,
#         466642,
#         2,
#         "rectangle",
#         {
#             "points": {
#                 "exterior": [
#                     [
#                         2237,
#                         1046
#                     ],
#                     [
#                         2464,
#                         1179
#                     ]
#                 ],
#                 "interior": []
#             }
#         }
#     ]
# ]

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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 Figure information by ID.

Parameters

id : int: Figure ID in Supervisely.

Returns

Information about Figure. See info_sequence

Return type

NamedTuple

Usage example

import supervisely as sly

figure_id = 588801373

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

figure_info = api.video.figure.get_info_by_id(figure_id)
print(figure_info)
# Output: [
#     588801373,
#     "2020-12-22T06:37:13.183Z",
#     "2020-12-22T06:37:13.183Z",
#     186648101,
#     112482,
#     110366,
#     419886,
#     0,
#     "bitmap",
#     {
#         "bitmap": {
#             "data": "eJw...Cgj4=",
#             "origin": [
#                 335,
#                 205
#             ]
#         }
#     }
# ]

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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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

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 : asyncio.Semaphore, optional: Semaphore for limiting the number of simultaneous requests.
kwargs: Additional arguments.

Returns

List of images in dataset.

Return type

AsyncGenerator[List[ImageInfo]]

Usage example

import supervisely as sly
import asyncio

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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))

static info_sequence()¶

NamedTuple FigureInfo information about Figure.

Example

FigureInfo(id=588801373,
           updated_at='2020-12-22T06:37:13.183Z',
           created_at='2020-12-22T06:37:13.183Z',
           entity_id=186648101,
           object_id=112482,
           project_id=110366,
           dataset_id=419886,
           frame_index=0,
           geometry_type='bitmap',
           geometry={'bitmap': {'data': 'eJwdlns8...Cgj4=', 'origin': [335, 205]}})

static info_tuple_name()¶

Get string name of NamedTuple for class.

Returns

NamedTuple name.

Return type

str

Usage example

import supervisely as sly

os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

tuple_name = api.video.figure.info_tuple_name()
print(tuple_name) # FigureInfo

remove(id)¶

Remove an entity with the specified ID from the Supervisely server.

Parameters

id : int: Entity ID in Supervisely.

Usage example

import supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


image_id = 19369643
api.image.remove(image_id)

remove_batch(ids, progress_cb=None, batch_size=50)¶

Remove entities in batches from the Supervisely server. All entity IDs must belong to the same nesting (for example team, or workspace, or project, or dataset). Therefore, it is necessary to sort IDs before calling this method.

Parameters

ids : List[int]: IDs of entities in Supervisely.
progress_cb : Callable: Function for control remove progress.

Usage example

import supervisely as sly

# You can connect to API directly
address = 'https://app.supervise.ly/'
token = 'Your Supervisely API Token'
api = sly.Api(address, token)

# Or you can use API from environment
os.environ['SERVER_ADDRESS'] = 'https://app.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()


image_ids = [19369645, 19369646, 19369647]
api.image.remove_batch(image_ids)

update(figure_id, geometry)[source]¶

Updates figure feometry with given ID in Supervisely with new Geometry object.

Parameters

figure_id : int: ID of the figure to update
geometry : Geometry: Supervisely Gepmetry object

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
load_dotenv(os.path.expanduser("~/supervisely.env"))
api = sly.Api.from_env()

new_geometry: sly.Rectangle(10, 10, 100, 100)
figure_id = 121236918

api.video.figure.update(figure_id, new_geometry)

Return type

None

upload_geometries_batch(figure_ids, geometries)¶

Upload figure geometries with given figure IDs to storage.

Parameters

figure_ids : List[int]: List of figure IDs in Supervisely.
geometries : List[dict]: List of figure geometries in Supervisely JSON format.

Returns

None

Return type

None

upload_geometry(figure_id, geometry)¶

Upload figure geometry with given figure ID to storage.

Parameters

figure_id : int: Figure ID in Supervisely.
geometry : dict: Figure geometry in Supervisely JSON format.

Returns

None

Return type

None