Calculate Point Cloud Centroid

SUMMARY

Calculate Point Cloud Centroid computes the geometric center of a 3D point cloud by averaging the positions of all points.

This Skill is often used to obtain a single representative position for an object or region in space, such as the approximate location of an object, cluster, or segmented surface. The centroid is commonly used for visualization, alignment, initialization of algorithms, or as a reference point in motion planning.

Use this Skill when you need a simple and reliable spatial anchor for a point cloud, especially after filtering, clustering, or segmentation steps in a pipeline.

The Skill

from telekinesis import vitreous

centroid = vitreous.calculate_point_cloud_centroid(point_cloud=point_cloud)

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

Raw Sensor Input

Unprocessed point cloud captured directly from the sensor. Shows full resolution, natural noise, and uneven sampling density.

Calculated Centroid with World Orientation

Frame visualises the position of the centroid with world orientation.

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 cloud
filepath = str(DATA_DIR / "point_clouds" / "can_vertical_3_subtracted.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

# Execute operation
centroid = vitreous.calculate_point_cloud_centroid(point_cloud=point_cloud)
logger.success(
  f"Calculated centroid {centroid} for {len(point_cloud.positions)} points"
)

The Explanation of the Code

This example demonstrates how to use the calculate_point_cloud_centroid Skill to compute the geometric center of a 3D point cloud. After importing the necessary modules and setting up optional logging, the point cloud is loaded from a .ply file.

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 cloud
filepath = str(DATA_DIR / "point_clouds" / "can_vertical_3_subtracted.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

The Skill calculates the centroid by averaging the positions of all points in the cloud, returning a single 3D coordinate representing the cloud’s center. The logger prints the resulting centroid, which can be used in downstream tasks.

# Execute operation
centroid = vitreous.calculate_point_cloud_centroid(point_cloud=point_cloud)
logger.success(
  f"Calculated centroid {centroid} for {len(point_cloud.positions)} points"
)

This Skill is particularly useful in robotics pipelines for object localization, grasping, alignment, or reference frame computation, where knowing the central point of a point cloud aids in planning motions, estimating object poses, or normalizing coordinates for further processing.

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 calculate_point_cloud_centroid

How to Tune the Parameters

The calculate_point_cloud_centroid Skill has no parameters to tune, it only requires a point cloud as input. The centroid is computed by averaging all point positions, so the result depends on the input point cloud's distribution.

Where to Use the Skill in a Pipeline

Point cloud centroid calculation is commonly used in the following pipelines:

• Object localization and tracking
• Clustering and segmentation analysis
• Grasp planning and manipulation
• Reference frame computation

A typical pipeline for object localization and tracking looks as follows:

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

from telekinesis import vitreous

# 1. Load raw point cloud
... = vitreous.load_point_cloud(...)

# 2. Preprocess: remove outliers and downsample
... = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)
... = vitreous.filter_point_cloud_using_voxel_downsampling(...)

# 3. Cluster to separate objects
clusters = vitreous.cluster_point_cloud_using_dbscan(...)

# 4. For each cluster, compute centroid
for cluster in clusters:
    centroid = vitreous.calculate_point_cloud_centroid(point_cloud=cluster)
    # Use centroid for object localization or as reference point

# 5. Optional: Use centroid for grasp planning or motion planning

Related skills to build such a pipeline:

• filter_point_cloud_using_statistical_outlier_removal: clean input before centroid computation
• filter_point_cloud_using_voxel_downsampling: reduce point cloud density for faster processing
• cluster_point_cloud_using_dbscan: separate objects before computing individual centroids
• calculate_axis_aligned_bounding_box: alternative when you also need size/extent information
• calculate_oriented_bounding_box: alternative when you also need size, extent, and orientation

Alternative Skills

Skill	vs. Calculate Point Cloud Centroid
calculate_axis_aligned_bounding_box	Use centroid when you only need the center position. Use AABB when you also need size/extent information.
calculate_oriented_bounding_box	Use centroid when you only need the center position. Use OBB when you also need size/extent and orientation information.

When Not to Use the Skill

Do not use calculate point cloud centroid when:

• You need size or extent information (use calculate_axis_aligned_bounding_box or calculate_oriented_bounding_box instead)
• You need orientation information (use calculate_oriented_bounding_box instead)
• The point cloud has uneven density (the centroid may be biased toward dense regions)
• You need a weighted center (centroid gives equal weight to all points, regardless of density)

WARNING

The centroid gives equal weight to all points. If your point cloud has uneven sampling density, the centroid may not represent the true geometric center of the object.