AnnotationApi¶

class AnnotationApi[source]¶

Bases: supervisely.api.module_api.ModuleApi

Annotation for a single image. AnnotationApi object is immutable.

Parameters

api : Api: API connection to the server.

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()

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

dataset_id = 254737
ann_infos = api.annotation.get_list(dataset_id)

Methods

`append_labels`	Append labels to image with given ID in API.
`copy`	Copy annotation from one image ID to another image ID in API.
`copy_batch`	Copy annotations from one images IDs to another in API.
`copy_batch_by_ids`	Copy annotations from one images IDs to another images IDs in API.
`download`	Download AnnotationInfo by image ID from API.
`download_batch`	Get list of AnnotationInfos for given dataset ID from API.
`download_json`	Download Annotation in json format by image ID from API.
`download_json_batch`	Get list of AnnotationInfos for given dataset ID from API.
`exists`
`get_free_name`
`get_info_by_id`
`get_info_by_name`
`get_label_by_id`	Returns Supervisely Label object by it's ID.
`get_list`	Get list of information about all annotations for a given dataset.
`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_generator`	Get list of information about all annotations for a given dataset.
`info_sequence`	NamedTuple AnnotationInfo information about Annotation.
`info_tuple_name`	NamedTuple name - AnnotationInfo.
`update_label`	Updates label with given ID in Supervisely with new Label object.
`upload_ann`	Loads an `Annotation` to a given image ID in the API.
`upload_anns`	Loads an `Annotations` to a given images IDs in the API.
`upload_json`	Loads an annotation from dict to a given image ID in the API.
`upload_jsons`	Loads an annotations from dicts to a given images IDs in the API.
`upload_path`	Loads an annotation from a given path to a given image ID in the API.
`upload_paths`	Loads an annotations from a given paths to a given images IDs in the API.

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.AnnotationInfo

append_labels(image_id, labels, skip_bounds_validation=False)[source]¶

Append labels to image with given ID in API.

Parameters

image_id : int: Image ID to append labels.
labels : List[Label]: List of labels to append.

Returns

None

Return type

NoneType

copy(src_image_id, dst_image_id, force_metadata_for_links=True, skip_bounds_validation=False)[source]¶

Copy annotation from one image ID to another image ID in API.

Parameters

src_image_id : int: Image ID in Supervisely.
dst_image_id : int: Image ID in Supervisely.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

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

src_id = 121236918
dst_id = 547837053
api.annotation.copy(src_id, dst_id)

copy_batch(src_image_ids, dst_image_ids, progress_cb=None, force_metadata_for_links=True, skip_bounds_validation=False)[source]¶

Copy annotations from one images IDs to another in API.

Parameters

src_image_ids : List[int]: Images IDs in Supervisely.
dst_image_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_image_ids) != len(dst_image_ids)

Returns

None

Return type

NoneType

Usage example

import supervisely as sly
from tqdm import tqdm

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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"}

copy_batch_by_ids(src_image_ids, dst_image_ids, batch_size=50, save_source_date=True)[source]¶

Copy annotations from one images IDs to another images IDs in API.

Parameters

src_image_ids : List[int]: Images IDs in Supervisely.
dst_image_ids : List[int]: Images IDs in Supervisely.

Returns

None

Return type

NoneType

Raises

RuntimeError if len(src_image_ids) != len(dst_image_ids)

Usage example

import supervisely as sly

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

src_ids = [121236918, 121236919]
dst_ids = [547837053, 547837054]
api.annotation.copy_batch_by_ids(src_ids, dst_ids)

download(image_id, with_custom_data=False, force_metadata_for_links=True)[source]¶

Download AnnotationInfo by image ID from API.

Parameters

image_id : int: Image ID in Supervisely.
with_custom_data : bool, optional

Returns

Information about Annotation. See info_sequence

Return type

AnnotationInfo

Usage example

import supervisely as sly

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

image_id = 121236918
ann_info = api.annotation.download(image_id)
print(json.dumps(ann_info, indent=4))
# Output: [
#     121236918,
#     "IMG_0748.jpeg",
#     {
#         "description": "",
#         "tags": [],
#         "size": {
#             "height": 800,
#             "width": 1067
#         },
#         "objects": []
#     },
#     "2019-12-19T12:06:59.435Z",
#     "2021-02-06T11:07:26.080Z"
# ]

download_batch(dataset_id, image_ids, progress_cb=None, with_custom_data=False, force_metadata_for_links=True)[source]¶

Get list of AnnotationInfos for given dataset ID from API.

Parameters

dataset_id : int: Dataset ID in Supervisely.
image_ids : List[int]: List of integers.
progress_cb : tqdm: Function for tracking download progress.

