Filter Point Cloud Using Uniform Downsampling

SUMMARY

Filter Point Cloud Using Uniform Downsampling shrinks a point cloud by keeping every step_size-th point by index.

Points are selected at fixed index intervals (0, step_size, 2 * step_size, ...) rather than by spatial position — the fastest downsampling method in Vitreous, since it doesn't need to look at point coordinates at all. Because it ignores spatial density, it isn't equivalent to filter_point_cloud_using_voxel_downsampling when the input's point density varies across the cloud: a dense region and a sparse region both get thinned by the same fixed factor, rather than being evened out.

Use this Skill when you want to quickly shrink a point cloud as cheaply as possible, and don't need the result to be spatially uniform.

The Skill

from telekinesis import vitreous

filtered_point_cloud = vitreous.filter_point_cloud_using_uniform_downsampling(
    point_cloud=point_cloud,
    step_size=20,
)

API Reference

Full parameter and return type documentation for filter_point_cloud_using_uniform_downsampling.

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.

Moderate Downsampling

Light reduction that keeps the global structure while making further processing significantly lighter. Note that dense areas are still dense relative to sparse ones.
Parameters: step_size = 5.

Aggressive Downsampling

Aggressive thinning for fast previewing or early-stage pipeline testing
Parameters: step_size = 20

The Code

"""
Demonstrates downsampling a point cloud by selecting every Nth point.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def filter_point_cloud_using_uniform_downsampling_example():
    """
    Downsamples a point cloud by selecting every Nth point.

    Uniformly samples points by selecting every step_size-th point from the
    original cloud.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = (
        "https://assets.telekinesis.ai/examples/v1/point_clouds/zivid_welding_scene.ply"
    )
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    filtered_point_cloud = vitreous.filter_point_cloud_using_uniform_downsampling(
        step_size=20, point_cloud=point_cloud
    )

    # ===================== Log ================================================
    logger.success(f"Filtered {point_cloud} using uniform downsampling")
    logger.success(f"Results: {filtered_point_cloud}")
    logger.info(
        f"Filtered point cloud positions shape: {filtered_point_cloud.positions.shape}"
    )
    logger.info(
        f"Filtered point cloud has normals shape: "
        f"{filtered_point_cloud.normals.shape if filtered_point_cloud.has_normals else None}"
    )
    logger.info(
        f"Filtered point cloud has colors shape: "
        f"{filtered_point_cloud.colors.shape if filtered_point_cloud.has_colors else None}"
    )

    # ===================== Visualization  (Optional) ===========================
    rr.init("filter_point_cloud_using_uniform_downsampling_example", spawn=True)
    datatypes.visualize(point_cloud, entity_path="/1-input_point_cloud")
    datatypes.visualize(filtered_point_cloud, entity_path="/2-filtered_point_cloud")


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

Parameter Configuration

Parameter	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to downsample
step_size	datatypes.Int | int	required	The interval between kept points — every step_size-th point is kept. Must be >= 1

Returns

Type	Description
datatypes.PointCloud	A point cloud with roughly 1/step_size of the original points. Use .positions for the surviving (N, 3) position array and len(...) for the point count.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above)
ValueError	step_size is not > 0
ConfigurationError	The TELEKINESIS_API_KEY environment variable is not set
SerializationError	The request input failed to serialize, the response was not returned as an Arrow stream, 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 or malformed input (HTTP 400/422), an unrecognized endpoint (HTTP 404), or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired (HTTP 401)
AuthenticationServiceError	The authentication service returned an invalid response, was temporarily unavailable, or timed out (HTTP 502/503/504)
ServerError	The Vitreous service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

The filter_point_cloud_using_uniform_downsampling Skill exposes one parameter that controls how aggressively the cloud is thinned.

step_size

• Controls: The index interval between kept points. The output has roughly original_count / step_size points.
• Units: Count (integer), must be >= 1
• Default: required — no default
• Increase → reduces the point count more aggressively (a sparser output)
• Decrease → keeps more points, preserving more detail
• Typical range: 2–100 — use 2–5 for light downsampling, 5–20 for moderate, 20–100 for aggressive

TIP

step_size looks at point index, not position — if your point cloud's density varies across the scene (common with real sensor data), the output will inherit that same uneven density. If you need an evenly-spaced result instead, use filter_point_cloud_using_voxel_downsampling.

Where to Use the Skill

Common pipelines include:

• Fast preprocessing – shrinking a cloud as cheaply as possible before heavier downstream skills
• Quick preview generation – producing a lightweight preview for visualization or interactive tools
• Reducing computation time – cutting point count before clustering or registration when raw speed matters more than uniformity
• Early-stage pipeline testing – iterating quickly on a pipeline with a smaller, cheaper-to-process cloud

Alternative Skills

Skill	vs. Filter Point Cloud Using Uniform Downsampling
filter_point_cloud_using_voxel_downsampling	Buckets points into cubic voxels and averages each bucket, accounting for actual spatial density and producing a roughly evenly-spaced result. Use it instead when point density varies across the cloud and you need spatial uniformity, not just a smaller file.

When Not to Use the Skill

Do not use Filter Point Cloud Using Uniform Downsampling when:

• The input's point density varies across the cloud – keeping every Nth point by index doesn't even out density; use filter_point_cloud_using_voxel_downsampling instead
• You need a spatially uniform result – dense regions will remain proportionally denser than sparse ones after this filter
• You need to preserve fine geometric detail – any fixed-interval downsampling discards information, and this method has no way to protect small or thin structures
• The point cloud is already sparse – downsampling further risks losing the structure you're trying to keep