Create Sphere Mesh

SUMMARY

Create Sphere Mesh generates a 3D spherical mesh centered at the global origin, with configurable radius and resolution.

This Skill is primarily used for pose estimation and 3D detection of spherical objects, such as balls, rounded sensors, or spherical components. By providing a precise spherical mesh, it allows perception algorithms to detect and estimate the position and orientation of these objects in 3D scenes.

Use this Skill when you want to develop or test 3D detection and pose estimation pipelines for spherical objects.

The Skill

from telekinesis import vitreous
import numpy as np

sphere_mesh = vitreous.create_sphere_mesh(
    transformation_matrix=np.eye(4),
    radius=0.01,
    resolution=20,
    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
sphere_mesh = vitreous.create_sphere_mesh(
  transformation_matrix=np.eye(4, dtype=np.float32),
  radius=0.01,
  resolution=20,
  compute_vertex_normals=True   
)
logger.success("Created sphere 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_sphere_mesh

The Explanation of the Code

First, we import the required modules: vitreous for 3D 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_sphere_mesh Skill is executed. This generates a spherical 3D mesh with a specified radius and resolution. The compute_vertex_normals parameter ensures that the mesh can be correctly visualized or used in downstream geometry processing.

# Execute operation
sphere_mesh = vitreous.create_sphere_mesh(
  transformation_matrix=np.eye(4, dtype=np.float32),
  radius=0.01,
  resolution=20,
  compute_vertex_normals=True   
)
logger.success("Created sphere mesh")

This Skill is particularly useful in robotics pipelines for 6D pose estimation and object detection, where spherical objects or markers are needed as reference points, targets, or synthetic objects for simulation and testing.

How to Tune the Parameters

The create_sphere_mesh Skill has several parameters that control the sphere's geometry and mesh quality:

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

• The 4x4 transformation matrix to position the sphere
• The sphere is centered at the translation component of the matrix
• Use this to translate, rotate, and scale the sphere

radius (default: 0.01):

• The radius of the sphere
• 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 sphere
• Typical range: 0.001-100.0 in point cloud units
• Use 0.001-0.1 for small markers, 0.1-1.0 for medium spheres, 1.0-10.0 for large spheres

resolution (default: 20):

• The number of vertices around the sphere (angular resolution)
• Increase (32-64) for smoother sphere with more triangles
• Decrease (8-16) for more faceted sphere with fewer triangles
• Typical range: 8-64
• Use 8-16 for low-poly spheres, 20-32 for smooth, 32-64 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

Where to Use the Skill in a Pipeline

Sphere mesh creation is commonly used in the following pipelines:

• 6D pose estimation for spherical 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 sphere mesh for pose estimation (parameters omitted).

from telekinesis import vitreous
import numpy as np

# 1. Create reference sphere mesh matching your object
sphere_mesh = vitreous.create_sphere_mesh(
    transformation_matrix=np.eye(4),
    radius=0.01,
    resolution=20,
    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 sphere 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_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 Sphere Mesh
create_plane_mesh	Use plane mesh for planar surfaces or cuboids. Use sphere mesh for spherical objects.
create_cylinder_mesh	Use cylinder mesh for cylindrical objects. Use sphere mesh for spherical objects.
create_torus_mesh	Use torus mesh for toroidal objects. Use sphere mesh for spherical objects.

When Not to Use the Skill

Do not use create sphere mesh when:

• You need a different shape (use create_plane_mesh, create_cylinder_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 spheres)
• You need very high precision geometry (parametric meshes may have limitations compared to CAD models)