Telekinesis Docs

Appearance

Add Point Clouds ​

SUMMARY

Add Point Clouds combines two or more point clouds into a single point cloud by merging their points into a common representation.

This Skill is commonly used when building multi-view or multi-sensor pipelines, such as aggregating successive depth frames, fusing scans from different viewpoints, or accumulating data over time. It enables larger, more complete scene representations that can then be processed by downstream Skills like filtering, registration, or segmentation.

Use this Skill when you want to accumulate spatial information across multiple observations. The resulting point cloud may require additional preprocessing (such as downsampling or outlier removal) to maintain uniform density and performance.

The Skill ​

python
from telekinesis import vitreous

combined_point_cloud = vitreous.add_point_clouds(
    point_cloud1=point_cloud1,
    point_cloud2=point_cloud2,
)

API Reference

Performance Note

Current Data Limits: The system currently supports up to 1 million points per request (approximately 16MB of data). We're actively optimizing data transfer performance as part of our beta program, with improvements rolling out regularly to enhance processing speed.

Example ​

Input Point Cloud 1

Input Point Cloud 2

Output Point Cloud

The Code ​

python
from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib

# Optional for logging
from loguru import logger

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load point clouds
filepath1 = str(DATA_DIR / "point_clouds" / "can_vertical_3_clustered.ply")
filepath2 = str(DATA_DIR / "point_clouds" / "can_vertical_3_segmented_plane.ply")
point_cloud1 = io.load_point_cloud(filepath=filepath1)
point_cloud2 = io.load_point_cloud(filepath=filepath2)
logger.success(f"Loaded point cloud 1 with {len(point_cloud1.positions)} points")
logger.success(f"Loaded point cloud 2 with {len(point_cloud2.positions)} points")

# Execute operation
added_point_cloud = vitreous.add_point_clouds(
  point_cloud1=point_cloud1, point_cloud2=point_cloud2
)
logger.success(
  f"Added point clouds: {len(point_cloud1.positions)} + {len(point_cloud2.positions)} points"
)

The Explanation of the Code ​

The example starts by importing the necessary modules from the Telekinesis SDK and Python standard libraries, along with the logger for optional feedback. These imports give you access to the point cloud manipulation Skills, file I/O, and convenient logging.

python
from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib

# Optional for logging
from loguru import logger

Next, the code sets the path to your data directory and constructs the file paths for two point clouds. Using the io.load_point_cloud function, it loads both point clouds into memory. The logger statements provide a quick check that the point clouds have been loaded correctly and display how many points each contains. This is especially useful for debugging and ensuring that your input data is valid before performing any operations.

python
DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load point clouds
filepath1 = str(DATA_DIR / "point_clouds" / "can_vertical_3_clustered.ply")
filepath2 = str(DATA_DIR / "point_clouds" / "can_vertical_3_segmented_plane.ply")
point_cloud1 = io.load_point_cloud(filepath=filepath1)
point_cloud2 = io.load_point_cloud(filepath=filepath2)
logger.success(f"Loaded point cloud 1 with {len(point_cloud1.positions)} points")
logger.success(f"Loaded point cloud 2 with {len(point_cloud2.positions)} points")

Finally, the add_point_clouds Skill is applied to merge the two point clouds into a single unified cloud. This operation is essential when combining multiple scans, partial captures, or layers of a scene.

python
# Execute operation
added_point_cloud = vitreous.add_point_clouds(
  point_cloud1=point_cloud1, point_cloud2=point_cloud2
)

After execution, the logger reports the total number of points in the merged cloud, giving instant feedback that the operation completed successfully.

python
# Optional for logging
from loguru import logger

This workflow is simple yet powerful, enabling you to combine multiple 3D scans into one cohesive point cloud, which can then be used for downstream tasks such as segmentation, clustering, registration, or visualization.

Running the Example ​

Runnable examples are available in the Telekinesis examples repository. Follow the README in that repository to set up the environment. Once set up, you can run this specific example with:

bash
cd telekinesis-examples
python examples/vitreous_examples.py --example add_point_clouds

How to Tune the Parameters ​

The add_point_clouds Skill has no parameters to tune, it only requires two point clouds as input. The Skill simply combines all points from both point clouds into a single unified point cloud.

Important considerations:

  • Coordinate frames: Ensure both point clouds are in the same coordinate frame. If they are not, apply transformations first using apply_transform_to_point_cloud
  • Point density: The combined point cloud may have uneven density if the input clouds have different densities
  • Memory usage: The resulting point cloud will contain all points from both inputs, which may be large

TIP

Best practice: After adding point clouds, consider using filter_point_cloud_using_voxel_downsampling to maintain uniform density and reduce memory usage, especially if the point clouds overlap significantly.

Where to Use the Skill in a Pipeline ​

Point cloud addition is commonly used in the following pipelines:

  • Multi-view or multi-sensor fusion
  • Temporal accumulation of scans
  • Combining segmented regions
  • Building complete scene representations

A typical pipeline for multi-view fusion looks as follows:

python
# Example pipeline using point cloud addition (parameters omitted).

from telekinesis import vitreous

# 1. Load or capture point clouds from different viewpoints
view1_cloud = vitreous.load_point_cloud(...)
view2_cloud = vitreous.load_point_cloud(...)

# 2. Optional: Apply transforms if point clouds are in different coordinate frames
transformed_view2 = vitreous.apply_transform_to_point_cloud(
    point_cloud=view2_cloud,
    transformation_matrix=transform_matrix,
)

# 3. Combine point clouds
combined_cloud = vitreous.add_point_clouds(
    point_cloud1=view1_cloud,
    point_cloud2=transformed_view2,
)

# 4. Optional: Downsample to maintain uniform density
downsampled_cloud = vitreous.filter_point_cloud_using_voxel_downsampling(
    point_cloud=combined_cloud,
    voxel_size=0.01,
)

# 5. Optional: Remove outliers
filtered_cloud = vitreous.filter_point_cloud_using_statistical_outlier_removal(
    point_cloud=downsampled_cloud,
)

# 6. Process the combined point cloud
clusters = vitreous.cluster_point_cloud_using_dbscan(...)

Related skills to build such a pipeline:

  • apply_transform_to_point_cloud: align point clouds before adding
  • filter_point_cloud_using_voxel_downsampling: maintain uniform density after adding
  • filter_point_cloud_using_statistical_outlier_removal: clean the combined point cloud
  • cluster_point_cloud_using_dbscan: cluster objects in the combined scene

Alternative Skills ​

There are no direct alternative skills for adding point clouds. This Skill is the primary method for combining multiple point clouds into one.

When Not to Use the Skill ​

Do not use add point clouds when:

  • Point clouds are in different coordinate frames (apply transforms first using apply_transform_to_point_cloud)
  • You want to subtract one point cloud from another (use subtract_point_clouds instead)
  • You need to merge only overlapping regions (consider registration or alignment first)
  • Memory is constrained (the combined point cloud may be very large)
  • You need to preserve point cloud metadata separately (adding merges points but may not preserve all metadata)