Reconstruct Mesh Using Convex Hull

SUMMARY

Reconstruct Mesh Using Convex Hull wraps a point cloud in the smallest convex mesh that contains every point.

The reconstruction is fast and always produces a closed, watertight mesh, but it cannot represent concave features — dents, holes, and other non-convex shapes get "filled in" by the hull. Compare with reconstruct_mesh_using_poisson, which can represent that concave detail but requires the input point cloud to already have normals.

Use this Skill when you want a quick, always-watertight convex approximation of a point cloud's shape, e.g. for collision geometry or grasp planning.

The Skill

from telekinesis import vitreous

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

API Reference

Full parameter and return type documentation for reconstruct_mesh_using_convex_hull.

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 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

"""
Demonstrates computing the convex hull mesh enclosing a point cloud.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def reconstruct_mesh_using_convex_hull_example():
    """
    Computes the convex hull mesh enclosing a point cloud.

    Creates the smallest convex shape that contains all points.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = "https://assets.telekinesis.ai/examples/v1/point_clouds/beer_can_corrupted_normals.ply"
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    result_mesh = vitreous.reconstruct_mesh_using_convex_hull(
        joggle_inputs=False,
        point_cloud=point_cloud,
    )

    # ===================== Log ================================================
    logger.success(f"Reconstructed convex hull mesh from {point_cloud}")
    logger.success(f"Results: {result_mesh}")
    logger.info(
        f"Result mesh has {len(result_mesh.vertex_positions)} vertices and {len(result_mesh.triangle_indices)} triangles"
    )
    logger.info(f"Result mesh has vertex normals: {result_mesh.has_vertex_normals}")
    logger.info(f"Result mesh has vertex colors: {result_mesh.has_vertex_colors}")

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


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

Parameter Configuration

This Skill takes the point cloud to wrap and a single flag controlling the robustness of the hull computation.

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to wrap. Only positions are used
joggle_inputs	datatypes.Bool | bool	False	Whether to add tiny random perturbations to the input points before hull computation, to avoid failures on degenerate inputs (e.g. many coplanar or duplicate points)

Returns

Type	Description
datatypes.Mesh3D	The convex hull surface. Use len(mesh) (or len(mesh.vertex_positions)) for the vertex count and len(mesh.triangle_indices) for the triangle count.

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

joggle_inputs

• Controls: Whether tiny random perturbations are applied to the input points before computing the hull.
• Units: Boolean
• Default: False
• Set True if hull computation fails on degenerate input (many coplanar or duplicate points) — more robust, but slightly alters the input
• Keep False for an exact hull when you're confident the input isn't degenerate

TIP

If reconstruction fails outright rather than just producing a coarse result, that's usually a degenerate-input error, not a parameter-tuning problem — retry with joggle_inputs=True before changing anything else.

Where to Use the Skill

Common pipelines include:

• Collision geometry generation – producing a cheap, always-watertight bound for physics or collision checks
• Grasp planning – approximating an object's outer envelope for manipulator reasoning
• Volume estimation – computing a conservative upper-bound volume from a partial scan
• Per-cluster mesh generation – wrapping each cluster from cluster_point_cloud_using_dbscan in its own simplified mesh

Alternative Skills

Skill	vs. Reconstruct Mesh Using Convex Hull
reconstruct_mesh_using_poisson	Can represent concave surface detail that convex hull fills in, but requires the point cloud to already have normals and is more computationally expensive. Use convex hull for a fast, always-watertight approximation; use Poisson when concavities matter and normals are available.

When Not to Use the Skill

Do not use Reconstruct Mesh Using Convex Hull when:

• The object has real concave features you need to preserve — the hull fills in every dent, hole, and non-convex region; use reconstruct_mesh_using_poisson instead
• You need an accurate surface, not just a bounding shape — a convex hull can be substantially larger than the actual object once there's any concavity
• Fine geometric detail matters — convex hull is a coarse approximation, not a detailed reconstruction

WARNING

A convex hull mesh wraps every point but removes all concavities, so it will be larger than the real object whenever the object isn't already convex. Only use it when that coarse, convex approximation is acceptable for your downstream task.