MeshApi¶

Bases: RemoveableBulkModuleApi

API for working with mesh entities in Supervisely.

Parameters:

api¶: Api object to use for API connection.

Usage Example:

import supervisely as sly
api = sly.Api.from_env()
mesh_info = api.mesh.get_info_by_id(mesh_id)

Methods

`convert_info_to_json`	Convert information about an entity to a dictionary.
`copy_batch`	Copy meshes with given IDs to a dataset.
`default_fields`	Default list of fields requested when listing or fetching mesh entities.
`download_path`	Download a mesh file to a local path.
`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 mesh information by ID.
`get_info_by_name`	Get mesh information by its filename within a dataset.
`get_list`	Get a list of mesh entities for a given dataset or project.
`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 `MeshInfo` field names.
`info_tuple_name`	Get string name of `MeshInfo` NamedTuple.
`remove`	Remove an entity with the specified ID from the Supervisely server.
`remove_batch`	Remove entities in batches from the Supervisely server.
`upload_ids`	Upload meshes from given source IDs to a dataset (server-side copy).
`upload_link`	Upload a single mesh from an external URL.
`upload_links`	Upload multiple meshes from external URLs.
`upload_path`	Upload a single mesh from a local file.
`upload_paths`	Upload multiple meshes from local 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.

InfoType¶: alias of MeshInfo

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 default_fields()[source]¶

Default list of fields requested when listing or fetching mesh entities.

Returns:: List of field names.
Return type:: List[str]

static info_sequence()[source]¶

Get list of all MeshInfo field names.

Returns:: List of MeshInfo field names.
Return type:: List[str]

static info_tuple_name()[source]¶

Get string name of MeshInfo NamedTuple.

Returns:: NamedTuple name.
Return type:: str

copy_batch(dst_dataset_id, ids, change_name_if_conflict=False, with_annotations=False, progress_cb=None)[source]¶

Copy meshes with given IDs to a dataset.

Parameters:

dst_dataset_id : int¶: Destination Dataset ID in Supervisely.
ids : List[int]¶: Mesh IDs to copy.
change_name_if_conflict : bool, optional¶: Add a suffix when a mesh with the same name already exists in the destination dataset. When False and a name collision is detected, raises ValueError.
with_annotations : bool, optional¶: Copy mesh annotations to the destination dataset.
progress_cb : tqdm or callable, optional¶: Progress callback invoked once per copied mesh.

Raises:

TypeError – If ids is not a list.
ValueError – If meshes from more than one source dataset are given, or if name conflicts exist and change_name_if_conflict is False.

Returns:

List of new MeshInfo objects.

Return type:

List[MeshInfo]

Usage Example:

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

mesh_infos = api.mesh.get_list(src_dataset_id)
mesh_ids = [info.id for info in mesh_infos]
new_infos = api.mesh.copy_batch(dst_dataset_id, mesh_ids, with_annotations=True)

download_path(id, path)[source]¶

Download a mesh file to a local path.

Parameters:

id : int¶: Mesh ID in Supervisely.
path : str¶: Local destination path (including filename).

Returns:

None

Return type:

None

Usage Example:

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

api.mesh.download_path(id=1, path="/tmp/scan.stl")

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, fields=None, raise_error=False)[source]¶

Get mesh information by ID.

Parameters:

id : int¶: Mesh ID in Supervisely.
fields : List[str], optional¶: Explicit list of fields to return. Defaults to default_fields().
raise_error : bool¶: If True, raise KeyError when the mesh is not found.

Returns:

Information about the mesh, or None if not found and raise_error is False.

Return type:

MeshInfo

Usage Example:

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

mesh_info = api.mesh.get_info_by_id(1)
print(mesh_info)
# Output: MeshInfo(id=1, name='scan.stl', ...)

get_info_by_name(dataset_id, name, fields=None)[source]¶

Get mesh information by its filename within a dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
name : str¶: Mesh filename to look up.
fields : List[str], optional¶: Explicit list of fields to return. Defaults to default_fields().

Returns:

Information about the mesh, or None if not found.

Return type:

MeshInfo

Usage Example:

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

mesh_info = api.mesh.get_info_by_name(dataset_id=4, name="scan.stl")

get_list(dataset_id=None, project_id=None, filters=None, sort='id', sort_order='asc', limit=None, fields=None, extra_fields=None, recursive=False, show_disabled=False)[source]¶

Get a list of mesh entities for a given dataset or project.

Exactly one of dataset_id or project_id must be provided.

Parameters:

dataset_id : int, optional¶: Dataset ID in Supervisely.
project_id : int, optional¶: Project ID in Supervisely.
filters : List[Dict[str, str]], optional¶: List of filter conditions. See the entities.list API docs.
sort : str, optional¶: Field name to sort results by. Defaults to "id".
sort_order : str, optional¶: Sort direction — "asc" or "desc". Defaults to "asc".
limit : int, optional¶: Maximum number of items to return. None returns all items.
fields : List[str], optional¶: Explicit list of fields to include in each returned item. Defaults to default_fields().
extra_fields : List[str], optional¶: Additional fields to append on top of fields.
recursive : bool, optional¶: If True, include meshes from nested datasets.
show_disabled : bool, optional¶: If True, include disabled meshes.

Returns:

List of MeshInfo objects.

Return type:

List[MeshInfo]

Usage Example:

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

mesh_infos = api.mesh.get_list(dataset_id=4)
print(mesh_infos)
# Output: [MeshInfo(...), MeshInfo(...)]

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

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)

