Point Cloud Voxel Downsampling

3D Vision Processing

This tutorial walks you through how to use vitreous to downsample a 3D point cloud with voxel filtering and visualize the result in Rerun.

Downsampled Point Cloud Output

Light voxel-based reduction that removes redundant samples while preserving fine geometric detail.

Run the Voxel Downsampling from Vitreous on Point Cloud

Save the script

Create a file called quickstart_voxel_downsample_example.py anywhere on your machine and paste the following:

"""
Telekinesis quickstart: downsample a point cloud with voxel filtering.

Loads a sample point cloud from a public URL, runs Voxel downsampling,
and visualizes the input and the filtered point cloud
in a Rerun viewer.

Run as a script - python quickstart_voxel_downsample_example.py
"""

from pathlib import Path

import requests
import rerun as rr
from loguru import logger
from datatypes import io

from telekinesis import vitreous


# Public sample point cloud shipped by Telekinesis (you can swap this for a local file later).
POINT_CLOUD_URL = (
    "https://telekinesis-public-assets.s3.us-east-1.amazonaws.com/point_clouds/"
    "can_vertical_1_subtracted.ply"
)

# Written under the current working directory when you run the script.
POINT_CLOUD_PATH = Path("can_vertical_1_subtracted.ply")


def main() -> None:
    # Download PLY bytes and write a local file for io.load_point_cloud
    response = requests.get(POINT_CLOUD_URL, timeout=60)
    response.raise_for_status()
    POINT_CLOUD_PATH.write_bytes(response.content)

    # Typed PointCloud: positions (N,3) and optional colors - this asset includes colors.
    point_cloud = io.load_point_cloud(filepath=str(POINT_CLOUD_PATH))
    logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

    # One Skill call: points in the same voxel cell are merged. Smaller voxel_size keeps more detail.
    filtered_point_cloud = vitreous.filter_point_cloud_using_voxel_downsampling(
        point_cloud=point_cloud,
        voxel_size=0.005,
    )
    logger.success("Voxel downsampling complete.")

    # Opens the Rerun viewer (spawn=True). 
    rr.init("telekinesis_voxel_downsampling_quickstart", spawn=True)

    # Log full-resolution cloud and filtered cloud as separate entities in the 3D view.
    rr.log(
        "input_point_cloud",
        rr.Points3D(
            positions=point_cloud.positions,
            colors=point_cloud.colors,
        ),
    )
    rr.log(
        "filtered_point_cloud",
        rr.Points3D(
            positions=filtered_point_cloud.positions,
            colors=filtered_point_cloud.colors,
        ),
    )


if __name__ == "__main__":
    main()

Run the script!

python quickstart_voxel_downsample_example.py

Free TierEvery new account starts on a free tier with credits to call the SDK — no billing details required.Create API key →

Where to Go Next?

Ready to go deeper? Browse the Telekinesis Skill Examples repository for a runnable example covering every Skill.

Skill Examples

One runnable example per Skill, across vision, 3D, hardware, and robotics.

Explore the Docs

Skills

Vision, 3D, hardware, and robotics skills — the full API reference.

Agents

Turn natural-language instructions into robot code with Tzara, the VS Code agent.

Data Engine

Generate and manage synthetic datasets for training Physical AI models.

BabyROS

Lightweight pub/sub and service primitives for building robot communication layers.

Applications

Real-world use cases: pick-and-place, palletizing, quality inspection, and more.

Support

Join Discord

Ask questions, share what you're building, and get help from the community.

Add a Skill?

Have a new Skill to be added to Telekinesis? Get in touch with us.