Create Sphere Mesh

SUMMARY

Create Sphere Mesh generates a parametric sphere mesh centered at the origin, with configurable radius and resolution.

It builds a triangle mesh of a sphere before transformation_matrix is applied, so the sphere ends up centered at the matrix's translation component. It's useful synthetic geometry for visualizing a point (e.g. marking a centroid) at a real physical size, or as input to convert_mesh_to_point_cloud.

Use this Skill when you want to generate a reference sphere mesh for marking a point at real scale, or for synthetic point clouds and pose-estimation testing on 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

Full parameter and return type documentation for create_sphere_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 UV sphere mesh.
"""

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

from telekinesis import vitreous, datatypes


def create_sphere_mesh_example():
    """
    Creates a UV sphere mesh.

    Generates a spherical mesh with specified radius and resolution.
    """
    # ===================== Run Skill ==========================================
    sphere_mesh = vitreous.create_sphere_mesh(
        transformation_matrix=np.eye(4, dtype=np.float32),
        radius=0.01,
        resolution=20,
        compute_vertex_normals=True,
    )

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

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


if __name__ == "__main__":
    create_sphere_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_sphere_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; the sphere ends up centered at this matrix's translation component
radius	datatypes.Float | float | int	0.01	The sphere's radius, in meters
resolution	datatypes.Int | int	20	Number of vertices around the sphere (angular resolution)
compute_vertex_normals	datatypes.Bool | bool	True	Whether to compute per-vertex normals

Returns

Type	Description
datatypes.Mesh3D	The generated sphere 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_sphere_mesh Skill exposes four parameters that control the sphere's placement, size, and mesh density.

transformation_matrix

• Controls: The 4x4 rigid transform applied to the sphere after it's generated.
• Units: N/A (4x4 matrix)
• Default: np.eye(4) (identity -- sphere centered at the origin)
• The sphere is centered at this matrix's translation component

radius

• Controls: The sphere's radius.
• Units: Meters
• Default: 0.01
• Increase → a larger sphere
• Typical range: 0.001-100.0 meters -- use 0.001-0.1 for small markers, 0.1-1.0 for medium spheres, 1.0-10.0 for large ones

resolution

• Controls: The number of vertices around the sphere.
• Units: Unitless (vertex count)
• Default: 20
• Increase → a smoother sphere with more triangles
• Decrease → a more faceted, low-poly sphere with fewer triangles
• Typical range: 8-64 -- use 8-16 for low-poly, 20-32 for smooth, 32-64 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

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
• Marking a centroid or keypoint at real scale -- place a sphere of a known physical radius at a computed centroid (e.g. from calculate_point_cloud_centroid) for visualization
• 6D pose estimation and detection testing -- use as a reference/template mesh for spherical objects such as balls or rounded components
• Collision checking and simulation -- represent spherical parts as simplified collision geometry

Alternative Skills

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

When Not to Use the Skill

Do not use Create Sphere 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 spherical -- use create_plane_mesh, create_cylinder_mesh, or create_torus_mesh instead
• You need a complex or non-parametric shape -- this Skill only creates simple parametric spheres (radius/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