upload_ids(dataset_id, names, ids, metas=None, progress_cb=None, descriptions=None, parent_ids=None)[source]¶

Upload meshes from given source IDs to a dataset (server-side copy).

Mirrors upload_ids(): each source mesh is re-registered in the destination dataset by its ID; the binary is not downloaded or re-uploaded.

Parameters:

dataset_id : int¶: Destination dataset ID in Supervisely.
names : List[str]¶: Destination mesh names with extension. Must match ids length.
ids : List[int]¶: Source mesh IDs in Supervisely.
metas : List[dict], optional¶: Per-mesh metadata dictionaries. Defaults to empty dicts.
progress_cb : tqdm or callable, optional¶: Progress callback.
descriptions : List[str], optional¶: Per-mesh human-readable descriptions.
parent_ids : List[int], optional¶: Per-mesh parent entity IDs.

Returns:

List of MeshInfo objects in the same order as ids.

Return type:

List[MeshInfo]

Usage Example:

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

src_infos = api.mesh.get_list(src_dataset_id)
names = [info.name for info in src_infos]
ids = [info.id for info in src_infos]
new_infos = api.mesh.upload_ids(dst_dataset_id, names, ids)

upload_link(dataset_id, link, name=None, meta=None, description=None, parent_id=None)[source]¶

Upload a single mesh from an external URL.

If name is omitted, a random name with the URL’s file extension is used. A free (non-conflicting) name is resolved automatically via get_free_name().

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
link : str¶: Public URL pointing to the mesh file.
name : str, optional¶: Desired filename (with extension). Defaults to a random name derived from link.
meta : dict, optional¶: Arbitrary metadata to attach to the mesh.
description : str, optional¶: Human-readable description of the mesh.
parent_id : int, optional¶: ID of the parent entity, if applicable.

Returns:

Information about the uploaded mesh.

Return type:

MeshInfo

Usage Example:

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

mesh_info = api.mesh.upload_link(
    dataset_id=4,
    link="https://example.com/scan.stl",
)

upload_links(dataset_id, names, links, metas=None, progress_cb=None, descriptions=None, parent_ids=None)[source]¶

Upload multiple meshes from external URLs.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: List of filenames (with extensions) for the uploaded meshes.
links : List[str]¶: List of public URLs. Must be the same length as names.
metas : List[dict], optional¶: Per-mesh metadata dictionaries. Defaults to empty dicts.
progress_cb : Callable, optional¶: Callable invoked with the number of items processed per batch.
descriptions : List[str], optional¶: Per-mesh human-readable descriptions.
parent_ids : List[int], optional¶: Per-mesh parent entity IDs.

Returns:

List of MeshInfo objects in the same order as names.

Return type:

List[MeshInfo]

Usage Example:

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

infos = api.mesh.upload_links(
    dataset_id=4,
    names=["a.stl", "b.obj"],
    links=["https://example.com/a.stl", "https://example.com/b.obj"],
)

upload_path(dataset_id, name, path, meta=None, team_files_dir=None, description=None, parent_id=None)[source]¶

Upload a single mesh from a local file.

The file is first staged in Team Files and then registered as a mesh entity. See upload_paths() for parameter details.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
name : str¶: Filename (with extension) to use in Supervisely.
path : str¶: Local filesystem path to the mesh file.
meta : dict, optional¶: Arbitrary metadata to attach to the mesh.
team_files_dir : str, optional¶: Remote Team Files directory for staging. Defaults to /supervisely/mesh_uploads/<dataset_id>.
description : str, optional¶: Human-readable description of the mesh.
parent_id : int, optional¶: ID of the parent entity, if applicable.

Returns:

Information about the uploaded mesh.

Return type:

MeshInfo

Usage Example:

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

mesh_info = api.mesh.upload_path(
    dataset_id=4,
    name="scan.stl",
    path="/local/data/scan.stl",
)

upload_paths(dataset_id, names, paths, progress_cb=None, metas=None, team_files_dir=None, descriptions=None, parent_ids=None)[source]¶

Upload multiple meshes from local files.

Each file is first staged under team_files_dir in Team Files using upload_bulk(), and then registered as a mesh entity via Team Files IDs. Only .ply, .stl, and .obj extensions are accepted for both names and paths.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: Filenames (with extensions) to use in Supervisely. Must be the same length as paths.
paths : List[str]¶: Local filesystem paths to the mesh files. Must be the same length as names.
progress_cb : Union[tqdm, Callable], optional¶: Callable invoked with the number of bytes/items processed during the Team Files upload stage.
metas : List[dict], optional¶: Per-mesh metadata dictionaries. Defaults to empty dicts.
team_files_dir : str, optional¶: Remote Team Files directory used for staging. Defaults to /supervisely/mesh_uploads/<dataset_id>.
descriptions : List[str], optional¶: Per-mesh human-readable descriptions.
parent_ids : List[int], optional¶: Per-mesh parent entity IDs.

Raises:

RuntimeError – If names and paths have different lengths.
ValueError – If any name or path has an unsupported extension.
FileNotFoundError – If any path does not point to an existing file.

Returns:

List of MeshInfo objects in the same order as names.

Return type:

List[MeshInfo]

Usage Example:

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

infos = api.mesh.upload_paths(
    dataset_id=4,
    names=["a.stl", "b.obj"],
    paths=["/local/a.stl", "/local/b.obj"],
)