PointcloudEpisodeApi¶

class PointcloudEpisodeApi(api)[source]¶

Bases: PointcloudApi

API for working with point cloud episodes.

Parameters:

api¶: Api object to use for API connection.

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

pcd_epsodes_id = 19373295
pcd_epsodes_info = api.pointcloud_episode.get_info_by_id(pcd_epsodes_id) # api usage example

Methods

`add_related_images`	Attach images to point cloud by hash or link.
`check_existing_hashes`	Check if point clouds with given hashes are exist.
`convert_info_to_json`	Convert information about an entity to a dictionary.
`download_path`	Download point cloud with given id on the given path.
`download_path_async`	Downloads Point cloud with given ID to local path.
`download_paths_async`	Download Point clouds with given IDs and saves them to given local paths asynchronously.
`download_related_image`	Download a related context image from Supervisely to local directory by image id.
`download_related_image_async`	Downloads a related context image from Supervisely to local directory by image id.
`download_related_images_async`	Downloads a related context image from Supervisely to local directory by image id.
`exists`	Checks if an entity with the given parent_id and name exists
`get_frame_name_map`	Get a dictionary with frame_id and name of pointcloud by dataset id.
`get_free_name`	Generates a free name for an entity with the given parent_id and name.
`get_free_names`	Returns list of free names for given dataset.
`get_info_by_id`	Get point cloud information by ID in `PointcloudInfo` format.
`get_info_by_name`	Get information about an entity by its name from the Supervisely server.
`get_list`	Get list of information about all point cloud for a given dataset 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.
`get_list_related_images`	Get information about related context images.
`get_list_related_images_batch`
`get_max_frame_idx`	Get max frame index for episode by dataset id.
`info_sequence`	Get list of all `PointcloudInfo` field names.
`info_tuple_name`	Get string name of `PointcloudInfo` NamedTuple.
`notify_progress`	Send message to the Annotation Tool and return info if tracking was stopped
`raise_name_intersections_if_exist`	Raises error if pointclouds with given names already exist in dataset.
`remove`	Remove an entity with the specified ID from the Supervisely server.
`remove_batch`	Remove entities in batches from the Supervisely server.
`rename`	Renames Pointcloud with given ID to a new name.
`update_frames_order`	Update order of frames in a point cloud episode dataset.
`upload_dir`	Uploads all pointclouds with supported extensions from given directory to Supervisely.
`upload_dirs`	Uploads all pointclouds with supported extensions from given directories to Supervisely.
`upload_hash`	Upload Pointcloud from given hash to Dataset.
`upload_hashes`	Upload point clouds from given hashes to Dataset.
`upload_link`	Upload point cloud from given link to Dataset.
`upload_links`	Upload point clouds from given links to Dataset.
`upload_path`	Upload point cloud with given path to Dataset.
`upload_paths`	Upload point clouds with given paths to Dataset.
`upload_paths_via_team_files`	Upload PLY/LAS/LAZ point clouds by first staging them in Team Files, then adding to dataset.
`upload_related_image`	Upload an image to the Supervisely.
`upload_related_images`	Upload a batch of related images to the Supervisely.
`upload_team_files_ids`	Add point clouds already present in Team Files to a dataset by their file IDs.

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 PointCloudInfo

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 PointcloudInfo field names.

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

static info_tuple_name()¶

Get string name of PointcloudInfo NamedTuple.

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.pointcloud.info_tuple_name()
print(tuple_name) # PointCloudInfo

add_related_images(images_json, camera_names=None)¶

Attach images to point cloud by hash or link.

Parameters:

images_json : List[Dict]¶: List of dictionaries with entityId, name, and either ‘hash’ (for uploaded files) or ‘link’ (for external URLs), plus optional meta.
camera_names : List[Dict]¶: List of camera informations.

Returns:

Response object

Return type:

Dict

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

# Example 1: Using uploaded images (with hash)
img_paths = ["src/input/img/000001.png", "src/input/img/000002.png"]
cam_paths = ["src/input/cam_info/000001.json", "src/input/cam_info/000002.json"]

img_hashes = api.pointcloud.upload_related_images(img_paths)
img_infos = []
for i, cam_info_file in enumerate(cam_paths):
    # reading cam_info
    with open(cam_info_file, "r") as f:
        cam_info = json.load(f)
    img_info = {
        "entityId": pcd_infos[i].id,
        "name": f"img_{i}.png",
        "hash": img_hashes[i],
        "meta": cam_info,
    }
    img_infos.append(img_info)
