Calculate Points in Point Cloud

SUMMARY

Calculate Points in Point Cloud returns the number of points in a point cloud.

It is a thin, remote-call wrapper equivalent to Python's own len(point_cloud) on a datatypes.PointCloud. Prefer len(point_cloud) locally when you already have the point cloud in hand; reach for this Skill only when you need the count without transferring or holding the full point cloud client-side.

Use this Skill when you want to get a point count from a point cloud that lives remotely, without pulling the full data back locally.

The Skill

from telekinesis import vitreous

num_points = vitreous.calculate_points_in_point_cloud(point_cloud=point_cloud)

API Reference

Full parameter and return type documentation for calculate_points_in_point_cloud.

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.

The Code

"""
Demonstrates counting the number of points in a point cloud.
"""

from loguru import logger

from telekinesis import vitreous, datatypes


def calculate_points_in_point_cloud_example():
    """
    Counts the number of points in a point cloud.

    Simple utility that returns the total point count.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = (
        "https://assets.telekinesis.ai/examples/v1/point_clouds/can_vertical_1_raw.ply"
    )
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    num_points = vitreous.calculate_points_in_point_cloud(point_cloud=point_cloud)

    # ===================== Log ================================================
    logger.success(f"Counted points in {point_cloud}")
    logger.success(f"Results: {num_points}")


if __name__ == "__main__":
    calculate_points_in_point_cloud_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_points_in_point_cloud.py

Parameter Configuration

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to count.

Returns

Type	Description
datatypes.Int	The point count N. Use .data for the raw Python int.

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_points_in_point_cloud takes only point_cloud — there is nothing to tune. It has no parameters that change how the count is computed; it simply reports the number of points currently in the cloud.

Where to Use the Skill

Common pipelines include:

• Remote pipeline validation – confirming a filtering or downsampling step reduced (or didn't unexpectedly zero out) the point count, without pulling the point cloud back client-side
• Conditional branching – skipping downstream processing when too few points remain after filtering, based on a count fetched remotely
• Monitoring server-side pipelines – checking the size of a point cloud that is produced and consumed entirely on the server, where transferring the full cloud locally just to call len() would be wasteful

Alternative Skills

Skill	vs. Calculate Points in Point Cloud
len(point_cloud) (local Python, not a Vitreous Skill)	Equivalent result, computed instantly with no network round trip. Prefer this whenever you already have the datatypes.PointCloud object in hand locally.

When Not to Use the Skill

Do not use Calculate Points in Point Cloud when:

• You already have the point cloud locally — call Python's own len(point_cloud) instead; it's equivalent and doesn't incur a network round trip.
• You're checking the count repeatedly in a tight loop — a remote call per iteration adds latency that a local len() doesn't have.
• You need to validate the point cloud itself (e.g. check it isn't empty) — an empty point cloud simply returns a count of 0 rather than raising an error, so validate the input directly if that distinction matters to your pipeline.

TIP

This Skill exists for one specific case: getting the count without transferring or holding the full point cloud client-side — for example, when the cloud lives entirely server-side as part of a longer pipeline. If you already have the datatypes.PointCloud object in Python, call len(point_cloud) instead.