MeshAnnotationAPI¶

class MeshAnnotationAPI(api)[source]¶

Bases: EntityAnnotationAPI

API for mesh annotations.

A mesh annotation is a flat list of labels, each persisted as a single mesh object (api.mesh.object) referencing its mesh entity directly. The nested “figures” entity used by video/pointcloud annotations is not applicable here. Object index geometry is stored as a separate blob in geometry storage.

Like image annotations, server-side IDs are carried inline in the annotation JSON (label["id"]); there is no KeyIdMap. On upload, objects are associated with their labels by order.

Parameters:

api¶: Api object to use for API connection.

Methods

`append`	Append a full mesh annotation to the mesh entity.
`convert_info_to_json`	Convert information about an entity to a dictionary.
`copy_batch`	Copy annotations from source meshes to destination meshes.
`download`	Download mesh annotation by mesh ID.
`download_bulk`	Download mesh annotation transfer JSONs by mesh IDs.
`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_json`	Upload one mesh annotation JSON to the mesh entity.
`upload_paths`	Upload mesh annotations from local JSON files.

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(mesh_id, ann)[source]¶

Append a full mesh annotation to the mesh entity.

Parameters:

mesh_id : int¶: Mesh ID in Supervisely.
ann¶: Mesh annotation object or its JSON representation.

Returns:

None

Return type:

None

Raises:

TypeError – If ann is neither a MeshAnnotation nor a dict.

Usage Example:

import supervisely as sly
api = sly.Api.from_env()

ann_json = api.mesh.annotation.download(mesh_id)
api.mesh.annotation.append(mesh_id, ann_json)

copy_batch(src_mesh_ids, dst_mesh_ids, progress_cb=None)[source]¶

Copy annotations from source meshes to destination meshes.

Downloads annotations from each source mesh and uploads them to the corresponding destination mesh. Source and destination meshes must belong to projects with compatible meta (call api.project.merge_metas() first).

Parameters:

src_mesh_ids : List[int]¶: Source mesh IDs.
dst_mesh_ids : List[int]¶: Destination mesh IDs. Must match src_mesh_ids in length.
progress_cb : tqdm or callable, optional¶: Progress callback invoked once per annotation copied.

Raises:

RuntimeError – If src_mesh_ids and dst_mesh_ids have different lengths.

Returns:

None

Return type:

None

Usage Example:

import supervisely as sly
api = sly.Api.from_env()

api.project.merge_metas(src_project_id, dst_project_id)
api.mesh.annotation.copy_batch(src_mesh_ids, dst_mesh_ids)

download(mesh_id, download_mesh_geometries=True)[source]¶

Download mesh annotation by mesh ID.

Parameters:

mesh_id : int¶: Mesh ID in Supervisely.
download_mesh_geometries : bool¶: Download raw mesh index geometry blobs and patch them into the annotation JSON when labels reference external geometry storage.

Returns:

Annotation JSON.

Return type:

dict

download_bulk(dataset_id, mesh_ids, download_mesh_geometries=True, progress_cb=None)[source]¶

Download mesh annotation transfer JSONs by mesh IDs.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
mesh_ids : List[int]¶: Mesh entity IDs.
download_mesh_geometries : bool¶: Download raw mesh index geometry blobs and patch them into JSON when annotation labels reference external geometry.
progress_cb : tqdm or callable, optional¶: Progress callback.

Returns:

Annotation JSONs ordered like mesh_ids.

Return type:

List[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 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_json(mesh_id, ann_json)[source]¶

Upload one mesh annotation JSON to the mesh entity.

Thin wrapper around append().

Parameters:

mesh_id : int¶: Mesh ID in Supervisely.
ann_json : dict¶: Mesh annotation JSON.

Returns:

None

Return type:

None

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

Upload mesh annotations from local JSON files.

Each annotation is loaded from its file and appended to the matching mesh via append().

Parameters:

mesh_ids : List[int]¶: Mesh IDs in Supervisely. Must match ann_paths length.
ann_paths : List[str]¶: Local paths to mesh annotation JSON files.
progress_cb : tqdm or callable, optional¶: Progress callback.

Returns:

None

Return type:

None

Raises:

ValueError – If mesh_ids and ann_paths have different lengths.