api.pointcloud.add_related_images(img_infos)

# Example 2: Using external links (without uploading)
img_links = [
    "https://example.com/images/cam_front.png",
    "https://example.com/images/cam_back.png"
]
img_infos_with_links = []
for i, link in enumerate(img_links):
    with open(cam_paths[i], "r") as f:
        cam_info = json.load(f)
    img_info = {
        "entityId": pcd_infos[i].id,
        "name": f"img_{i}.png",
        "link": link,  # Use 'link' instead of 'hash'
        "meta": cam_info,
    }
    img_infos_with_links.append(img_info)
api.pointcloud.add_related_images(img_infos_with_links)

check_existing_hashes(hashes)¶

Check if point clouds with given hashes are exist.

Parameters:

paths : List[str]: Point clouds hashes to check.

Returns:

List of point clouds hashes that are exist.

Return type:

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

pointcloud_id = 19618685
pcd_info = api.pointcloud.get_info_by_id(pointcloud_id)
hash = api.pointcloud.check_existing_hashes([pcd_info.hash])
print(hash)

# Output:
# ['5w69Vv1i6JrqhU0Lw1UJAJFGPhgkIhs7O3f4QSwRfmE=']

download_path(id, path)¶

Download point cloud with given id on the given path.

Parameters:

id : int¶: Point cloud ID in Supervisely.
path : str¶: Local save path for point cloud.

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()
pcd_id = 19373403
pcd_info = api.pointcloud.get_info_by_id(pcd_id)
save_path = os.path.join(storage_dir, pcd_info.name)

api.pointcloud.download_path(pcd_id, save_path)
print(os.listdir(storage_dir))

# Output: ['000063.pcd']

async download_path_async(id, path, semaphore=None, range_start=None, range_end=None, headers=None, chunk_size=1048576, check_hash=True, progress_cb=None, progress_cb_type='number')¶

Downloads Point cloud with given ID to local path.

Parameters:

id : int¶: Point cloud ID in Supervisely.
path : str¶: Local save path for Point cloud.
semaphore=None¶: Semaphore for limiting the number of simultaneous downloads.
range_start : int, optional¶: Start byte of range for partial download.
range_end : int, optional¶: End byte of range for partial download.
headers : dict, optional¶: Headers for request.
chunk_size : int, optional¶: Size of chunk for partial download. Default is 1MB.
check_hash : bool, optional¶: If True, checks hash of downloaded file. Check is not supported for partial downloads. When range is set, hash check is disabled.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
progress_cb_type : Literal["number", "size"], optional¶: Type of progress callback. Can be “number” or “size”. Default is “number”.

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

pcd_info = api.pointcloud.get_info_by_id(19373403)
save_path = os.path.join("/path/to/save/", pcd_info.name)

semaphore = asyncio.Semaphore(100)
loop = sly.utils.get_or_create_event_loop()
loop.run_until_complete(
    api.pointcloud.download_path_async(pcd_info.id, save_path, semaphore)
)

async download_paths_async(ids, paths, semaphore=None, headers=None, chunk_size=1048576, check_hash=True, progress_cb=None, progress_cb_type='number')¶

Download Point clouds with given IDs and saves them to given local paths asynchronously.

Parameters:

ids¶: List of Point cloud IDs in Supervisely.
paths¶: Local save paths for Point clouds.
semaphore=None¶: Semaphore for limiting the number of simultaneous downloads.
headers : dict, optional¶: Headers for request.
show_progress : bool, optional: If True, shows progress bar.
chunk_size : int, optional¶: Size of chunk for partial download. Default is 1MB.
check_hash : bool, optional¶: If True, checks hash of downloaded file.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
progress_cb_type : Literal["number", "size"], optional¶: Type of progress callback. Can be “number” or “size”. Default is “number”.

Raises:

ValueError – if len(ids) != len(paths)

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

ids = [19373403, 19373404]
paths = ["/path/to/save/000063.pcd", "/path/to/save/000064.pcd"]
loop = sly.utils.get_or_create_event_loop()
loop.run_until_complete(api.pointcloud.download_paths_async(ids, paths))

download_related_image(id, path=None)¶

Download a related context image from Supervisely to local directory by image id.

Parameters:

id : int¶: Related context imgage ID in Supervisely.
path : str¶: Local save path for point cloud.

Returns:

List of dictionaries with informations about related images

