Calculate Point Cloud Centroid

SUMMARY

Calculate Point Cloud Centroid computes the mean [x, y, z] position of every point in a point cloud.

It averages the point cloud's positions (normals and colors are ignored) to produce a single 3D point representing the cloud's geometric center — a common building block, for example as the center_point for scale_point_cloud, or to compare two point clouds' rough positions before fine registration.

Use this Skill when you need a single representative position for a point cloud, cluster, or segmented region.

The Skill

from telekinesis import vitreous

centroid = vitreous.calculate_point_cloud_centroid(point_cloud=point_cloud)

API Reference

Full parameter and return type documentation for calculate_point_cloud_centroid.

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

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

"""
Demonstrates computing the geometric center (centroid) of a point cloud.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def calculate_point_cloud_centroid_example():
    """
    Computes the geometric center (centroid) of a point cloud.

    Calculates the mean position of all points in the cloud.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = "https://assets.telekinesis.ai/examples/v1/point_clouds/zivid_large_pcb_inspection_cropped_preprocessed.ply"
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    # `calculate_point_cloud_centroid` returns a Point3D datatype instance.
    centroid = vitreous.calculate_point_cloud_centroid(point_cloud=point_cloud)

    # ===================== Log ================================================
    logger.success(f"Calculated centroid for {point_cloud}")
    logger.success(f"Results: {centroid}")
    logger.info(f"Centroid data: {centroid.data}")
    logger.info(f"Centroid shape: {centroid.shape}")
    logger.info(f"Centroid dtype: {centroid.dtype}")

    # ===================== Visualization  (Optional) ===========================
    rr.init("calculate_point_cloud_centroid_example", spawn=True)
    datatypes.visualize(point_cloud, entity_path="/point_cloud")
    datatypes.visualize(centroid, entity_path="/centroid", label="Centroid")


if __name__ == "__main__":
    calculate_point_cloud_centroid_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/calculate_point_cloud_centroid.py

Parameter Configuration

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to average. Only positions are used; normals/colors are ignored.

Returns

Type	Description
datatypes.Point3D	The mean position [cx, cy, cz] of all points, in meters (same units as the input point cloud's positions). Use .data for the raw (3,) array.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (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

calculate_point_cloud_centroid takes only point_cloud — there is nothing to tune. The centroid is the unweighted mean of every point's position, so the result depends entirely on the input point cloud's distribution.

If the centroid looks skewed toward one side of the object, that's usually because the point cloud has uneven sampling density or includes points that don't belong to the object. Isolate the object first with cluster_point_cloud_using_dbscan or clean it with filter_point_cloud_using_statistical_outlier_removal before computing the centroid.

Where to Use the Skill

Common pipelines include:

• Per-cluster position estimation – computing a representative position for each object after cluster_point_cloud_using_dbscan separates a scene into individual objects
• Scale/transform anchoring – using the centroid as the center_point argument for scale_point_cloud
• Coarse registration – comparing two point clouds' centroids as a quick check before running a finer registration/alignment step
• Reference point for motion planning – using the centroid as an approach point or waypoint target

Alternative Skills

Skill	vs. Calculate Point Cloud Centroid
calculate_axis_aligned_bounding_box	Also exposes a .center, plus size information (.width/.height/.depth/.volume). Use it when you need extent, not just a position — note its .center is the midpoint of the box's extent, not the mean of the points, so the two won't generally match exactly.
calculate_oriented_bounding_box	Same trade-off as the axis-aligned box, plus orientation information. Use it when you need extent and orientation, not just a position.

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 strongly uneven sampling density — the centroid is biased toward denser regions and may not represent the object's true geometric center.

TIP

If you already need a bounding box for other reasons, its .center is a free source of a representative position — but remember it's the midpoint of the box's extent, not the mean of the points, so it won't exactly match calculate_point_cloud_centroid for an irregularly-shaped or unevenly-sampled object.