Reconstruct Mesh Using Convex Hull

SUMMARY

Reconstruct Mesh Using Convex Hull computes the smallest convex mesh that contains all points in a given point cloud.

This Skill is useful in industrial, mobile, and humanoid robotics pipelines for rough object modeling and collision geometry. For instance, it can generate a convex representation of a part for grasp planning in manufacturing, create simplified environment boundaries for mobile robot navigation, or approximate object shapes for humanoid robot manipulation. Convex hulls provide a fast and simple mesh representation suitable for geometric reasoning and collision checking.

Use this Skill when you want to generate a quick convex mesh from a point cloud for perception, collision detection, or geometric analysis.

The Skill

from telekinesis import vitreous

reconstructed_mesh = vitreous.reconstruct_mesh_using_convex_hull(
    point_cloud=point_cloud,
    joggle_inputs=False,
)

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

Raw Pointcloud

Unprocessed point cloud with missing regions.

Reconstructed Mesh

Generates the smallest convex shape that fully encloses the point cloud. This produces a closed, watertight mesh by “bridging over” missing or incomplete regions, but it also removes concavities and fine geometric details.

The Code

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 point cloud
filepath = str(DATA_DIR / "point_clouds" / "beer_can_corrupted_normals.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

# Execute operation
result_mesh = vitreous.reconstruct_mesh_using_convex_hull(
  joggle_inputs=False, 
  point_cloud=point_cloud
)
logger.success(
  f"Reconstructed convex hull mesh from {len(point_cloud.positions)} points"
)

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:

cd telekinesis-examples
python examples/vitreous_examples.py --example reconstruct_mesh_using_convex_hull

The Explanation of the Code

The code starts by importing the necessary modules: vitreous for 3D operations, datatypes and io for data handling, pathlib for managing file paths, and loguru for optional logging.

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

# Optional for logging
from loguru import logger

Next, a point cloud is loaded from a .ply file, and the number of points is logged to verify successful loading.

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

# Load point cloud
filepath = str(DATA_DIR / "point_clouds" / "beer_can_corrupted_normals.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

The main operation uses the reconstruct_mesh_using_convex_hull Skill, which computes the smallest convex mesh that fully encloses all points in the cloud. This method is useful in robotics and 3D vision pipelines for generating coarse object meshes, estimating object volume, or providing a simple geometric representation for collision detection and grasp planning. The joggle_inputs parameter can be used to slightly perturb points to avoid degenerate configurations in the hull calculation.

# Execute operation
result_mesh = vitreous.reconstruct_mesh_using_convex_hull(
  joggle_inputs=False, 
  point_cloud=point_cloud
)
logger.success(
  f"Reconstructed convex hull mesh from {len(point_cloud.positions)} points"
)

How to Tune the Parameters

The reconstruct_mesh_using_convex_hull Skill has one parameter that controls the reconstruction behavior:

joggle_inputs (default: False):

• Whether to add small random perturbations to input points to avoid degenerate cases
• True: Helps handle edge cases (e.g., coplanar points, duplicate points) but slightly modifies the input
• False: May fail on degenerate inputs but provides exact computation
• Set to True for robust operation, False for exact computation
• Default: False

TIP

Best practice: Use joggle_inputs=True if you encounter errors with degenerate point configurations (coplanar points, duplicates, etc.). Use False if you need exact computation and are confident your point cloud doesn't have degenerate cases.

Where to Use the Skill in a Pipeline

Convex hull mesh reconstruction is commonly used in the following pipelines:

• Collision geometry generation
• Grasp planning and manipulation
• Volume estimation
• Simplified object representation

A typical pipeline for collision geometry generation looks as follows:

# Example pipeline using convex hull reconstruction (parameters omitted).

from telekinesis import vitreous

# 1. Load point cloud
point_cloud = vitreous.load_point_cloud(...)

# 2. Preprocess: remove outliers and downsample
filtered_cloud = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)
downsampled_cloud = vitreous.filter_point_cloud_using_voxel_downsampling(...)

# 3. Cluster to separate objects
clusters = vitreous.cluster_point_cloud_using_dbscan(...)

# 4. For each cluster, generate convex hull mesh
for cluster in clusters:
    convex_mesh = vitreous.reconstruct_mesh_using_convex_hull(
        point_cloud=cluster,
        joggle_inputs=False,
    )
    # Use convex mesh for collision checking or grasp planning

# 5. Optional: Use convex mesh for collision detection

Related skills to build such a pipeline:

• filter_point_cloud_using_statistical_outlier_removal: clean input before reconstruction
• filter_point_cloud_using_voxel_downsampling: reduce point cloud density for faster processing
• cluster_point_cloud_using_dbscan: separate objects before generating individual meshes
• reconstruct_mesh_using_poisson: alternative method for smooth, detailed meshes
• calculate_oriented_bounding_box: compute bounding box for objects

Alternative Skills

Skill	vs. Reconstruct Mesh Using Convex Hull
reconstruct_mesh_using_poisson	Use Poisson reconstruction when you need smooth, detailed meshes that preserve fine geometric features. Use convex hull when you need a simple, fast convex representation for collision detection or rough modeling.

When Not to Use the Skill

Do not use reconstruct mesh using convex hull when:

• You need to preserve concave features (convex hull removes all concavities)
• You need fine geometric detail (convex hull provides only a rough approximation)
• You need a smooth surface (use reconstruct_mesh_using_poisson instead)
• The object has significant concavities (the convex hull will be much larger than the actual object)
• You need accurate surface representation (convex hull is a simplification)

WARNING

Important: Convex hull reconstruction creates a mesh that wraps all points but removes all concave features. The resulting mesh will be larger than the actual object if it has any concavities. Use this only when a convex approximation is acceptable.