Telekinesis Docs

Appearance

Calculate Plane Normal ​

SUMMARY

Calculate Plane Normal extracts the unit normal vector from a plane equation defined by coefficients (ax + by + cz + d = 0).

This Skill is typically used after plane segmentation to obtain a directional representation of a surface, such as the orientation of a table, wall, or floor. The resulting normal vector is normalized, making it directly usable for geometric reasoning, alignment, or comparison.

Use this Skill when you need to understand or reason about surface orientation, for example to align coordinate frames, filter planes by orientation, or decide how a robot should approach or interact with a planar surface.

The Skill ​

python
from telekinesis import vitreous

normal_vector = vitreous.calculate_plane_normal(plane_coefficients=[a, b, c, d])

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 ​

Calculated Normal

The Code ​

python
from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib

# Optional for logging
from loguru import logger

# Execute operation
normal_vector = vitreous.calculate_plane_normal(plane_coefficients=[0.0, 0.0, 1.0, 0.0])
logger.success(
    f"Calculated normal vector to {normal_vector}"
)

The Explanation of the Code ​

This example shows how to use the calculate_plane_normal Skill to extract a unit normal vector from a plane equation. The code first imports the necessary modules and sets up optional logging.

python
from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib

# Optional for logging
from loguru import logger

The operation is executed by passing the plane coefficients [a, b, c, d] in the form ax + by + cz + d = 0. The Skill computes the normalized normal vector [a, b, c], representing the plane's orientation in 3D space. The logger confirms the calculated vector for verification.

python
# Execute operation
normal_vector = vitreous.calculate_plane_normal(plane_coefficients=[0.0, 0.0, 1.0, 0.0])
logger.success(
    f"Calculated normal vector to {normal_vector}"
)

This Skill is particularly useful in robotics perception and manipulation pipelines, such as surface alignment, plane-based segmentation, grasping on planar surfaces, or collision avoidance, where knowing the orientation of a plane is essential for geometric reasoning.

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:

bash
cd telekinesis-examples
python examples/vitreous_examples.py --example calculate_plane_normal

How to Tune the Parameters ​

The calculate_plane_normal Skill has no parameters to tune, it only requires plane_coefficients as input. The plane coefficients should be in the form [a, b, c, d] representing the plane equation ax + by + cz + d = 0.

Where to Use the Skill in a Pipeline ​

Plane normal calculation is commonly used in the following pipelines:

  • Plane segmentation and analysis
  • Surface alignment and registration
  • Grasp planning on planar surfaces
  • Collision avoidance and spatial reasoning

A typical pipeline for plane segmentation and analysis looks as follows:

python
# Example pipeline using plane normal calculation (parameters omitted).

from telekinesis import vitreous

# 1. Load raw point cloud
... = vitreous.load_point_cloud(...)

# 2. Preprocess: remove outliers and downsample
... = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)
... = vitreous.filter_point_cloud_using_voxel_downsampling(...)

# 3. Segment planes from the point cloud
planes = vitreous.segment_point_cloud_using_plane(...)

# 4. For each detected plane, calculate its normal vector
for plane in planes:
    normal = vitreous.calculate_plane_normal(plane_coefficients=plane.coefficients)
    # Use normal for alignment, filtering, or geometric reasoning

# 5. Optional: Filter planes by orientation or use normals for alignment

Related skills to build such a pipeline:

  • filter_point_cloud_using_statistical_outlier_removal: clean input before plane segmentation
  • filter_point_cloud_using_voxel_downsampling: reduce point cloud density for faster processing
  • segment_point_cloud_using_plane: detect planes in the point cloud

Alternative Skills ​

There are no direct alternative skills for calculating plane normals. This Skill is specifically designed to extract the normal vector from plane coefficients.

When Not to Use the Skill ​

Do not use calculate plane normal when:

  • You don't have plane coefficients (you need to segment planes first using segment_point_cloud_using_plane)
  • You only need the plane equation (the coefficients already contain the normal information in [a, b, c])

WARNING

This Skill requires plane coefficients as input. If you only have a point cloud, you must first segment planes using segment_point_cloud_using_plane to obtain the coefficients.