Create Cylinder Mesh

SUMMARY

Create Cylinder Mesh generates a parametric cylinder mesh standing along the Z-axis, centered at the origin.

It builds a triangle mesh from a radius, height, and radial/height resolution, optionally capping the bottom face with retain_base and welding near-duplicate vertices within vertex_tolerance, then applies a 4x4 rigid transformation_matrix to translate, rotate, or scale the result into place. It's a convenient way to produce synthetic 3D test geometry -- for example as input to convert_mesh_to_point_cloud for a synthetic point cloud, or to approximate pipe- or rod-shaped objects for filter_point_cloud_using_cylinder_base_removal.

Use this Skill when you want to generate a reference cylinder mesh for synthetic point clouds, pose-estimation testing, or pipe/rod-shaped object approximation.

The Skill

from telekinesis import vitreous
import numpy as np

cylinder_mesh = vitreous.create_cylinder_mesh(
    radius=0.01,
    height=0.02,
    radial_resolution=20,
    height_resolution=4,
    retain_base=False,
    vertex_tolerance=1e-6,
    transformation_matrix=np.eye(4),
    compute_vertex_normals=True,
)

API Reference

Full parameter and return type documentation for create_cylinder_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 parametric cylinder mesh.
"""

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

from telekinesis import vitreous, datatypes


def create_cylinder_mesh_example():
    """
    Creates a parametric cylinder mesh.

    Generates a cylinder with specified radius, height, and resolution.
    """
    # ===================== Run Skill ==========================================
    cylinder_mesh = vitreous.create_cylinder_mesh(
        radius=0.01,
        height=0.02,
        radial_resolution=20,
        height_resolution=4,
        retain_base=False,
        vertex_tolerance=1e-6,
        transformation_matrix=np.eye(4, dtype=np.float32),
        compute_vertex_normals=True,
    )

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

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


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

Parameter Configuration

Key	Type	Default	Description
radius	datatypes.Float | float | int	0.01	The cylinder's radius, in meters
height	datatypes.Float | float | int	0.02	The cylinder's height along its axis, in meters
radial_resolution	datatypes.Int | int	20	Number of vertices around the circumference (angular resolution)
height_resolution	datatypes.Int | int	4	Number of vertices along the height (vertical subdivisions)
retain_base	datatypes.Bool | bool	False	Whether to cap the bottom circular face (True = closed base, False = open/hollow tube)
vertex_tolerance	datatypes.Float | float | int	1e-6	Minimum distance, in meters, below which two vertices are treated as duplicates and merged
transformation_matrix	datatypes.Mat4x4 | np.ndarray | list[list[float]]	np.eye(4)	4x4 rigid transform applied after generation to translate/rotate/scale the cylinder into place; the cylinder's own axis is Z before this is applied
compute_vertex_normals	datatypes.Bool | bool	True	Whether to compute per-vertex normals

Returns

Type	Description
datatypes.Mesh3D	The generated cylinder 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_cylinder_mesh Skill exposes eight parameters that control the cylinder's geometry, mesh density, and placement.

radius

• Controls: The cylinder's radius.
• Units: Meters
• Default: 0.01
• Increase → a wider cylinder
• Typical range: 0.001-1.0 meters

height

• Controls: The cylinder's height along its axis.
• Units: Meters
• Default: 0.02
• Increase → a taller cylinder
• Typical range: 0.001-10.0 meters

radial_resolution

• Controls: The number of vertices around the circumference.
• Units: Unitless (vertex count)
• Default: 20
• Increase → a smoother circular cross-section, at the cost of more triangles
• Decrease → a more faceted, low-poly look with fewer triangles
• Typical range: 8-64 -- use 8-16 for low-poly, 20-32 for smooth, 32-64 for very smooth

height_resolution

• Controls: The number of vertices along the height (vertical subdivisions).
• Units: Unitless (vertex count)
• Default: 4
• Increase → more vertical subdivisions, useful if you plan to deform the mesh later
• Decrease → fewer segments
• Typical range: 2-20 -- use 2-4 for a plain cylinder, 4-10 for more detail

retain_base

• Controls: Whether the bottom circular face is capped.
• Units: Boolean
• Default: False
• True gives a closed, solid-looking base
• False leaves the bottom open (a hollow tube)

vertex_tolerance

• Controls: The minimum distance below which two vertices are treated as duplicates and merged.
• Units: Meters
• Default: 1e-6
• Decrease (1e-8-1e-6) to preserve near-duplicate vertices exactly
• Increase (1e-4-1e-3) for more aggressive automatic vertex welding
• Typical range: 1e-8-1e-3 meters

transformation_matrix

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

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 (e.g. as input to convert_mesh_to_point_cloud) and want to save compute

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
• Pipe/rod base removal -- approximate pipe- or rod-shaped objects as a reference cylinder for filter_point_cloud_using_cylinder_base_removal
• 6D pose estimation and detection testing -- use as a reference/template mesh for cylindrical objects such as pipes, rods, or cans
• Collision checking and simulation -- represent cylindrical parts as simplified collision geometry

Alternative Skills

Skill	vs. Create Cylinder Mesh
create_plane_mesh	Generates a flat rectangular (thin-box) mesh. Use for planar surfaces or cuboids instead of cylindrical objects.
create_sphere_mesh	Generates a spherical mesh. Use for round objects or markers instead of cylindrical objects.
create_torus_mesh	Generates a ring/donut-shaped mesh. Use for toroidal objects instead of cylindrical objects.
convert_mesh_to_point_cloud	Companion next step: samples this cylinder mesh's surface into a datatypes.PointCloud for synthetic testing.

When Not to Use the Skill

Do not use Create Cylinder Mesh when:

• You already have a real scanned mesh or point cloud of the object -- this Skill only creates idealized synthetic geometry, not a representation of an actual scanned part
• The object isn't cylindrical -- use create_plane_mesh, create_sphere_mesh, or create_torus_mesh instead
• You need a complex or non-parametric shape -- this Skill only creates simple parametric cylinders (radius/height/resolution), not arbitrary CAD geometry
• You need CAD-level precision -- a parametric mesh is a convenient approximation, not a substitute for an authoritative CAD model

TIP

If you need a solid-looking reference cylinder (e.g. to test filter_point_cloud_using_cylinder_base_removal against a capped object), set retain_base=True; leave it False for an open/hollow tube.