Annotation API

class supervisely_lib.api.annotation_api.AnnotationApi(api)[source]

Bases: supervisely_lib.api.module_api.ModuleApi

Annotation for a single image. AnnotationApi object is immutable.

Parameters

api (Api) – API connection to the server.

Usage example
# 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.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)
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')
get_list(dataset_id: int, filters: Optional[List[dict]] = None, progress_cb: Optional[supervisely_lib.task.progress.Progress] = None) → List[NamedTuple][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 (Progress, optional) – Function for tracking download progress.

Returns

Information about Annotations. See info_sequence

Return type

List[NamedTuple]

Usage example
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"
# ]
download(image_id: int, with_custom_data: bool = False) → NamedTuple[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

Namedtuple

Usage example
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: int, image_ids: List[int], progress_cb: Optional[supervisely_lib.task.progress.Progress] = None, with_custom_data: bool = False) → List[NamedTuple][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 (Progress) – Function for tracking download progress.

Returns

Information about Annotations. See info_sequence

Return type

List[Namedtuple]

Usage example
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]
progress = sly.Progress("Annotations downloaded: ", len(image_ids))
ann_infos = api.annotation.download_batch(dataset_id, image_ids, progress_cb=progress.iters_done_report)
# 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"}
upload_path(img_id: int, ann_path: str) → None[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
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: List[int], ann_paths: List[str], progress_cb: Optional[supervisely_lib.task.progress.Progress] = None) → None[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 (Progress, optional) – Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example
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)
upload_json(img_id: int, ann_json: dict) → None[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
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: List[int], ann_jsons: List[dict], progress_cb: Optional[supervisely_lib.task.progress.Progress] = None) → None[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 (Progress, optional) – Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example
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_ann(img_id: int, ann: supervisely_lib.annotation.annotation.Annotation) → None[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
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: List[int], anns: List[supervisely_lib.annotation.annotation.Annotation], progress_cb: Optional[supervisely_lib.task.progress.Progress] = None) → None[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 (Progress, optional) – Function for tracking download progress.

Returns

None

Return type

NoneType

Usage example
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])
copy_batch(src_image_ids: List[int], dst_image_ids: List[int], progress_cb: Optional[supervisely_lib.task.progress.Progress] = None) → None[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 (Progress, optional) – Function for tracking download progress.

Raises

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

Returns

None

Return type

NoneType

Usage example
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]
progress = sly.Progress("Annotations copy: ", len(src_ids))
copy_anns = api.annotation.copy_batch(src_ids, dst_ids, progress_cb=progress.iters_done_report)
# 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(src_image_id: int, dst_image_id: int) → None[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
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
copy_ann = api.annotation.copy(src_id, dst_id)
copy_batch_by_ids(src_image_ids, dst_image_ids)[source]
InfoType

alias of supervisely_lib.api.module_api.AnnotationInfo