VolumeFigureApi¶

class VolumeFigureApi(api)[source]¶

Bases: FigureApi

API for working with VolumeFigure. VolumeFigureApi object is immutable.

Parameters:

api¶: Api object to use for API connection.

Methods

`append_bulk`	Add VolumeFigures to given Volume by ID.
`convert_info_to_json`	Convert information about an entity to a dictionary.
`create`	Create new VolumeFigure for given slice in given volume ID.
`create_bulk`	Create figures in Supervisely in bulk.
`download`	Method returns a dictionary with pairs of volume ID and list of FigureInfo for the given dataset ID.
`download_async`	Asynchronously download figures for the given dataset ID.
`download_fast`	Download figures 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.
`download_sf_geometries`	Download spatial figure geometries for the specified figure IDs and save them to the specified paths.
`download_stl_meshes`	Download STL meshes for the specified figure IDs and saves them to the specified paths.
`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.
`interpolate`	Interpolate a spatial figure with a ClosedSurfaceMesh geometry.
`load_sf_geometry`	Download geometry of an existing in Supervisely figure and load this data into the VolumeFigure object to complete this figure representation.
`remove`	Remove an entity with the specified ID from the Supervisely server.
`remove_batch`	Remove entities in batches from the Supervisely server.
`restore`	Restore a single archived figure with the specified ID from the Supervisely server.
`restore_batch`	Restore archived figures in batches from the Supervisely server.
`update_custom_data`	Update custom data for a specific figure in a volume.
`upload_geometries_batch`	Upload figure geometries with given figure IDs to storage.
`upload_geometries_batch_async`	Upload figure geometries with given figure IDs to storage asynchronously in batches.
`upload_geometry`	Upload figure geometry with given figure ID to storage.
`upload_sf_geometries`	Upload geometries as bytes into spatial figures in the project using their UUID keys.
`upload_sf_geometry`	Upload spatial figures geometry as bytes to storage by given ID.
`upload_stl_meshes`	Upload existing interpolations or create on the fly and and add them to empty mesh figures.

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 FigureInfo

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

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

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

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

Add VolumeFigures to given Volume by ID.

Parameters:

volume_id : int¶: Volume ID in Supervisely.
key_id_map¶: KeyIdMap object.
figures¶: List of VolumeFigure objects.

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly
from supervisely.volume_annotation.plane import Plane

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

project_id = 19370
volume_id = 19617444

key_id_map = sly.KeyIdMap()

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

vol_ann_json = api.volume.annotation.download(volume_id)
vol_ann = sly.VolumeAnnotation.from_json(vol_ann_json, project_meta, key_id_map)
volume_obj_collection = vol_ann.objects.to_json()
vol_obj = sly.VolumeObject.from_json(volume_obj_collection[1], project_meta)

figure = sly.VolumeFigure(
    vol_obj,
    sly.Rectangle(20, 20, 129, 200),
    sly.Plane.AXIAL,
    45,
)

api.volume.figure.append_bulk(volume_id, [figure], key_id_map)

create(volume_id, object_id, plane_name, slice_index, geometry_json, geometry_type, custom_data=None)[source]¶

Create new VolumeFigure for given slice in given volume ID.

Parameters:

volume_id : int¶: Volume ID in Supervisely.
object_id : int¶: ID of the object to which the VolumeFigure belongs.
plane_name : str¶: Plane of the slice in volume.
slice_index : int¶: Number of the slice to add VolumeFigure.
geometry_json : dict¶: Parameters of geometry for VolumeFigure.
geometry_type : str¶: Type of VolumeFigure geometry.

Returns:

New figure ID

Return type:

int

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly
from supervisely.volume_annotation.plane import Plane

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

volume_id = 19581134
object_id = 5565016
slice_index = 0
plane_name = Plane.AXIAL
geometry_json = {'points': {'exterior': [[500, 500], [1555, 1500]], 'interior': []}}
geometry_type = 'rectangle'

figure_id = api.volume.figure.create(
    volume_id,
    object_id,
    plane_name,
    slice_index,
    geometry_json,
    geometry_type
) # 87821207

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.

Returns:

List of figure IDs.

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

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

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
volume_ids : List[int], optional¶: Specify the list of volume IDs within the given dataset ID. If volume_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 volume IDs and values are lists of figures.

Return type:

Dict[int, List[FigureInfo]]

async download_async(dataset_id, image_ids=None, skip_geometry=False, filters=None, semaphore=None, log_progress=True, batch_size=300)¶

Asynchronously download figures for the given dataset ID. Can be filtered by image IDs. This method is significantly faster than the synchronous version for large datasets.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
image_ids : List[int], optional¶: Specify the list of image IDs within the given dataset ID. If image_ids is None, the method returns all possible pairs of images with figures.
skip_geometry : bool¶: Skip the download of figure geometry. May be useful for a significant api request speed increase in the large datasets.
filters : List[Dict[str, Any]], optional¶: Filters for the figures. See https://api.docs.supervisely.com/#tag/Figures/paths/~1figures.list/get for more details.
semaphore : Optional[asyncio.Semaphore], optional¶: Semaphore to limit the number of concurrent downloads.
log_progress : bool, optional¶: If True, log the progress of the download.
batch_size : int, optional¶: Size of the batch for downloading figures per 1 request. Default is 300. Used for batching image_ids when filtering by specific images. Adjust this value for optimal performance, value cannot exceed 500.

Returns:

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

Return type:

Dict[int, List[FigureInfo]]

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 = 40568
image_id = 4877489

download_coroutine = api.image.figure.download_async(dataset_id, [image_id])
figures = sly.run_coroutine(download_coroutine)

filtered_figures = sly.run_coroutine(
    api.image.figure.download_async(
        dataset_id,
        [image_id],
        filters=[
            {
                "type": "objects_class",
                "data": {
                    "from": 1,
                    "to": 9999,
                    "include": True,
                    "classId": 154344,
                },
            }
        ],
    )
)

download_fast(dataset_id, image_ids=None, skip_geometry=False, filters=None, semaphore=None, log_progress=True, batch_size=300)¶

Download figures for the given dataset ID. Can be filtered by image IDs. This method is significantly faster than the synchronous version for large datasets and is designed to be used in an asynchronous context. Will fallback to the synchronous version if async fails.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
image_ids : List[int], optional¶: Specify the list of image IDs within the given dataset ID. If image_ids is None, the method returns all possible pairs of images with figures.
skip_geometry : bool¶: Skip the download of figure geometry. May be useful for a significant api request speed increase in the large datasets.
filters : List[Dict[str, Any]], optional¶: Filters for the figures. See https://api.docs.supervisely.com/#tag/Figures/paths/~1figures.list/get for more details.
semaphore : Optional[asyncio.Semaphore], optional¶: Semaphore to limit the number of concurrent downloads.
log_progress : bool, optional¶: If True, log the progress of the download.
batch_size : int, optional¶: Size of the batch for downloading figures per 1 request. Default is 300. Used for batching image_ids when filtering by specific images. Adjust this value for optimal performance, value cannot exceed 500.

Returns:

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

Return type:

Dict[int, List[FigureInfo]]

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 = 40568
image_id = 4877489
figures = api.image.figure.download_fast(dataset_id, [image_id])

filtered_figures = api.image.figure.download_fast(
    dataset_id,
    [image_id],
    filters=[
        {
            "type": "objects_class",
            "data": {
                "from": 1,
                "to": 9999,
                "include": True,
                "classId": 154344,
            },
        }
    ],
)

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 os
import asyncio
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()

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

download_sf_geometries(ids, paths)[source]¶

Download spatial figure geometries for the specified figure IDs and save them to the specified paths.

Parameters:

ids : List[int]¶: List of VolumeFigure IDs in Supervisely.
paths : List[str]¶: List of paths to save the downloaded geometries.

Returns:

None

Return type:

None

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

STORAGE_DIR = sly.app.get_data_dir()

volume_id = 19371414
project_id = 17215

volume = api.volume.get_info_by_id(volume_id)

key_id_map = sly.KeyIdMap()
project_meta_json = api.project.get_meta(project_id)
project_meta = sly.ProjectMeta.from_json(project_meta_json)

vol_ann_json = api.volume.annotation.download(volume_id)
id_to_paths = {}
vol_ann = sly.VolumeAnnotation.from_json(vol_ann_json, project_meta, key_id_map)

for sp_figure in vol_ann.spatial_figures:
    figure_id = key_id_map.get_figure_id(sp_figure.key())
    id_to_paths[figure_id] = f"{STORAGE_DIR}/{sp_figure.key().hex}.stl"
if id_to_paths:
    api.volume.figure.download_sf_geometries(*zip(*id_to_paths.items()))

download_stl_meshes(ids, paths)[source]¶

Download STL meshes for the specified figure IDs and saves them to the specified paths.

Parameters:

ids : int¶: VolumeFigure ID in Supervisely.
paths : List[str]¶: List of paths to download.

Returns:

None

Return type:

None

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

STORAGE_DIR = sly.app.get_data_dir()

volume_id = 19371414
project_id = 17215

volume = api.volume.get_info_by_id(volume_id)

key_id_map = sly.KeyIdMap()
project_meta_json = api.project.get_meta(project_id)
project_meta = sly.ProjectMeta.from_json(project_meta_json)

vol_ann_json = api.volume.annotation.download(volume_id)
id_to_paths = {}
vol_ann = sly.VolumeAnnotation.from_json(vol_ann_json, project_meta, key_id_map)

for sp_figure in vol_ann.spatial_figures:
    figure_id = key_id_map.get_figure_id(sp_figure.key())
    id_to_paths[figure_id] = f"{STORAGE_DIR}/{sp_figure.key().hex}.stl"

if id_to_paths:
    api.volume.figure.download_stl_meshes(*zip(*id_to_paths.items()))

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

Return type:

List[FigureInfo]

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 = 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 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 Figure information by ID.

Parameters:

id : int¶: Figure ID in Supervisely.

Returns:

Information about Figure.

Return type:

FigureInfo

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

figure_id = 588801373
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 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))

interpolate(volume_id, spatial_figure, key_id_map)[source]¶

Interpolate a spatial figure with a ClosedSurfaceMesh geometry.

Parameters:

volume_id : int¶: VolumeFigure ID in Supervisely.
spatial_figure¶: Spatial figure to interpolate.
key_id_map¶: KeyIdMap object.

Returns:

None

Return type:

None

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

volume_id = 19371414
project_id = 17215

volume = api.volume.get_info_by_id(volume_id)

key_id_map = sly.KeyIdMap()
project_meta_json = api.project.get_meta(project_id)
project_meta = sly.ProjectMeta.from_json(project_meta_json)

vol_ann_json = api.volume.annotation.download(volume_id)
id_to_paths = {}
vol_ann = sly.VolumeAnnotation.from_json(vol_ann_json, project_meta, key_id_map)

for sp_figure in vol_ann.spatial_figures:
    res = volume_figure_api.interpolate(volume_id, sp_figure, key_id_map)

load_sf_geometry(spatial_figure, key_id_map)[source]¶

Download geometry of an existing in Supervisely figure and load this data into the VolumeFigure object to complete this figure representation.

Parameters:

spatial_figure¶: The spatial figure object from VolumeAnnotation.
key_id_map : KeyIdMap object¶: The mapped keys and IDs.

remove(id)¶

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

Parameters:

id : int¶: Entity ID in Supervisely.

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

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

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

restore(id)¶

Restore a single archived figure with the specified ID from the Supervisely server.

Parameters:

id : int¶: Figure ID in Supervisely.

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

Restore archived figures in batches from the Supervisely server.

Parameters:

ids : List[int]¶: IDs of figures in Supervisely.
progress_cb : Optional[Callable]¶: Optional callback to track restore progress. Receives number of restored figures in the current batch.
batch_size : int¶: Number of figure IDs to send in a single request.

update_custom_data(figure_id, custom_data, update_strategy='merge')[source]¶

Update custom data for a specific figure in a volume.

Parameters:

figure_id : int¶: ID of the figure to update.
custom_data : Dict[str, str]¶: Custom data to update.
update_strategy : Literal["replace", "merge"]¶: Strategy to apply, either “replace” or “merge”.

Returns:

None

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

async upload_geometries_batch_async(figure_ids, geometries, semaphore=None, progress_cb=None)¶

Upload figure geometries with given figure IDs to storage asynchronously in batches.

Parameters:

figure_ids : List[int]¶: List of figure IDs in Supervisely.
geometries : List[dict]¶: List of figure geometries in Supervisely JSON format.
semaphore : Optional[asyncio.Semaphore], optional¶: Semaphore to limit the number of concurrent uploads.
progress_cb : Union[tqdm, Callable], optional¶: Progress bar to show the upload progress. Shows the number of geometries uploaded.

Returns:

None

Return type:

None

Usage Example:

import os
import asyncio
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()

figure_ids = [642155547, 642155548, 642155549]
geometries = [{...}, {...}, {...}]  # Your geometry data

upload_coroutine = api.figure.upload_geometries_batch_async(
    figure_ids,
    geometries,
    semaphore=asyncio.Semaphore(10),
)
sly.run_coroutine(upload_coroutine)

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

upload_sf_geometries(spatial_figures, geometries, key_id_map)[source]¶

Upload geometries as bytes into spatial figures in the project using their UUID keys.

Parameters:

spatial_figures : List[UUID]¶: List of UUID keys representing spatial figures.
geometries : Dict[UUID, bytes]¶: Dictionary where keys are UUIDs of spatial figures, and values are geometries represented as NRRD files in byte format.
key_id_map¶: KeyIdMap object (a dictionary with bidict values).

Returns:

None

Return type:

None

Usage Example:

import os
import numpy as np
from dotenv import load_dotenv

import supervisely as sly
from supervisely.volume.nrrd_encoder import encode

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

volume_id = 23772225
project_id = 28159
geometries = {}
key_id_map = sly.KeyIdMap()
geometry_bytes = encode(np.random.randint(2, size=(20, 20, 20), dtype=np.uint8))

vol_ann_json = api.volume.annotation.download(volume_id)
project_meta = sly.ProjectMeta.from_json(api.project.get_meta(project_id))
ann = sly.VolumeAnnotation.from_json(vol_ann_json, project_meta, key_id_map)
spatial_figures = [sp_figure.key() for sp_figure in ann.spatial_figures]
for figure in spatial_figures:
    geometries[figure] = geometry_bytes
api.volume.figure.upload_sf_geometries(spatial_figures, geometries, key_id_map)

upload_sf_geometry(spatial_figures, geometries, key_id_map)[source]¶

Upload spatial figures geometry as bytes to storage by given ID.

Parameters:

spatial_figures : dict¶: Dictionary with figure IDs.
geometries : list¶: Dictionary with geometries, which represented as content of NRRD files in byte format.
key_id_map¶: KeyIdMap object (dict with bidict values)

Return type:

None

upload_stl_meshes(volume_id, spatial_figures, key_id_map, interpolation_dir=None)[source]¶

Upload existing interpolations or create on the fly and and add them to empty mesh figures.

Parameters:

volume_id : int¶: VolumeFigure ID in Supervisely.
spatial_figures¶: List of spatial figures to upload.
key_id_map¶: KeyIdMap object.

Returns:

None

Return type:

None

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

volume_id = 19371414
project_id = 17215

volume = api.volume.get_info_by_id(volume_id)

key_id_map = sly.KeyIdMap()
project_meta_json = api.project.get_meta(project_id)
project_meta = sly.ProjectMeta.from_json(project_meta_json)

vol_ann_json = api.volume.annotation.download(volume_id)
id_to_paths = {}
vol_ann = sly.VolumeAnnotation.from_json(vol_ann_json, project_meta, key_id_map)
sp_figures = vol_ann.spatial_figures

res = volume_figure_api.upload_stl_meshes(volume_id, sp_figures, key_id_map)