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.

Requires Normals

point_cloud must already have normals (check point_cloud.has_normals) for this Skill to produce a meaningful result. The SDK does not raise an error if normals are missing — passing a normal-less point cloud will not fail, but the reconstructed mesh will be low-quality or geometrically meaningless rather than a useful surface. If your point cloud doesn't have normals, compute/estimate them before calling this Skill.

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.

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to reconstruct from. Must have normals (point_cloud.has_normals) for a meaningful result
octree_depth	datatypes.Int | int	8	Depth of the octree used for spatial subdivision — each additional level roughly doubles the spatial resolution
octree_width	datatypes.Int | int	0	Spatial width of the octree, in the same units as the point cloud; 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

Returns

Type	Description
datatypes.Mesh3D	A closed surface fit through the points. 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

Note: missing normals on point_cloud do not trigger any of the exceptions above — see the "Requires Normals" warning above and the "When Not to Use the Skill" section below.

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.

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

WARNING

Passing a point cloud without normals does not raise an error — the request will still succeed, but the resulting mesh will not represent the actual surface. Always check point_cloud.has_normals before calling this Skill.