Returns

Information about Annotations. See info_sequence

Return type

List[AnnotationInfo]

Usage example

import supervisely as sly

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

dataset_id = 254737
image_ids = [121236918, 121236919]
p = tqdm(desc="Annotations downloaded: ", total=len(image_ids))

ann_infos = api.annotation.download_batch(dataset_id, image_ids, progress_cb=p)
# Output:
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Annotations downloaded: ", "current": 0, "total": 2, "timestamp": "2021-03-16T15:20:06.168Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Annotations downloaded: ", "current": 2, "total": 2, "timestamp": "2021-03-16T15:20:06.510Z", "level": "info"}

download_json(image_id, with_custom_data=False, force_metadata_for_links=True)[source]¶

Download Annotation in json format by image ID from API.

Parameters

image_id : int: Image ID in Supervisely.
with_custom_data : bool, optional

Returns

Annotation in json format

Return type

dict

Usage example

import supervisely as sly

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

image_id = 121236918
ann_json = api.annotation.download_json(image_id)
print(ann_json)
# Output: {
#         "description": "",
#         "tags": [],
#         "size": {
#             "height": 800,
#             "width": 1067
#         },
#         "objects": []
#     }

download_json_batch(dataset_id, image_ids, progress_cb=None, force_metadata_for_links=True)[source]¶

Get list of AnnotationInfos for given dataset ID from API.

Parameters

dataset_id : int: Dataset ID in Supervisely.
image_ids : List[int]: List of integers.
progress_cb : tqdm: Function for tracking download progress.

Returns

Information about Annotations. See info_sequence

Return type

List[Dict]

Usage example

import supervisely as sly

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

dataset_id = 254737
image_ids = [121236918, 121236919]
p = tqdm(desc="Annotations downloaded: ", total=len(image_ids))

anns_jsons = api.annotation.download_json_batch(dataset_id, image_ids, progress_cb=p)
# Output:
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Annotations downloaded: ", "current": 0, "total": 2, "timestamp": "2021-03-16T15:20:06.168Z", "level": "info"}
# {"message": "progress", "event_type": "EventType.PROGRESS", "subtask": "Annotations downloaded: ", "current": 2, "total": 2, "timestamp": "2021-03-16T15:20:06.510Z", "level": "info"}

exists(parent_id, name)[source]¶

get_free_name(parent_id, name)[source]¶

get_info_by_id(id)[source]¶

get_info_by_name(parent_id, name)[source]¶

get_label_by_id(label_id, project_meta, with_tags=True)[source]¶

Returns Supervisely Label object by it’s ID.

Parameters

label_id : int: ID of the label to get
project_meta : ProjectMeta: Supervisely ProjectMeta object
with_tags : bool, optional: If True, tags will be added to the Label object

Returns

Supervisely Label object

Return type

Label

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()

label_id = 121236918

project_id = 254737
project_meta = sly.ProjectMeta.from_json(api.project.get_meta(project_id))

label = api.annotation.get_label_by_id(label_id, project_meta)

get_list(dataset_id, filters=None, progress_cb=None, force_metadata_for_links=True)[source]¶

Get list of information about all annotations for a given dataset.

Parameters

dataset_id : int: Dataset ID in Supervisely.
filters : List[dict], optional: List of parameters to sort output Annotations.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

Information about Annotations. See info_sequence

Return type

List[AnnotationInfo]

Usage example

import supervisely as sly

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

dataset_id = 254737
ann_infos = api.annotation.get_list(dataset_id)
print(json.dumps(ann_infos[0], indent=4))
# Output: [
#     121236918,
#     "IMG_0748.jpeg",
#     {
#         "description": "",
#         "tags": [],
#         "size": {
#             "height": 800,
#             "width": 1067
#         },
#         "objects": []
#     },
#     "2019-12-19T12:06:59.435Z",
#     "2021-02-06T11:07:26.080Z"
# ]

ann_infos_filter = api.annotation.get_list(dataset_id, filters={ 'field': 'name', 'operator': '=', 'value': 'IMG_1836' })
print(json.dumps(ann_infos_filter, indent=4))
# Output: [
#     121236919,
#     "IMG_1836",
#     {
#         "description": "",
#         "tags": [],
#         "size": {
#             "height": 800,
#             "width": 1067
#         },
#         "objects": []
#     },
#     "2019-12-19T12:06:59.435Z",
#     "2021-02-06T11:07:26.080Z"
# ]

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

get_list_generator(dataset_id, filters=None, progress_cb=None, batch_size=50, force_metadata_for_links=True)[source]¶

Get list of information about all annotations for a given dataset.

Parameters