Return type:

List

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

save_path = "src/output/img_0.png"
img_info = api.pointcloud.get_list_related_images(pcd_info.id)[0]
api.pointcloud.download_related_image(img_info["id"], save_path)
print(f"Context image has been successfully downloaded to '{save_path}'")

# Output:
# Context image has been successfully downloaded to 'src/output/img_0.png'

async download_related_image_async(id, path, semaphore=None, headers=None, chunk_size=1048576, check_hash=True, progress_cb=None, progress_cb_type='number')¶

Downloads a related context image from Supervisely to local directory by image id.

Parameters:

id : int¶: Point cloud ID in Supervisely.
path : str¶: Local save path for Point cloud.
semaphore=None¶: Semaphore for limiting the number of simultaneous downloads.
headers : dict, optional¶: Headers for request.
chunk_size : int, optional¶: Size of chunk for partial download. Default is 1MB.
check_hash : bool, optional¶: If True, checks hash of downloaded file.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
progress_cb_type : Literal["number", "size"], optional¶: Type of progress callback. Can be “number” or “size”. Default is “number”.

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

img_info = api.pointcloud.get_list_related_images(19373403)[0]
save_path = os.path.join("/path/to/save/", img_info.name)

semaphore = asyncio.Semaphore(100)
loop = sly.utils.get_or_create_event_loop()
loop.run_until_complete(
    api.pointcloud.download_related_image_async(19373403, save_path, semaphore)
)

async download_related_images_async(ids, paths, semaphore=None, headers=None, check_hash=True, progress_cb=None, progress_cb_type='number')¶

Downloads a related context image from Supervisely to local directory by image id.

Parameters:

ids : int¶: Related context imgage IDs in Supervisely.
paths : str¶: Local save paths for Point clouds.
semaphore=None¶: Semaphore for limiting the number of simultaneous downloads.
headers : dict, optional¶: Headers for request.
check_hash : bool, optional¶: If True, checks hash of downloaded file.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking download progress.
progress_cb_type : Literal["number", "size"], optional¶: Type of progress callback. Can be “number” or “size”. Default is “number”.

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

img_infos = api.pointcloud.get_list_related_images(19373403)
ids = [img_info.id for img_info in img_infos]
save_paths = [os.path.join("/path/to/save/", img_info.name) for img_info in img_infos]

semaphore = asyncio.Semaphore(100)
loop = sly.utils.get_or_create_event_loop()
loop.run_until_complete(
    api.pointcloud.download_related_images_async(ids, save_paths, semaphore)
)

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

Get a dictionary with frame_id and name of pointcloud by dataset id.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.

Returns:

Dictionary mapping frame index to point cloud name.

Return type:

