VolumeFigureApi¶

class VolumeFigureApi[source]¶

Bases: supervisely.api.entity_annotation.figure_api.FigureApi

VolumeFigure for a single volume.

Methods

`append_bulk`	Add VolumeFigures to given Volume by ID.
`create`	Create new VolumeFigure for given slice in given volume ID.
`download`	Method returns a dictionary with pairs of image ID and list of FigureInfo for the given dataset ID.
`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
`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.
`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 supervisely.api.module_api.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: KeyIdMap object.
figures : List[VolumeFigure]: List of VolumeFigure objects.

Returns

None

Return type

NoneType

Usage example

import supervisely as sly

from supervisely.volume_annotation.plane import Plane

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

from supervisely.volume_annotation.plane import Plane

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

download(dataset_id, image_ids=None, skip_geometry=False)¶

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

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. 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 requets speed increase in the large datasets.

Returns

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

Return type

class: Dict[int, List[FigureInfo]]

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

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

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

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

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 supervisely as sly

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


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. See info_sequence

Return type

List[NamedTuple]

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 = 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 supervisely as sly

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


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. See info_sequence

Return type

NamedTuple

Usage example

import supervisely as sly

figure_id = 588801373

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

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 supervisely as sly

# 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 = 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 supervisely as sly

# 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 = 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

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

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 supervisely as sly

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

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

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 : VolumeFigure: Spatial figure to interpolate.
key_id_map : KeyIdMap: KeyIdMap 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()

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 : VolumeFigure: 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 supervisely as sly

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


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 supervisely as sly

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


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

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: The KeyIdMap object (a dictionary with bidict values).

Returns

None

Return type

NoneType

Usage example

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

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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: KeyIdMap object (dict with bidict values)

Return type

NoneType

Usage example

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[VolumeFigure]: List of spatial figures to upload.
key_id_map : KeyIdMap: KeyIdMap 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()

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)