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.supervisely.com'
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.supervisely.com'
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.supervisely.com'
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.supervisely.com'
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.supervisely.com'
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"}

Optimizing the download process by using the context to avoid redundant API calls.:
# 1. Download the project meta
project_id = api.dataset.get_info_by_id(dataset_id).project_id
project_meta = api.project.get_meta(project_id)

# 2. Use the context to avoid redundant API calls
dataset_id = 254737
image_ids = [121236918, 121236919]
with sly.ApiContext(api, dataset_id=dataset_id, project_id=project_id, project_meta=project_meta):
    ann_infos = api.annotation.download_batch(dataset_id, image_ids)
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.supervisely.com'
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.supervisely.com'
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.supervisely.com'
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.supervisely.com'
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.supervisely.com'
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.supervisely.com'
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])

# Optimizing the upload process by using the context to avoid redundant API calls.
# Usefull when uploading a large number of annotations in one dataset.
# 1. Download the project meta
dataset_id = 254737
project_id = api.dataset.get_info_by_id(dataset_id).project_id
project_meta = api.project.get_meta(project_id)

# 2. Use the context to avoid redundant API calls
with sly.ApiContext(api, dataset_id=dataset_id, project_id=project_id, project_meta=project_meta):
    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.supervisely.com'
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.supervisely.com'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
api = sly.Api.from_env()

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

# Optimizing the upload process by using the context to avoid redundant API calls.
# Usefull when uploading a large number of annotations in one dataset.
# 1. Download the project meta
dataset_id = 254737
project_id = api.dataset.get_info_by_id(dataset_id).project_id
project_meta = api.project.get_meta(project_id)

# 2. Use the context to avoid redundant API calls
with sly.ApiContext(api, dataset_id=dataset_id, project_id=project_id, project_meta=project_meta):
    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.supervisely.com'
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.supervisely.com'
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)

# Optimizing the upload process by using the context to avoid redundant API calls.
# Usefull when uploading a large number of annotations in one dataset.
# 1. Download the project meta
dataset_id = 254737
project_id = api.dataset.get_info_by_id(dataset_id).project_id
project_meta = api.project.get_meta(project_id)

# 2. Use the context to avoid redundant API calls
with sly.ApiContext(api, dataset_id=dataset_id, project_id=project_id, project_meta=project_meta):
    api.annotation.upload_paths(img_ids, ann_pathes)