Telekinesis Agentic Skill Library

Appearance

Convert Mesh to Point Cloud ​

SUMMARY

Convert Mesh to Point Cloud generates a point cloud representation from a triangle mesh by sampling points on the mesh surface.

This Skill is primarily used for 6D pose estimation and registration, converting CAD or mesh models into point clouds so they can be aligned with real-world sensor data. By creating a point cloud with controlled density, it enables accurate correspondence-based registration and pose estimation pipelines.

Use this Skill when you want to prepare mesh models for 3D registration or 6D pose estimation in perception workflows.

The Skill ​

python
from telekinesis import vitreous

output_point_cloud = vitreous.filter_point_cloud_using_voxel_downsampling(
    point_cloud=input_point_cloud,
    voxel_size=0.01,
)

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 ​

Input Mesh

Output Point Cloud

Parameters: num_points=10000, sampling_method="poisson_disk", initial_sampling_factor=5, initial_point_cloud=None, use_triangle_normal=False.

The Code ​

python
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 mesh
filepath = str(DATA_DIR / "meshes" / "gear_box.glb")
mesh = io.load_mesh(filepath=filepath)
logger.success(f"Loaded mesh with {len(mesh.vertex_positions)} vertices")

# Execute operation
point_cloud = vitreous.convert_mesh_to_point_cloud(
  mesh=mesh,
  num_points=10000,
  sampling_method="poisson_disk",
  initial_sampling_factor=5,
  initial_point_cloud=None,
  use_triangle_normal=False,
)
logger.success(
  f"Converted mesh with {len(mesh.vertex_positions)} vertices to point cloud"
)

The Explanation of the Code ​

First, we import the necessary modules from the Telekinesis SDK, including vitreous for 3D operations and io for data loading. Logging with loguru is optional but helps track workflow progress.

python
from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib

# Optional for logging
from loguru import logger

Next, we load a 3D mesh from a .glb file using io.load_mesh. Logging the number of vertices provides a sanity check on the mesh data and ensures it’s ready for conversion.

python
DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Load mesh
filepath = str(DATA_DIR / "meshes" / "gear_box.glb")
mesh = io.load_mesh(filepath=filepath)
logger.success(f"Loaded mesh with {len(mesh.vertex_positions)} vertices")

Finally, we run the convert_mesh_to_point_cloud Skill. This samples points from the mesh surface to generate a point cloud representation. The poisson_disk sampling method ensures a more uniform point distribution, which is especially useful in 6D pose estimation and registration pipelines. The resulting point cloud can then be used for downstream tasks like alignment, detection, or collision checking in industrial robotics workflows.

python
# Execute operation
point_cloud = vitreous.convert_mesh_to_point_cloud(
  mesh=mesh,
  num_points=10000,
  sampling_method="poisson_disk",
  initial_sampling_factor=5,
  initial_point_cloud=None,
  use_triangle_normal=False,
)
logger.success(
  f"Converted mesh with {len(mesh.vertex_positions)} vertices to point cloud"
)

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:

bash
cd telekinesis-examples
python examples/vitreous_examples.py --example convert_mesh_to_point_cloud

How to Tune the Parameters ​

num_points ​

Controls the number of sampled surface points.

  • Low (1k–5k): Fast, coarse geometry
  • Medium (5k–20k): Recommended for most 6D pose estimation tasks
  • High (20k+): High detail, slower processing
    Use the lowest value that preserves required geometric features.

sampling_method ​

Defines how points are distributed on the surface.

  • poisson_disk (recommended): Even spacing, ideal for registration
  • uniform: Faster, less consistent density

initial_sampling_factor ​

Number of candidate points sampled before filtering.

  • Lower (2–3): Faster, less uniform
  • Higher (5–10): Better spacing, slower execution
    Start with 5 and adjust if needed.

initial_point_cloud ​

Optional seed point cloud.

  • Use None for standard mesh-to-point-cloud conversion
  • Useful for incremental refinement or consistency across runs

use_triangle_normal ​

Whether to include mesh surface normals.

  • False: Geometry-only (default, recommended)
  • True: Required for point-to-plane ICP or normal-aware pipelines
python
num_points=10000
sampling_method="poisson_disk"
initial_sampling_factor=5
initial_point_cloud=None
use_triangle_normal=False