PointcloudApi

class PointcloudApi[source]

Bases: supervisely.api.module_api.RemoveableBulkModuleApi

API for working with Pointcloud. PointcloudApi object is immutable.

Parameters
api : Api

API connection to the server.

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

# Pass values into the API constructor (optional, not recommended)
# api = sly.Api(server_address="https://app.supervise.ly", token="4r47N...xaTatb")

pcd_id = 19618654
pcd_info = api.pointcloud.get_info_by_id(pcd_id) # api usage example

Methods

add_related_images

Attach images to point cloud.

check_existing_hashes

Check if point clouds with given hashes are exist.

download_path

Download point cloud with given id on the given path.

download_related_image

Download 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_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<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_related_images

Get information about related context images.

info_sequence

Get list of all PointcloudInfo field names.

info_tuple_name

Get string name of PointcloudInfo NamedTuple.

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.

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_path

Upload point cloud with given path to Dataset.

upload_paths

Upload point clouds with given paths to Dataset.

upload_related_image

Upload an image to the Supervisely.

upload_related_images

Upload a batch of related images to the Supervisely.

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

Attach images to point cloud.

Parameters
images_json : List[Dict]

List of dictionaries with dataset id, image name, hash and meta.

camera_names : List[Dict]

List of camera informations.

Returns

Response object

Return type

Dict

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

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)
check_existing_hashes(hashes)[source]

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

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

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

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

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

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

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_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_free_names(dataset_id, names)[source]

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

Get point cloud information by ID in PointcloudInfo<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. See info_sequence

Return type

PointcloudInfo

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

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 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(dataset_id, filters=None)[source]

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://dev.supervise.ly/api-docs/#tag/Point-Clouds/paths/~1point-clouds.list/get

Returns

List of the point clouds objects from the dataset with given id.

Return type

List[PointcloudInfo]

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

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

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

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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://dev.supervise.ly/hs4-public/images/original/S/j/hJ/PwMg.png',
#     'name': 'img00'
# }
static info_sequence()[source]

Get list of all PointcloudInfo field names.

Returns

List of PointcloudInfo field names.`

Return type

list

static info_tuple_name()[source]

Get string name of PointcloudInfo NamedTuple.

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.pointcloud.info_tuple_name()
print(tuple_name) # PointCloudInfo
raise_name_intersections_if_exist(dataset_id, names, message=None)[source]

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 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_dir(dataset_id, dir_path, recursive=True, change_name_if_conflict=True, progress_cb=None)[source]

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

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

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

Return type

PointcloudInfo

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

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

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

Return type

List[PointcloudInfo]

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

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_path(dataset_id, name, path, meta=None)[source]

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

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

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

os.environ['SERVER_ADDRESS'] = 'https://app.supervise.ly'
os.environ['API_TOKEN'] = 'Your Supervisely API Token'
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 an image to the Supervisely. It generates us a hash for image.

Parameters
path : str

Image path.

Returns

Hash for image. See info_sequence

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

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

# Output:
# +R6dFy8nMEq6k82vHLxuakpqVBmyTTPj5hXdPfjAv/c=

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

Return type

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

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]