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_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.
`remove`	Remove an entity with the specified ID from the Supervisely server.
`remove_batch`	Remove entities in batches from the Supervisely server.
`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

add_related_images(images_json, camera_names=None)[source]¶

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.

Returns

List of point clouds hashes.

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_related_image(id, path)[source]¶

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

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

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

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

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.

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_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.
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.
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.
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.
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_related_image(path)[source]¶

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_related_images(paths, progress_cb=None)[source]¶

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]