Create Torus Mesh

SUMMARY

Create Torus Mesh generates a 3D torus mesh aligned along the Z-axis and centered at the origin, with configurable major and minor radii and resolution.

This Skill is mainly used for pose estimation and detection of torus-shaped objects, such as rings, wheels, or circular components. By providing a parametric torus, it allows perception algorithms to match, detect, and estimate the pose of these objects in 3D scenes.

Use this Skill when you want to test or develop pose estimation pipelines specifically for toroidal objects or to create reference meshes for detection tasks.

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

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

DATA_DIR = pathlib.Path("path/to/telekinesis-data")

# Execute operation
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,
)
logger.success(
  "Created torus mesh"
)

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_torus_mesh

The Explanation of the Code

First, the necessary modules are imported: vitreous for mesh operations, numpy for transformation matrices, and optionally loguru for logging.

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_torus_mesh Skill is executed. This generates a torus-shaped 3D mesh with configurable torus_radius and tube_radius. The radial_resolution and tubular_resolution control the mesh density, and compute_vertex_normals ensures proper visualization and downstream geometric processing.

# Execute operation
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,
)
logger.success(
  "Created torus mesh"
)

This Skill is especially useful in robotics pipelines for 6D pose estimation and detection, where torus-like objects such as rings, handles, or circular fixtures need to be represented for synthetic testing, calibration, or object recognition.

How to Tune the Parameters

The create_torus_mesh Skill has several parameters that control the torus's geometry and mesh quality:

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

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

torus_radius (default: 0.01):

• The major radius (distance from center to tube center)
• Units: Uses the same units as your point cloud (e.g., if point cloud is in meters, radius is in meters; if in millimeters, radius is in millimeters)
• Increase to create a larger torus
• Must be greater than tube_radius
• Typical range: 0.001-1.0 in point cloud units

tube_radius (default: 0.005):

• The minor radius (radius of the circular cross-section of the tube)
• Units: Uses the same units as your point cloud
• Increase to create a thicker tube
• Must be less than torus_radius
• Typical range: 0.0005-0.5 in point cloud units

radial_resolution (default: 20):

• The number of vertices around the major circle (torus circumference)
• Increase (32-64) for smoother torus but with more triangles
• Decrease (8-16) for more faceted appearance
• Typical range: 8-64
• Use 8-16 for low-poly, 20-32 for smooth, 32-64 for very smooth

tubular_resolution (default: 10):

• The number of vertices around the minor circle (tube cross-section)
• Increase (20-32) for smoother tube but with more triangles
• Decrease (6-10) for 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 (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

WARNING

Important: torus_radius must be greater than tube_radius. If tube_radius >= torus_radius, the torus geometry will be invalid.

Where to Use the Skill in a Pipeline

Torus mesh creation is commonly used in the following pipelines:

• 6D pose estimation for toroidal objects
• Object detection and matching
• Synthetic data generation for testing
• Collision checking and simulation

A typical pipeline for pose estimation looks as follows:

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

from telekinesis import vitreous
import numpy as np

# 1. Create reference torus mesh matching your object
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,
)

# 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 torus mesh for pose estimation or matching
# (pose estimation code would go here)

Related skills to build such a pipeline:

• create_plane_mesh: create planar reference meshes
• create_cylinder_mesh: create cylindrical reference meshes
• create_sphere_mesh: create spherical 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 Torus Mesh
create_plane_mesh	Use plane mesh for planar surfaces or cuboids. Use torus mesh for toroidal objects.
create_cylinder_mesh	Use cylinder mesh for cylindrical objects. Use torus mesh for toroidal objects.
create_sphere_mesh	Use sphere mesh for spherical objects. Use torus mesh for toroidal objects.

When Not to Use the Skill

Do not use create torus mesh when:

• You need a different shape (use create_plane_mesh, create_cylinder_mesh, or create_sphere_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 tori)
• You need very high precision geometry (parametric meshes may have limitations compared to CAD models)
• tube_radius >= torus_radius (the geometry will be invalid)