Create Plane Mesh

SUMMARY

Create Plane Mesh generates a rectangular 3D plane mesh centered at the global origin.

This Skill is mainly used for pose estimation and 3D detection of planar objects or surfaces, such as tabletops, walls, or floors. By providing a simple planar reference, it enables perception algorithms to detect, align, and estimate the orientation of planes in 3D scenes.

Use this Skill when you want to develop or test 3D detection and pose estimation pipelines involving planar surfaces.

The Skill

from telekinesis import vitreous
import numpy as np

plane_mesh = vitreous.create_plane_mesh(
    transformation_matrix=np.eye(4),
    x_dimension=1.0,
    y_dimension=1.0,
    z_dimension=0.01,
    compute_vertex_normals=True,
)

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

Visualisation

The Code

from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib
import numpy as np

# Optional for logging
from loguru import logger

# Execute operation
plane_mesh = vitreous.create_plane_mesh(
  transformation_matrix=np.eye(4, dtype=np.float32),
  x_dimension=1.0,
  y_dimension=1.0,
  z_dimension=0.001,
  compute_vertex_normals=True,
)
logger.success("Created plane mesh")

The Explanation of the Code

First, we import the required modules: vitreous for 3D operations, numpy for transformations, and optionally loguru for logging progress.

from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib
import numpy as np

# Optional for logging
from loguru import logger

Next, the create_plane_mesh Skill is executed. This generates a rectangular 3D plane mesh with specified dimensions (x_dimension, y_dimension, z_dimension) and an optional transformation matrix. The compute_vertex_normals parameter ensures the mesh has correct normals for visualization or downstream processing.

# Execute operation
plane_mesh = vitreous.create_plane_mesh(
  transformation_matrix=np.eye(4, dtype=np.float32),
  x_dimension=1.0,
  y_dimension=1.0,
  z_dimension=0.01,
  compute_vertex_normals=True,
)
logger.success("Created plane mesh")

This plane mesh is commonly used in robotics pipelines for 6D pose estimation, scene setup, or calibration, providing a simple planar reference surface such as floors, tables, or walls to help perception and registration tasks.

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 create_plane_mesh

How to Tune the Parameters

The create_plane_mesh Skill has several parameters that control the plane's geometry and mesh quality:

transformation_matrix (default: np.eye(4)):

• The 4x4 transformation matrix to position and orient the plane
• The plane lies in the XY plane by default, with normal along Z-axis
• Use this to translate, rotate, and scale the plane

x_dimension (default: 1.0):

• The length of the plane along the X-axis
• Units: Uses the same units as your point cloud (e.g., if point cloud is in meters, dimension is in meters; if in millimeters, dimension is in millimeters)
• Increase to create a wider plane
• Typical range: 0.001-100.0 in point cloud units

y_dimension (default: 1.0):

• The length of the plane along the Y-axis
• Units: Uses the same units as your point cloud
• Increase to create a longer plane
• Typical range: 0.001-100.0 in point cloud units

z_dimension (default: 0.01):

• The thickness of the plane along the Z-axis
• Units: Uses the same units as your point cloud
• Increase to create a thicker plane (more like a box/cuboid)
• Decrease to create a thinner plane
• For a true plane, use very small values (0.001-0.01 in point cloud units)
• Typical range: 0.001-1.0 in point cloud units
• Note: By adjusting z_dimension along with x_dimension and y_dimension, you can create cuboid/box shapes

compute_vertex_normals (default: True):

• Whether to compute vertex normals for the mesh
• True: Normals are calculated, useful for lighting and rendering
• False: Normals are not computed, acceptable for non-rendering uses

TIP

Note: This Skill can be used to create both thin planes and cuboids/boxes. For a thin plane, use small z_dimension (e.g., 0.001-0.01). For a cuboid, use larger z_dimension relative to x_dimension and y_dimension.

Where to Use the Skill in a Pipeline

Plane mesh creation is commonly used in the following pipelines:

• 6D pose estimation for planar objects
• Scene setup and calibration
• Cuboid/box object representation
• Synthetic data generation for testing

A typical pipeline for pose estimation looks as follows:

# Example pipeline using plane mesh for pose estimation (parameters omitted).

from telekinesis import vitreous
import numpy as np

# 1. Create reference plane mesh matching your object
plane_mesh = vitreous.create_plane_mesh(
    transformation_matrix=np.eye(4),
    x_dimension=1.0,
    y_dimension=1.0,
    z_dimension=0.01,  # Thin plane, or use larger value for cuboid
    compute_vertex_normals=True,
)

# 2. Load or capture point cloud from sensor
point_cloud = vitreous.load_point_cloud(...)

# 3. Preprocess point cloud
filtered_cloud = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)
downsampled_cloud = vitreous.filter_point_cloud_using_voxel_downsampling(...)

# 4. Use plane mesh for pose estimation or matching
# (pose estimation code would go here)

Related skills to build such a pipeline:

• create_cylinder_mesh: create cylindrical reference meshes
• create_sphere_mesh: create spherical reference meshes
• create_torus_mesh: create torus reference meshes
• filter_point_cloud_using_statistical_outlier_removal: clean input point clouds
• filter_point_cloud_using_voxel_downsampling: reduce point cloud density

Alternative Skills

Skill	vs. Create Plane Mesh
create_cylinder_mesh	Use cylinder mesh for cylindrical objects. Use plane mesh for planar surfaces or cuboids.
create_sphere_mesh	Use sphere mesh for spherical objects. Use plane mesh for planar surfaces or cuboids.
create_torus_mesh	Use torus mesh for toroidal objects. Use plane mesh for planar surfaces or cuboids.

When Not to Use the Skill

Do not use create plane mesh when:

• You need a different shape (use create_cylinder_mesh, create_sphere_mesh, or create_torus_mesh instead)
• You have an existing mesh file (load it directly instead of creating a parametric mesh)
• You need a complex or non-parametric shape (this Skill only creates simple parametric planes/cuboids)
• You need very high precision geometry (parametric meshes may have limitations compared to CAD models)