Create Plane Mesh

SUMMARY

Create Plane Mesh generates a rectangular 3D plane mesh, built as a thin box, lying in the XY plane and centered at the origin.

It's a thin box rather than a true zero-thickness plane, so it behaves well with mesh algorithms that expect a closed, watertight surface -- keep z_dimension small (0.001-0.01 meters) to approximate a flat plane, or make it larger relative to x_dimension/y_dimension to represent an actual cuboid. A 4x4 rigid transformation_matrix then translates, rotates, or scales the result into place.

Use this Skill when you want to generate a reference plane or cuboid mesh for planar-surface pose-estimation testing, scene setup, or calibration.

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

Full parameter and return type documentation for create_plane_mesh.

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

Visualisation

The Code

"""
Demonstrates creating a rectangular plane mesh (thin box).
"""

import numpy as np
from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def create_plane_mesh_example():
    """
    Creates a rectangular plane mesh (thin box).

    Generates a flat rectangular surface with specified dimensions.
    """
    # ===================== Run Skill ==========================================
    plane_mesh = vitreous.create_plane_mesh(
        transformation_matrix=np.eye(4, dtype=np.float32),
        x_dimension=0.01,
        y_dimension=0.01,
        z_dimension=0.00001,
        compute_vertex_normals=True,
    )

    # ===================== Log ================================================
    logger.success("Created plane mesh")
    logger.success(f"Results: {plane_mesh}")
    logger.info(
        f"Plane mesh has {len(plane_mesh)} vertices and {len(plane_mesh.triangle_indices)} triangles"
    )
    logger.info(f"Plane mesh has vertex normals: {plane_mesh.has_vertex_normals}")
    logger.info(f"Plane mesh has vertex colors: {plane_mesh.has_vertex_colors}")

    # ===================== Visualization  (Optional) ===========================
    rr.init("create_plane_mesh_example", spawn=True)
    datatypes.visualize(plane_mesh, entity_path="/plane_mesh")


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

Parameter Configuration

Key	Type	Default	Description
transformation_matrix	datatypes.Mat4x4 | np.ndarray | list[list[float]]	np.eye(4)	4x4 rigid transform applied after generation to translate/rotate/scale the plane into place; the plane's own normal is Z before this is applied
x_dimension	datatypes.Float | float | int	1.0	The plane's length along the X-axis, in meters
y_dimension	datatypes.Float | float | int	1.0	The plane's length along the Y-axis, in meters
z_dimension	datatypes.Float | float | int	0.01	The plane's thickness along the Z-axis, in meters
compute_vertex_normals	datatypes.Bool | bool	True	Whether to compute per-vertex normals

Returns

Type	Description
datatypes.Mesh3D	The generated plane mesh. Use len(mesh) (or len(mesh.vertex_positions)) for the vertex count, len(mesh.triangle_indices) for the triangle count, and .has_vertex_normals/.has_vertex_colors to check whether those optional fields were populated.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above)
ValueError	transformation_matrix is not shape (4, 4) (or, for a list input, doesn't contain only numeric elements)
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

The create_plane_mesh Skill exposes five parameters that control the plane's dimensions, thickness, and placement.

transformation_matrix

• Controls: The 4x4 rigid transform applied to the plane after it's generated (translate/rotate/scale it into place).
• Units: N/A (4x4 matrix)
• Default: np.eye(4) (identity -- no transform)
• The plane's own normal is Z before this transform is applied

x_dimension

• Controls: The plane's length along the X-axis.
• Units: Meters
• Default: 1.0
• Increase → a wider plane
• Typical range: 0.001-100.0 meters

y_dimension

• Controls: The plane's length along the Y-axis.
• Units: Meters
• Default: 1.0
• Increase → a longer plane
• Typical range: 0.001-100.0 meters

z_dimension

• Controls: The plane's thickness along the Z-axis.
• Units: Meters
• Default: 0.01
• Decrease → looks more like a true, zero-thickness flat plane -- use 0.001-0.01 meters to approximate one
• Increase → looks more like a real box/cuboid
• Typical range: 0.001-1.0 meters

compute_vertex_normals

• Controls: Whether per-vertex normals are computed.
• Units: Boolean
• Default: True
• True is needed for realistic lighting/shading when rendering
• False skips normal computation if you only need the raw geometry and want to save compute

TIP

This Skill can represent both thin planes and true cuboids/boxes from the same parameters. For a flat-looking plane, keep z_dimension small (0.001-0.01 meters) relative to x_dimension/y_dimension; for a box, make it comparable in scale.

Where to Use the Skill

Common pipelines include:

• Synthetic point cloud generation -- feed the mesh into convert_mesh_to_point_cloud to produce a test point cloud with known ground-truth geometry
• 6D pose estimation for planar objects -- use as a reference/template mesh for tabletops, walls, or floors
• Scene setup and calibration -- place a known-size planar reference in a synthetic scene
• Cuboid/box object representation -- use a larger z_dimension to represent boxes or crates

Alternative Skills

Skill	vs. Create Plane Mesh
create_cylinder_mesh	Generates a cylindrical mesh. Use for pipe/rod-shaped objects instead of planar surfaces or cuboids.
create_sphere_mesh	Generates a spherical mesh. Use for round objects or markers instead of planar surfaces or cuboids.
create_torus_mesh	Generates a ring/donut-shaped mesh. Use for toroidal objects instead of planar surfaces or cuboids.
convert_mesh_to_point_cloud	Companion next step: samples this plane mesh's surface into a datatypes.PointCloud for synthetic testing.

When Not to Use the Skill

Do not use Create Plane Mesh when:

• You already have a real scanned mesh or point cloud of the surface -- this Skill only creates idealized synthetic geometry, not a representation of an actual scanned scene
• The object isn't planar or box-shaped -- use create_cylinder_mesh, create_sphere_mesh, or create_torus_mesh instead
• You need a true zero-thickness surface for algorithms that reject thin solids -- this Skill always generates a thin box, not an infinitely thin plane
• You need CAD-level precision -- a parametric mesh is a convenient approximation, not a substitute for an authoritative CAD model