Dict[int, 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()

dataset_id = 62664
frame_to_name_map = api.pointcloud_episode.get_frame_name_map(dataset_id)
print(frame_to_name_map)

# Output:
# {0: '001', 1: '002'}

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_free_names(dataset_id, names)¶

Returns list of free names for given dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: List of names to check.

Returns:

List of free names.

Return type:

List[str]

get_info_by_id(id)¶

Get point cloud information by ID in PointcloudInfo format.

Parameters:

id : int¶: Point cloud ID in Supervisely.
raise_error : bool: Return an error if the point cloud info was not received.

Returns:

Information about point cloud.

Return type:

PointcloudInfo

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

pcd_id = 19373403
pcd_info = api.pointcloud.get_info_by_id(pcd_id)
print(pcd_info)

# Output:
# PointcloudInfo(
#     id=19373403,
#     frame=None,
#     description='',
#     name='000063.pcd',
#     team_id=435,
#     workspace_id=687,
#     project_id=17231,
#     dataset_id=55875,
#     link=None,
#     hash='7EcJCyhq15V4NnZ8oiPrKQckmXXypO4saqFN7kgH08Y=',
#     path_original='/h5unms4-public/point_clouds/Z/h/bc/roHZP5nP2.pcd',
#     cloud_mime='image/pcd',
#     figures_count=4,
#     objects_count=4,
#     tags=[],
#     meta={},
#     created_at='2023-02-07T19:36:44.897Z',
#     updated_at='2023-02-07T19:36:44.897Z'
# )

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(dataset_id, filters=None)¶

Get list of information about all point cloud for a given dataset ID.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
filters : List[Dict[str, str]], optional¶: List of parameters to sort output Pointclouds. See: https://api.docs.supervisely.com/#tag/Point-Clouds/paths/~1point-clouds.list/get

Returns:

List of the point cloud objects from the dataset with the given ID.

Return type:

List[PointcloudInfo]

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 = 62664
pcd_infos = api.pointcloud_episode.get_list(dataset_id)
print(pcd_infos)
# Output: [PointcloudInfo(...), PointcloudInfo(...)]

id_list = [19618654, 19618657, 19618660]
filtered_pointcloud_infos = api.pointcloud.get_list(dataset_id, filters=[{'field': 'id', 'operator': 'in', 'value': id_list}])
print(filtered_pointcloud_infos)
# Output:
# [PointcloudInfo(id=19618654, ...), PointcloudInfo(id=19618657, ...), PointcloudInfo(id=19618660, ...)]

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

get_list_related_images(id)¶

Get information about related context images.

Parameters:

id : int¶: Point cloud ID in Supervisely.

Returns:

List of dictionaries with informations about related images

Return type:

List

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

pcd_id = 19373403
img_infos = api.pointcloud.get_list_related_images(pcd_id)
img_info = img_infos[0]
print(img_info)

# Output:
# {
#     'pathOriginal': '/h5un6qgms4-public/images/original/S/j/hJ/PwMg.png',
#     'id': 473302,
#     'entityId': 19373403,
#     'createdAt': '2023-01-09T08:50:33.225Z',
#     'updatedAt': '2023-01-09T08:50:33.225Z',
#     'meta': {
#         'deviceId': 'cam_2'},
#         'fileMeta': {'mime': 'image/png',
#         'size': 893783,
#         'width': 1224,
#         'height': 370
#     },
#     'hash': 'vxA+emfDNUkFP9P6oitMB5Q0rMlnskmV2jvcf47OjGU=',
#     'link': None,
#     'preview': '/previews/q/ext:jpeg/resize:fill:50:0:0/q:50/plain/h5ad-public/images/original/S/j/hJ/PwMg.png',
#     'fullStorageUrl': 'https://app.supervisely.com/hs4-public/images/original/S/j/hJ/PwMg.png',
#     'name': 'img00'
# }

get_max_frame_idx(dataset_id)[source]¶

Get max frame index for episode by dataset id. This method is useful for uploading pointclouds to the episode in parts.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.

Returns:

Max frame index, or None if the dataset has no point clouds.

Return type:

Optional[int]

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 = 62664
max_frame = api.pointcloud_episode.get_max_frame_idx(dataset_id)
print(max_frame)

# Output: 1

notify_progress(track_id, dataset_id, pcd_ids, current, total)[source]¶

Send message to the Annotation Tool and return info if tracking was stopped

Parameters:

track_id¶: int
dataset_id¶: int
pcd_ids¶: list
current¶: int
total¶: int

Returns:

True if tracking was stopped, False otherwise.

Return type:

bool

raise_name_intersections_if_exist(dataset_id, names, message=None)¶

Raises error if pointclouds with given names already exist in dataset. Default error message: “Pointclouds with the following names already exist in dataset [ID={dataset_id}]: {name_intersections}. Please, rename pointclouds and try again or set change_name_if_conflict=True to rename automatically on upload.”

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: List of names to check.
message : str, optional¶: Error message.

Returns:

None

Return type:

None

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)

rename(id, name)¶

Renames Pointcloud with given ID to a new name.

Parameters:

id : int¶: Pointcloud ID in Supervisely.
name : str¶: New Pointcloud name.

Returns:

Information about updated Pointcloud.

Return type:

PointcloudInfo

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

pointcloud_id = 123456
new_pointcloud_name = "3333_new.pcd"

api.pointcloud.rename(id=pointcloud_id, name=new_pointcloud_name)

update_frames_order(dataset_id, ids)[source]¶

Update order of frames in a point cloud episode dataset.

Pass a full list of point cloud IDs (ids) in the target order.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
ids : List[int]¶: Full list of point cloud IDs in the new order.

Returns:

None

Return type:

None

Usage Example:

import os
from dotenv import load_dotenv

import supervisely as sly

if sly.is_development():
    load_dotenv(os.path.expanduser("~/supervisely.env"))

api = sly.Api.from_env()

dataset_id = 1815
ids = [101, 205, 309]
api.pointcloud_episode.update_frames_order(dataset_id, ids)

upload_dir(dataset_id, dir_path, recursive=True, change_name_if_conflict=True, progress_cb=None)¶

