Reconstruct Mesh Using Poisson

SUMMARY

Reconstruct Mesh Using Poisson fits a smooth, watertight mesh through an oriented point cloud using Poisson surface reconstruction.

The Skill solves a Poisson equation over the points' normals to fit a smooth implicit surface, then extracts it as a closed, manifold mesh. Unlike reconstruct_mesh_using_convex_hull, it can represent concave detail — but it requires point_cloud to already have normals (point_cloud.has_normals) to produce a meaningful result.

Use this Skill when you want to reconstruct a smooth, detailed, watertight mesh from a point cloud that already has normals.

The Skill

from telekinesis import vitreous

reconstructed_mesh = vitreous.reconstruct_mesh_using_poisson(
    point_cloud=point_cloud,
    octree_depth=8,
    octree_width=0,
    scale_factor=1.05,
)

API Reference

Full parameter and return type documentation for reconstruct_mesh_using_poisson.

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 normals already present.

Reconstructed Mesh

Reconstructed mesh. A higher depth leads to a mesh with more details.
Parameters: octree_depth = 8

The Code

"""
Demonstrates reconstructing a watertight mesh from an oriented point cloud using Poisson surface reconstruction.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def reconstruct_mesh_using_poisson_example():
    """
    Reconstructs a watertight mesh from an oriented point cloud using Poisson surface reconstruction.

    Solves a Poisson equation to fit a smooth surface through points with normals.
    Produces closed, manifold meshes. Requires point cloud normals.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = "https://assets.telekinesis.ai/examples/v1/point_clouds/industrial_part_7_normals.ply"
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    reconstructed_mesh = vitreous.reconstruct_mesh_using_poisson(
        octree_depth=7,
        octree_width=0,
        scale_factor=1.1,
        point_cloud=point_cloud,
    )

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

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


if __name__ == "__main__":
    reconstruct_mesh_using_poisson_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_poisson.py

Parameter Configuration

These parameters control the input point cloud and the resolution/extent of the Poisson surface reconstruction.

Parameter	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to reconstruct from. Must have normals (point_cloud.has_normals)
octree_depth	datatypes.Int | int	8	Depth of the octree used for spatial subdivision — each additional level roughly doubles the spatial resolution. Must be > 0
octree_width	datatypes.Int | int	0	Spatial width of the octree, in the point cloud's coordinate units. Must be >= 0; 0 auto-computes it from the point cloud's own bounds
scale_factor	datatypes.Float | float | int	1.05	Multiplier on the reconstruction's bounding volume. Must be > 0

Returns

Type	Description
datatypes.Mesh3D	A mesh fit through the points, with its lowest-density vertices trimmed away. This density-based trimming can leave holes or non-manifold regions, so the result is not guaranteed to be watertight or manifold. 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)
ValueError	point_cloud does not have normals (point_cloud.has_normals is False); octree_depth or scale_factor is not > 0; or octree_width is negative
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

octree_depth

• Controls: The depth of the octree used for spatial subdivision; each additional level roughly doubles spatial resolution.
• Units: Octree levels (integer)
• Default: 8
• Increase → captures finer surface detail, at the cost of more memory/compute
• Decrease → coarser, faster reconstruction
• Typical range: 6-12 — use 6-8 for coarse meshes, 8-10 for balanced quality/speed, 10-12 for high detail

octree_width

• Controls: The spatial width (extent) of the octree.
• Units: Same units as the point cloud
• Default: 0 (auto-computed from the point cloud's own bounds)
• Leave at 0 unless you specifically need a fixed reconstruction volume
• Typical range: 0 (auto), or 100-10000 if set manually

scale_factor

• Controls: A multiplier on the reconstruction's bounding volume.
• Units: Dimensionless multiplier
• Default: 1.05
• Increase → expands the fitted surface slightly beyond the points, which can help close small holes
• Decrease → keeps the surface closer to the points
• Typical range: 1.0-1.2 — use 1.0-1.05 for a tight fit, 1.05-1.1 for balanced, 1.1-1.2 for more expansion

TIP

Start from the defaults. If the mesh has unwanted holes, raise scale_factor slightly before reaching for a higher octree_depth. Only raise octree_depth when you specifically need finer surface detail — it's the most compute-expensive knob. Note that the reconstruction always trims away its lowest-density vertices, which can leave holes or non-manifold regions on its own — the result is not guaranteed to be watertight or manifold even with well-tuned parameters.

Where to Use the Skill

Common pipelines include:

• High-quality surface generation – producing detailed, watertight meshes from oriented scans for inspection or quality control
• Grasp planning with detailed geometry – reconstructing concave features a convex hull would otherwise remove
• Simulation and visualization – generating smooth meshes for physics simulation or rendering
• Environment modeling – building detailed surface models of scanned parts or scenes for downstream analysis

Alternative Skills

Skill	vs. Reconstruct Mesh Using Poisson
reconstruct_mesh_using_convex_hull	Always watertight and fast, with no normals requirement, but fills in every concave feature. Use convex hull for a quick collision/bounding approximation; use Poisson when concavities matter and normals are available.

When Not to Use the Skill

Do not use Reconstruct Mesh Using Poisson when:

• Your point cloud has no normals — this is a hard precondition for a meaningful result; compute/estimate normals first, or use reconstruct_mesh_using_convex_hull if you need a mesh without normals
• You need a simple, fast convex approximation — use reconstruct_mesh_using_convex_hull instead
• The point cloud is very sparse — Poisson reconstruction needs enough point density and normal coverage to fit a meaningful surface
• You need fast computation — Poisson reconstruction is computationally heavier than convex hull, especially at high octree_depth
• The point cloud has large holes or missing regions — Poisson may not close large gaps effectively even though it produces a watertight result