dataset_id : int: Dataset ID in Supervisely.
filters : List[dict], optional: List of parameters to sort output Annotations.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

Information about Annotations. See info_sequence

Return type

List[AnnotationInfo]

Usage example

import supervisely as sly

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

dataset_id = 254737
ann_infos = api.annotation.get_list(dataset_id)
print(json.dumps(ann_infos[0], indent=4))
# Output: [
#     121236918,
#     "IMG_0748.jpeg",
#     {
#         "description": "",
#         "tags": [],
#         "size": {
#             "height": 800,
#             "width": 1067
#         },
#         "objects": []
#     },
#     "2019-12-19T12:06:59.435Z",
#     "2021-02-06T11:07:26.080Z"
# ]

ann_infos_filter = api.annotation.get_list(dataset_id, filters={ 'field': 'name', 'operator': '=', 'value': 'IMG_1836' })
print(json.dumps(ann_infos_filter, indent=4))
# Output: [
#     121236919,
#     "IMG_1836",
#     {
#         "description": "",
#         "tags": [],
#         "size": {
#             "height": 800,
#             "width": 1067
#         },
#         "objects": []
#     },
#     "2019-12-19T12:06:59.435Z",
#     "2021-02-06T11:07:26.080Z"
# ]

static info_sequence()[source]¶

NamedTuple AnnotationInfo information about Annotation.

Example

AnnotationInfo(image_id=121236919,
               image_name='IMG_1836',
               annotation={'description': '', 'tags': [], 'size': {'height': 800, 'width': 1067}, 'objects': []},
               created_at='2019-12-19T12:06:59.435Z',
               updated_at='2021-02-06T11:07:26.080Z')

static info_tuple_name()[source]¶: NamedTuple name - AnnotationInfo.

update_label(label_id, label)[source]¶

Updates label with given ID in Supervisely with new Label object. NOTE: This method only updates label’s geometry and tags, not class title, etc.

Parameters

label_id : int: ID of the label to update
label : Label: Supervisely Label 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_label: sly.Label
label_id = 121236918

api.annotation.update_label(label_id, new_label)

Return type

None

upload_ann(img_id, ann, skip_bounds_validation=False)[source]¶

Loads an Annotation to a given image ID in the API.

Parameters

img_id : int: Image ID in Supervisely.
ann : Annotation: Annotation object.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

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

image_id = 121236918
upl_ann = api.annotation.upload_ann(image_id, ann)

upload_anns(img_ids, anns, progress_cb=None, skip_bounds_validation=False)[source]¶

Loads an Annotations to a given images IDs in the API. Images IDs must be from one dataset.

Parameters

img_ids : List[int]: Image ID in Supervisely.
anns : List[Annotation]: List of Annotation objects.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

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

img_ids = [121236918, 121236919]
upl_anns = api.annotation.upload_anns(img_ids, [ann1, ann2])

upload_json(img_id, ann_json, skip_bounds_validation=False)[source]¶

Loads an annotation from dict to a given image ID in the API.

Parameters

img_id : int: Image ID in Supervisely.
ann_json : dict: Annotation in JSON format.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

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

image_id = 121236918
upl_json = api.annotation.upload_json(image_id, ann_json)

upload_jsons(img_ids, ann_jsons, progress_cb=None, skip_bounds_validation=False)[source]¶

Loads an annotations from dicts to a given images IDs in the API. Images IDs must be from one dataset.

Parameters

img_ids : List[int]: Image ID in Supervisely.
ann_jsons : List[dict]: Annotation in JSON format.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

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

img_ids = [121236918, 121236919]
upl_jsons = api.annotation.upload_jsons(img_ids, ann_jsons)

upload_path(img_id, ann_path, skip_bounds_validation=False)[source]¶

Loads an annotation from a given path to a given image ID in the API.

Parameters

img_id : int: Image ID in Supervisely.
ann_path : str: Path to annotation on host.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

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

image_id = 121236918
ann_path = '/home/admin/work/supervisely/example/ann.json'
upl_path = api.annotation.upload_path(image_id, ann_path)

upload_paths(img_ids, ann_paths, progress_cb=None, skip_bounds_validation=False)[source]¶

Loads an annotations from a given paths to a given images IDs in the API. Images IDs must be from one dataset.

Parameters

img_ids : List[int]: Images IDs in Supervisely.
ann_paths : List[str]: Paths to annotations on local machine.
progress_cb : tqdm or callable, optional: Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

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

img_ids = [121236918, 121236919]
ann_pathes = ['/home/admin/work/supervisely/example/ann1.json', '/home/admin/work/supervisely/example/ann2.json']
upl_paths = api.annotation.upload_paths(img_ids, ann_pathes)