Add Point Clouds

SUMMARY

Add Point Clouds concatenates every point from two point clouds into one combined point cloud.

It performs a simple union: every point from point_cloud1 and point_cloud2 ends up in the result, with no deduplication and no distance check between them. Compare with subtract_point_clouds, which removes overlapping points instead of merging them in. Useful for merging multiple sensor captures, or recombining clusters/regions produced by Skills like cluster_point_cloud_using_dbscan or cluster_point_cloud_based_on_density_jump.

Use this Skill when you want to merge two point clouds into a single combined cloud, such as fusing multiple sensor views or recombining previously-split regions.

The Skill

from telekinesis import vitreous

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

API Reference

Full parameter and return type documentation for add_point_clouds.

View Reference →

Data Transfer Notice

There is no longer a fixed limit of 1 million points per request. However, very large datasets may result in slower data transfer and processing times. We are continuously optimizing performance as part of our beta program, with ongoing improvements to enhance speed and reliability.

Example

Input Point Cloud 1

Input Point Cloud 2

Output Point Cloud

The Code

"""
Demonstrates merging two point clouds into a single cloud.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def add_point_clouds_example():
    """
    Merges two point clouds into a single cloud.

    Combines all points from both clouds into one unified point cloud.
    """
    # ===================== Load Data ==========================================
    point_cloud_url_1 = "https://assets.telekinesis.ai/examples/v1/point_clouds/can_vertical_3_clustered.ply"
    point_cloud_url_2 = "https://assets.telekinesis.ai/examples/v1/point_clouds/can_vertical_3_segmented_plane.ply"
    point_cloud1 = datatypes.PointCloud.from_url(url=point_cloud_url_1, use_cache=True)
    point_cloud2 = datatypes.PointCloud.from_url(url=point_cloud_url_2, use_cache=True)

    # ===================== Run Skill ==========================================
    added_point_cloud = vitreous.add_point_clouds(
        point_cloud1=point_cloud1, point_cloud2=point_cloud2
    )

    # ===================== Log ================================================
    logger.success(f"Added {point_cloud1} and {point_cloud2}")
    logger.success(f"Results: {added_point_cloud}")
    logger.info(
        f"Added point cloud positions shape: {added_point_cloud.positions.shape}"
    )
    logger.info(
        f"Added point cloud normals shape: "
        f"{added_point_cloud.normals.shape if added_point_cloud.has_normals else None}"
    )
    logger.info(
        f"Added point cloud colors shape: "
        f"{added_point_cloud.colors.shape if added_point_cloud.has_colors else None}"
    )

    # ===================== Visualization  (Optional) ===========================
    rr.init("add_point_clouds_example", spawn=True)
    datatypes.visualize(point_cloud1, entity_path="/1-point_cloud_1")
    datatypes.visualize(point_cloud2, entity_path="/2-point_cloud_2")
    datatypes.visualize(added_point_cloud, entity_path="/3-added_point_cloud")


if __name__ == "__main__":
    add_point_clouds_example()

Runnable examples are available in the Telekinesis examples repository.

Follow the README in that repository to set up the environment, run this specific example with:

cd telekinesis-examples
python examples/point_cloud/add_point_clouds.py

Parameter Configuration

Key	Type	Default	Description
point_cloud1	datatypes.PointCloud	required	The first point cloud
point_cloud2	datatypes.PointCloud	required	The second point cloud

Returns

Type	Description
datatypes.PointCloud	Every point from both inputs, concatenated. Use .positions for the combined (N1 + N2, 3) position array and len(...) for the total point count.

Raises

Exception	Condition
TypeError	A parameter is not a datatypes.PointCloud (see the Parameter Configuration table above)
ConfigurationError	The TELEKINESIS_API_KEY environment variable is not set
SerializationError	The request input failed to serialize, or the response failed to deserialize
RequestTimeoutError	The request to the Vitreous service timed out
TransportError	A network failure occurred before a response was received
ClientError	The Vitreous service rejected the request due to invalid input, invalid data, or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired
AuthenticationServiceError	The authentication service was unavailable
ServerError	The Vitreous service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

add_point_clouds takes only the two point clouds to merge — there is no parameter that changes how the merge happens; it is always a full concatenation with no deduplication. What matters is how you prepare the inputs beforehand:

• Coordinate frames: both point clouds must already be in the same coordinate frame before adding — align one to the other first with apply_transform_to_point_cloud if they aren't
• Density: because there is no deduplication, regions where the two inputs overlap will end up with roughly double the point density in the result
• Size: the output always has exactly len(point_cloud1) + len(point_cloud2) points, so memory use grows linearly with both inputs

TIP

If the two inputs overlap spatially, follow up with filter_point_cloud_using_voxel_downsampling to bring the merged region back to a uniform density.

Where to Use the Skill

Common pipelines include:

• Multi-view fusion – combine point clouds captured from different sensor viewpoints into one scene
• Temporal accumulation – merge successive depth frames of a static scene over time
• Recombining split regions – merge clusters or segmented regions produced by cluster_point_cloud_using_dbscan back into a larger cloud
• Sensor aggregation – merge scans from multiple depth cameras after aligning them with apply_transform_to_point_cloud

Alternative Skills

Skill	vs. Add Point Clouds
subtract_point_clouds	The reverse operation: removes points near another cloud instead of merging them in. Use it to isolate a difference instead of building a union.
apply_transform_to_point_cloud	Aligns a point cloud into a common coordinate frame. Run it on one or both inputs before adding them if they were captured in different frames.

When Not to Use the Skill

Do not use Add Point Clouds when:

• The point clouds are in different coordinate frames — align them first with apply_transform_to_point_cloud, otherwise the merged result will be spatially inconsistent
• You want to remove overlapping points instead of keeping both copies — use subtract_point_clouds instead; add_point_clouds performs no deduplication or distance check
• You need the result to stay at a bounded, uniform density — plan to downsample afterward, since the output always contains every point from both inputs

TIP

Because there is no deduplication, adding two point clouds that describe the same surface (e.g. two overlapping scans) roughly doubles the point density there. If uniform density matters downstream, follow up with filter_point_cloud_using_voxel_downsampling.