Uploads all pointclouds with supported extensions from given directory to Supervisely. Optionally, uploads pointclouds from subdirectories of given directory.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
dir_path : str¶: Path to directory with pointclouds.
recursive : bool, optional¶: If True, will upload pointclouds from subdirectories of given directory recursively. Otherwise, will upload pointclouds only from given directory.
change_name_if_conflict : bool, optional¶: If True adds suffix to the end of Pointcloud name when Dataset already contains an Pointcloud with identical name, If False and pointclouds with the identical names already exist in Dataset raises error.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking upload progress.

Returns:

List of uploaded pointclouds infos

Return type:

List[PointcloudInfo]

upload_dirs(dataset_id, dir_paths, recursive=True, change_name_if_conflict=True, progress_cb=None)¶

Uploads all pointclouds with supported extensions from given directories to Supervisely. Optionally, uploads pointclouds from subdirectories of given directories.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
dir_paths : List[str]¶: List of paths to directories with pointclouds.
recursive : bool, optional¶: If True, will upload pointclouds from subdirectories of given directories recursively. Otherwise, will upload pointclouds only from given directories.
change_name_if_conflict : bool, optional¶: If True adds suffix to the end of Pointclouds name when Dataset already contains an Pointclouds with identical name, If False and pointclouds with the identical names already exist in Dataset raises error.
progress_cb : Optional[Union[tqdm, Callable]]¶: Function for tracking upload progress.

Returns:

List of uploaded pointclouds infos

Return type:

List[Pointclouds]

upload_hash(dataset_id, name, hash, meta=None)¶

Upload Pointcloud from given hash to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
name : str¶: Point cloud name with extension.
hash : str¶: Point cloud hash.
meta : dict, optional¶: Point cloud metadata.

Returns:

Information about point cloud.

Return type:

PointcloudInfo

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

dst_dataset_id = 62693

src_pointcloud_id = 19618685
pcd_info = api.pointcloud.get_info_by_id(src_pointcloud_id)
hash, name, meta = pcd_info.hash, pcd_info.name, pcd_info.meta

new_pcd_info = api.pointcloud.upload_hash(dst_dataset_id.id, name, hash, meta)
print(new_pcd_info)

# Output:
# PointcloudInfo(
#     id=19619507,
#     frame=None,
#     description='',
#     name='0000000031.pcd',
#     team_id=None,
#     workspace_id=None,
#     project_id=None,
#     dataset_id=62694,
#     link=None,
#     hash='5w69Vv1i6JrqhU0Lw1UJAJFGPVWUzDG7O3f4QSwRfmE=',
#     path_original='/j8a9qgms4-public/point_clouds/I/3/6U/L7YBY.pcd',
#     cloud_mime='image/pcd',
#     figures_count=None,
#     objects_count=None,
#     tags=None,
#     meta={'frame': 31},
#     created_at='2023-04-05T10:59:44.656Z',
#     updated_at='2023-04-05T10:59:44.656Z'
# )

upload_hashes(dataset_id, names, hashes, metas=None, progress_cb=None)¶

Upload point clouds from given hashes to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: Point cloud name with extension.
hashes : List[str]¶: Point cloud hash.
metas : Optional[List[Dict]], optional¶: Point cloud metadata.
progress_cb : Progress, optional¶: Function for tracking upload progress.

Returns:

List of informations about Pointclouds.

Return type:

List[PointcloudInfo]

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

src_dataset_id = 62664
dst_dataset_id = 62690

src_pcd_infos = api.pointcloud.get_list(src_dataset_id)

names = [pcd.name for pcd in src_pcd_infos[:4]]
hashes = [pcd.hash for pcd in src_pcd_infos[:4]]
metas = [pcd.meta for pcd in src_pcd_infos[:4]]

dst_pcd_infos = api.pointcloud.get_list(dst_dataset_id)
print(f"{len(dst_pcd_infos)} pointcloud before upload.")
# Output:
# 0 pointcloud before upload.

new_pcd_infos = api.pointcloud.upload_hashes(dst_dataset_id, names, hashes, metas)
print(f"{len(new_pcd_infos)} pointcloud after upload.")
# Output:
# 4 pointcloud after upload.

upload_link(dataset_id, link, name=None, meta=None)¶

Upload point cloud from given link to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
link : str¶: Point cloud link.
name : str, optional¶: Point cloud name with extension.
meta : Dict, optional¶: Point cloud metadata.

