Subtract Point Clouds

SUMMARY

Subtract Point Clouds removes points from a source point cloud that are within a specified distance of points in a target point cloud.

This Skill is useful in industrial, mobile, and humanoid robotics pipelines for isolating objects or removing known surfaces. For example, it can remove a table surface to isolate parts in manufacturing, subtract previously mapped areas in mobile robot SLAM, or exclude static background objects for humanoid robot perception. Subtracting point clouds helps focus processing on regions of interest and reduces clutter.

Use this Skill when you want to filter out points that overlap with another point cloud to isolate or highlight remaining structures.

The Skill

from telekinesis import vitreous

subtracted_point_cloud = vitreous.subtract_point_clouds(
    point_cloud1=point_cloud1,
    point_cloud2=point_cloud2,
    distance_threshold=0.1,
)

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

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" / "zivid_mixed_grocery_pallet_centered.ply")
filepath2 = str(DATA_DIR / "point_clouds" / "zivid_mixed_grocery_pallet_box_filtered.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
subtracted_point_cloud = vitreous.subtract_point_clouds(
  point_cloud1=point_cloud1,
  point_cloud2=point_cloud2,
  distance_threshold=0.1,
)
logger.success("Subtracted point clouds")

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:

cd telekinesis-examples
python examples/vitreous_examples.py --example subtract_point_clouds

The Explanation of the Code

The script starts by importing the necessary modules for point cloud processing (vitreous), data handling (datatypes, io), file management (pathlib), and optional logging (loguru).

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

# Optional for logging
from loguru import logger

Next, two point clouds are loaded from disk. Logging confirms that both clouds are successfully loaded and shows the number of points in each, providing insight into dataset size and complexity.

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

# Load point clouds
filepath1 = str(DATA_DIR / "point_clouds" / "zivid_mixed_grocery_pallet_centered.ply")
filepath2 = str(DATA_DIR / "point_clouds" / "zivid_mixed_grocery_pallet_box_filtered.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")

The main operation applies the subtract_point_clouds Skill. This Skill removes points from the first point cloud (point_cloud1) that are within a specified distance of any point in the second point cloud (point_cloud2). The distance_threshold parameter controls how close points must be to be considered overlapping. This operation is useful in industrial and mobile robotics pipelines for tasks such as background removal, isolating dynamic objects from static environments, or cleaning a scene before object detection or registration.

# Execute operation
subtracted_point_cloud = vitreous.subtract_point_clouds(
  point_cloud1=point_cloud1,
  point_cloud2=point_cloud2,
  distance_threshold=0.1,
)
logger.success("Subtracted point clouds")

How to Tune the Parameters

The subtract_point_clouds Skill has one parameter that controls the subtraction behavior:

distance_threshold (required):

• The maximum distance to consider points as "near" each other
• Units: Uses the same units as your point cloud (e.g., if point cloud is in meters, threshold is in meters; if in millimeters, threshold is in millimeters)
• Any point in point_cloud1 within this distance of any point in point_cloud2 will be removed
• Increase to remove more points (more aggressive subtraction)
• Decrease to remove fewer points (more precise, only very close points)
• Should be set based on point cloud density and desired precision:
  • Millimeter-scale point clouds (e.g., Zivid where 1 unit = 1 mm): Typical values 1-100 (representing 1-100 mm distance)
  • Centimeter-scale point clouds (e.g., 1 unit = 1 cm): Typical values 0.1-10 (representing 0.1-10 cm distance)
  • Meter-scale point clouds (e.g., 1 unit = 1 m): Typical values 0.001-0.1 (representing 0.001-0.1 m distance)
• Use smaller values for precise subtraction, larger values for aggressive subtraction

TIP

Best practice: Start with a small threshold (e.g., 0.01 in point cloud units) and gradually increase if you need more aggressive subtraction. Consider the typical spacing between points in your point cloud when choosing the threshold.

Where to Use the Skill in a Pipeline

Point cloud subtraction is commonly used in the following pipelines:

• Background removal and object isolation
• Dynamic object detection
• Scene cleaning before object detection
• SLAM and mapping applications

A typical pipeline for object isolation looks as follows:

# Example pipeline using point cloud subtraction (parameters omitted).

from telekinesis import vitreous

# 1. Load or capture point clouds
scene_cloud = vitreous.load_point_cloud(...)  # Full scene
background_cloud = vitreous.load_point_cloud(...)  # Background/table surface

# 2. Preprocess both point clouds
filtered_scene = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)
filtered_background = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)

# 3. Subtract background from scene
isolated_objects = vitreous.subtract_point_clouds(
    point_cloud1=filtered_scene,
    point_cloud2=filtered_background,
    distance_threshold=0.01,
)

# 4. Cluster remaining objects
clusters = vitreous.cluster_point_cloud_using_dbscan(
    point_cloud=isolated_objects,
    max_distance=0.5,
    min_points=10,
)

# 5. Process each isolated object
for cluster in clusters:
    # Compute bounding box, centroid, etc.
    bbox = vitreous.calculate_oriented_bounding_box(point_cloud=cluster)

Related skills to build such a pipeline:

• filter_point_cloud_using_statistical_outlier_removal: clean input point clouds before subtraction
• filter_point_cloud_using_voxel_downsampling: reduce point cloud density for faster processing
• cluster_point_cloud_using_dbscan: cluster isolated objects after subtraction
• calculate_oriented_bounding_box: compute bounding box for isolated objects
• filter_point_cloud_using_bounding_box: alternative method to crop point clouds

Alternative Skills

Skill	vs. Subtract Point Clouds
filter_point_cloud_using_bounding_box	Use bounding box filter when you want to crop based on geometric bounds. Use subtract point clouds when you want to remove points based on proximity to another point cloud.

When Not to Use the Skill

Do not use subtract point clouds when:

• You want to crop based on geometric bounds (use filter_point_cloud_using_bounding_box instead)
• The point clouds are in different coordinate frames (align them first using registration)
• You need to preserve points that are very close (the distance threshold may be too large)
• The reference point cloud (point_cloud2) is empty or invalid (the operation may not work as expected)
• You need to subtract multiple point clouds (you may need to chain multiple subtraction operations)

WARNING

This Skill removes points from point_cloud1 that are near any point in point_cloud2. If point_cloud2 is very dense or covers a large area, many points may be removed. Ensure point_cloud2 accurately represents what you want to subtract.