Estimate Principal Axes

SUMMARY

Estimate Principal Axes computes the principal directions of a 3D point cloud, using either PCA or the oriented bounding box (OBB) method.

This Skill is primarily used in industrial robotic manipulation pipelines to determine object orientation and alignment for tasks like grasping, pick-and-place, or packaging. Knowing the principal axes helps the robot align its gripper with the object, plan motions efficiently, and place objects accurately.

Use this Skill when you want to extract object orientation as part of pipelines for grasp planning, pose estimation, or automated bin picking in manufacturing and logistics scenarios.

The Skill

from telekinesis import vitreous

principal_axes = vitreous.estimate_principal_axes(
    point_cloud=point_cloud,
    method='obb',
)

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

Raw Sensor Input

Unprocessed point cloud captured directly from the sensor. Shows full resolution, natural noise, and uneven sampling density.

Calculated Highest Principal Axis

Point cloud with calculated highest principal axis shown in red

The Code

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

# Optional for logging
from loguru import logger

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

# Load point cloud
filepath = str(DATA_DIR / "point_clouds" / "zivid_large_pcb_inspection_cropped_preprocessed.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

# Execute operation
principal_axes = vitreous.estimate_principal_axes(
  point_cloud=point_cloud,
  method="obb",
)
logger.success("Estimated principal axes")

The Explanation of the Code

First, we import the required modules: vitreous for point cloud operations, datatypes and io for data handling, pathlib for constructing file paths, and loguru for optional logging.

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

# Optional for logging
from loguru import logger

Next, we load the point cloud from a .ply file. This gives us the 3D data that will be analyzed to determine the principal directions of the object. Logging confirms the number of points loaded, helping to ensure the data is correct and complete.

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

# Load point cloud
filepath = str(DATA_DIR / "point_clouds" / "zivid_large_pcb_inspection_cropped_preprocessed.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

Finally, the estimate_principal_axes Skill is applied using the oriented bounding box (obb) method. This computes the main axes of variance for the point cloud, which is particularly useful in industrial robotic manipulation pipelines. For example, it can help align objects for pick-and-place, orient tools correctly, or estimate the orientation of objects for inspection and automated assembly tasks. The logging confirms that the principal axes were successfully estimated.

# Execute operation
principal_axes = vitreous.estimate_principal_axes(
  point_cloud=point_cloud,
  method="obb",
)
logger.success("Estimated principal axes")

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 estimate_principal_axes

How to Tune the Parameters

The estimate_principal_axes Skill has one parameter that controls the estimation method:

method (default: 'obb'):

• The method to use for principal axis estimation
• 'obb': Uses the oriented bounding box axes, which may be more robust to outliers. Use this for robust results with noisy data
• 'pca': Uses principal component analysis, which is faster but more sensitive to outliers. Use this for fast computation with clean data
• Default: 'obb'

TIP

Best practice: Use 'obb' for most real-world scenarios where point clouds may contain noise or outliers. Use 'pca' only when you have clean, preprocessed data and need faster computation.

Where to Use the Skill in a Pipeline

Principal axes estimation is commonly used in the following pipelines:

• Grasp planning and manipulation
• Pose estimation and object alignment
• Automated bin picking
• Object orientation analysis

A typical pipeline for grasp planning looks as follows:

# Example pipeline using principal axes estimation (parameters omitted).

from telekinesis import vitreous

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

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

# 3. Cluster to separate objects
clusters = vitreous.cluster_point_cloud_using_dbscan(...)

# 4. For each cluster, estimate principal axes
for cluster in clusters:
    principal_axes = vitreous.estimate_principal_axes(
        point_cloud=cluster,
        method='obb',
    )
    # Use principal axes for grasp planning or alignment

# 5. Optional: Use principal axes for gripper orientation

Related skills to build such a pipeline:

• filter_point_cloud_using_statistical_outlier_removal: clean input before axis estimation
• filter_point_cloud_using_voxel_downsampling: reduce point cloud density for faster processing
• cluster_point_cloud_using_dbscan: separate objects before estimating individual axes
• calculate_oriented_bounding_box: alternative method to get object orientation
• estimate_principal_axis_within_radius: estimate local principal axis instead of global

Alternative Skills

Skill	vs. Estimate Principal Axes
estimate_principal_axis_within_radius	Use estimate_principal_axis_within_radius when you need the principal axis of a local neighborhood. Use estimate_principal_axes when you need the principal axes of the entire point cloud.
calculate_oriented_bounding_box	Use OBB when you need both orientation and size/extent information. Use principal axes when you only need orientation directions.

When Not to Use the Skill

Do not use estimate principal axes when:

• You need local orientation (use estimate_principal_axis_within_radius instead)
• You need size or extent information (use calculate_oriented_bounding_box instead)
• The point cloud is very noisy or sparse (preprocess first or use method='obb' for robustness)
• You need orientation of a specific region (use estimate_principal_axis_within_radius with a reference point)
• The point cloud has no clear dominant direction (the principal axes may not be meaningful)