Returns:

Information about point cloud.

Return type:

PointcloudInfo

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 = 62693
link = "https://example.com/pointclouds/scan1.pcd"
name = "scan1.pcd"

pcd_info = api.pointcloud.upload_link(dataset_id, link, name)
print(pcd_info)

upload_links(dataset_id, names, links, metas=None, progress_cb=None)¶

Upload point clouds from given links to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: Point cloud names with extension.
links : List[str]¶: Point cloud links.
metas : Optional[List[Dict]]¶: Point cloud metadatas.
progress_cb : Optional[Callable]¶: Function for tracking upload progress.

Returns:

List with information about Point clouds.

Return type:

List[PointcloudInfo]

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 = 62693
names = ["scan1.pcd", "scan2.pcd", "scan3.pcd"]
links = [
    "https://example.com/pointclouds/scan1.pcd",
    "https://example.com/pointclouds/scan2.pcd",
    "https://example.com/pointclouds/scan3.pcd",
]
pcd_infos = api.pointcloud.upload_links(dataset_id, names, links)
print(pcd_infos)

upload_path(dataset_id, name, path, meta=None)¶

Upload point cloud with given path to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
name : str¶: Point cloud name with extension.
path : str¶: Path to point cloud.
meta : Optional[Dict]¶: Dictionary with metadata for point cloud.

Returns:

Information about point cloud

Return type:

PointcloudInfo

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

pcd_file = "src/input/pcd/000000.pcd"
pcd_info = api.pointcloud.upload_path(dataset.id, name="pcd_0.pcd", path=pcd_file)
print(f'Point cloud "{pcd_info.name}" uploaded to Supervisely with ID:{pcd_info.id}')

# Output:
# Point cloud "pcd_0.pcd" uploaded to Supervisely with ID:19618685

upload_paths(dataset_id, names, paths, progress_cb=None, metas=None)¶

Upload point clouds with given paths to Dataset.

Parameters:

dataset_id : int¶: Dataset ID in Supervisely.
names : List[str]¶: Point clouds names with extension.
paths : List[str]¶: Paths to point clouds.
progress_cb : Progress, optional¶: Function for tracking upload progress.
metas : Optional[List[Dict]]¶: List of dictionary with metadata for point cloud.

Returns:

List of informations about point clouds.

Return type:

List[PointcloudInfo]

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

paths = ["src/input/pcd/000001.pcd", "src/input/pcd/000002.pcd"]
pcd_infos = api.pointcloud.upload_paths(dataset.id, names=["pcd_1.pcd", "pcd_2.pcd"], paths=paths)
print(f'Point clouds uploaded to Supervisely with IDs: {[pcd_info.id for pcd_info in pcd_infos]}')

# Output:
# Point clouds uploaded to Supervisely with IDs: [19618685, 19618686]

upload_paths_via_team_files(dataset_id, names, paths, metas=None, progress_cb=None)¶

Upload PLY/LAS/LAZ point clouds by first staging them in Team Files, then adding to dataset.

Use this method for formats not supported by the direct hash-based upload (.pcd only). Temporary files are removed from Team Files after the dataset entry is created.

upload_related_image(path)¶

Upload an image to the Supervisely. It generates us a hash for image.

Parameters:

path : str¶: Image path.

Returns:

Hash for image.

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

img_file = src/input/img/000000.png"
img_hash = api.pointcloud.upload_related_image(img_file)
print(img_hash)

# Output:
# +R6dFy8nMEq6k82vHLxuakpqVBmyTTPj5hXdPfjAv/c=

upload_related_images(paths, progress_cb=None)¶

Upload a batch of related images to the Supervisely. It generates us a hashes for images.

Parameters:

paths : List[str]¶: Images pathes.

Returns:

List of hashes for images.

Return type:

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

img_paths = ["src/input/img/000001.png", "src/input/img/000002.png"]
img_hashes = api.pointcloud.upload_related_images(img_paths)

# Output:
# [+R6dFy8nMEq6k82vHLxuakpqVBmyTTPjdfGdPfjAv/c=, +hfjbufnbkLhJb32vHLxuakpqVBmyTTPj5hXdPfhhj1c]

upload_team_files_ids(dataset_id, names, team_file_ids, metas=None, progress_cb=None)¶

Add point clouds already present in Team Files to a dataset by their file IDs.

Use when files are already uploaded to Team Files and you want to reference them directly without re-uploading.