Create Torus Mesh

SUMMARY

Create Torus Mesh generates a parametric torus (donut) mesh lying in the XY plane by default, with its hole along the Z-axis, centered at the origin.

It builds a triangle mesh from a major radius (torus_radius, center to tube center) and a minor radius (tube_radius, the tube's own cross-section), with independent resolution controls for the torus's circumference and the tube's cross-section, then applies a 4x4 rigid transformation_matrix to translate, rotate, or scale the result into place. It's useful synthetic geometry for ring- or donut-shaped objects such as gaskets, washers, or O-rings, for example as input to convert_mesh_to_point_cloud.

Use this Skill when you want to generate a reference torus mesh for gasket-, washer-, or O-ring-shaped objects, for synthetic point clouds or pose-estimation testing.

The Skill

from telekinesis import vitreous
import numpy as np

torus_mesh = vitreous.create_torus_mesh(
    transformation_matrix=np.eye(4),
    torus_radius=0.01,
    tube_radius=0.005,
    radial_resolution=20,
    tubular_resolution=10,
    compute_vertex_normals=True,
)

API Reference

Full parameter and return type documentation for create_torus_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 torus (donut shape) mesh.
"""

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

from telekinesis import vitreous, datatypes


def create_torus_mesh_example():
    """
    Creates a torus (donut shape) mesh.

    Generates a parametric torus with specified major/minor radii and resolution.
    """
    # ===================== Run Skill ==========================================
    torus_mesh = vitreous.create_torus_mesh(
        transformation_matrix=np.eye(4, dtype=np.float32),
        torus_radius=0.01,
        tube_radius=0.005,
        radial_resolution=20,
        tubular_resolution=10,
        compute_vertex_normals=True,
    )

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

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


if __name__ == "__main__":
    create_torus_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_torus_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 torus into place; the torus's own hole axis is Z before this is applied
torus_radius	datatypes.Float | float | int	0.01	The major radius, in meters -- the distance from the torus's center to the center of its tube. Must be greater than tube_radius
tube_radius	datatypes.Float | float | int	0.005	The minor radius, in meters -- the radius of the tube's own circular cross-section. Must be less than torus_radius
radial_resolution	datatypes.Int | int	20	Number of vertices around the major circle (the torus's overall circumference)
tubular_resolution	datatypes.Int | int	10	Number of vertices around the minor circle (the tube's own cross-section)
compute_vertex_normals	datatypes.Bool | bool	True	Whether to compute per-vertex normals

Returns

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

transformation_matrix

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

torus_radius

• Controls: The major radius -- the distance from the torus's center to the center of its tube.
• Units: Meters
• Default: 0.01
• Increase → a larger overall torus
• Must be greater than tube_radius
• Typical range: 0.001-1.0 meters

tube_radius

• Controls: The minor radius -- the radius of the tube's own circular cross-section.
• Units: Meters
• Default: 0.005
• Increase → a thicker tube
• Must be less than torus_radius
• Typical range: 0.0005-0.5 meters

radial_resolution

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

tubular_resolution

• Controls: The number of vertices around the minor circle (the tube's own cross-section).
• Units: Unitless (vertex count)
• Default: 10
• Increase → a smoother tube with more triangles
• Decrease → a more faceted tube
• Typical range: 6-32 -- use 6-10 for low-poly, 10-20 for smooth, 20-32 for very smooth

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

WARNING

torus_radius must be greater than tube_radius. If tube_radius >= torus_radius, the torus geometry is invalid -- the tube would overlap or exceed the central hole.

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 and detection testing -- use as a reference/template mesh for ring-shaped objects such as gaskets, washers, or O-rings
• Object detection and matching -- match against wheels, handles, or other circular fixtures
• Collision checking and simulation -- represent toroidal parts as simplified collision geometry

Alternative Skills

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

When Not to Use the Skill

Do not use Create Torus 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 toroidal -- use create_plane_mesh, create_cylinder_mesh, or create_sphere_mesh instead
• You need a complex or non-parametric shape -- this Skill only creates simple parametric tori (major/minor radius and 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
• tube_radius would be greater than or equal to torus_radius -- the resulting geometry is invalid