Project Point Cloud to Plane

SUMMARY

Project Point Cloud to Plane orthogonally projects 3D points onto a plane defined in general form (ax + by + cz + d = 0).

This Skill is useful in industrial, mobile, and humanoid robotics pipelines for flattening or aligning point clouds to planar surfaces. For example, it can project objects onto a conveyor belt plane for inspection, flatten floor scans for mobile robot navigation, or align surfaces for humanoid robot manipulation. By projecting points to a plane, downstream tasks like segmentation, registration, and pose estimation become simpler and more reliable.

Use this Skill when you want to map a point cloud to a general plane for analysis, alignment, or perception workflows.

The Skill

from telekinesis import vitreous

projected_point_cloud = vitreous.project_point_cloud_to_plane(
    point_cloud=point_cloud,
    plane_coefficients=[0.0, 0.0, 1.0, 0.0],
    add_white_noise=False,
    white_noise_standard_deviation=0.0,
)

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 Pointcloud

Unprocessed point cloud. Plane for projection visualized in green.

Projected Pointcloud

Flattened pointcloud.

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" / "engine_parts_0.ply")
point_cloud = io.load_point_cloud(filepath=filepath)
logger.success(f"Loaded point cloud with {len(point_cloud.positions)} points")

# Execute operation
projected_point_cloud = vitreous.project_point_cloud_to_plane(
  point_cloud=point_cloud,
  plane_coefficients=[0.0, 0.0, 1.0, 0.0],
  add_white_noise=False,
  white_noise_standard_deviation=0.0,
)
logger.success(f"Projected {len(projected_point_cloud.positions)} points to plane")

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 project_point_cloud_to_plane

The Explanation of the Code

The code begins by importing the necessary modules: vitreous for point cloud operations, datatypes and io for data handling, pathlib for file path management, and loguru for optional logging.

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

# Optional for logging
from loguru import logger

Next, a point cloud is loaded from a .ply file, and the total number of points is logged to confirm successful loading.

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

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

The key operation uses the project_point_cloud_to_plane Skill. This projects every point in the cloud orthogonally onto a plane defined by general plane coefficients [a, b, c, d]. This projection is commonly applied in robotics and 3D vision pipelines for tasks such as ground plane removal, planar feature extraction, or flattening data for alignment and registration algorithms. Optional white noise can be added to improve numerical stability during downstream computations.

# Execute operation
projected_point_cloud = vitreous.project_point_cloud_to_plane(
  point_cloud=point_cloud,
  plane_coefficients=[0.0, 0.0, 1.0, 0.0],
  add_white_noise=False,
  white_noise_standard_deviation=0.0,
)
logger.success(f"Projected {len(projected_point_cloud.positions)} points to plane")

How to Tune the Parameters

The project_point_cloud_to_plane Skill has three parameters that control the projection:

plane_coefficients (required):

• The plane equation coefficients as [a, b, c, d] where ax + by + cz + d = 0
• The vector [a, b, c] is the plane normal (should be normalized)
• d is the distance from origin
• Can be obtained from plane fitting algorithms (e.g., segment_point_cloud_using_plane)

add_white_noise (default: False):

• Whether to add random noise to the projected points
• True: Adds Gaussian noise to simulate measurement uncertainty or add variation
• False: Projects points exactly onto the plane
• Set to True for simulation/testing, False for exact projection

white_noise_standard_deviation (default: 0.0):

• The standard deviation of the Gaussian noise
• Units: Uses the same units as your point cloud (e.g., if point cloud is in meters, deviation is in meters; if in millimeters, deviation is in millimeters)
• Increase to add more variation to the projected points
• Decrease to add less noise
• Ignored if add_white_noise is False
• Typical range: 0.0-0.01 in point cloud units
• Use 0.0 for no noise, 0.001-0.005 for small variations, 0.005-0.01 for larger variations

TIP

Best practice: Keep add_white_noise=False for exact projection. Use noise only for simulation or testing scenarios. If you need plane coefficients, use segment_point_cloud_using_plane to detect planes first.

Where to Use the Skill in a Pipeline

Point cloud projection to plane is commonly used in the following pipelines:

• Ground plane removal
• Planar feature extraction
• 2D feature analysis
• Alignment and registration preparation

A typical pipeline for ground plane removal looks as follows:

# Example pipeline using point cloud projection (parameters omitted).

from telekinesis import vitreous

# 1. Load 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. Segment ground plane
plane_points = vitreous.segment_point_cloud_using_plane(
    point_cloud=downsampled_cloud,
    distance_threshold=0.01,
    keep_outliers=False,
)

# 4. Get plane coefficients (from plane segmentation result)
# plane_coefficients = [a, b, c, d]  # Extract from plane segmentation

# 5. Project point cloud to plane (optional, for 2D analysis)
projected_cloud = vitreous.project_point_cloud_to_plane(
    point_cloud=downsampled_cloud,
    plane_coefficients=[0.0, 0.0, 1.0, 0.0],
    add_white_noise=False,
    white_noise_standard_deviation=0.0,
)

# 6. Process the projected point cloud

Related skills to build such a pipeline:

• segment_point_cloud_using_plane: detect planes and get plane coefficients
• calculate_plane_normal: extract normal vector from plane coefficients
• filter_point_cloud_using_statistical_outlier_removal: clean input before projection
• project_point_cloud_to_plane_defined_by_point_normal: alternative method using point and normal

Alternative Skills

Skill	vs. Project Point Cloud to Plane
project_point_cloud_to_plane_defined_by_point_normal	Use point+normal when you have a point on the plane and its normal vector. Use plane coefficients when you have plane equation coefficients [a, b, c, d].

When Not to Use the Skill

Do not use project point cloud to plane when:

• You have a point and normal vector (use project_point_cloud_to_plane_defined_by_point_normal instead)
• The plane coefficients are invalid (ensure the normal vector [a, b, c] is normalized)
• You need to preserve 3D structure (projection flattens the point cloud to 2D on the plane)
• The point cloud is empty (the operation will succeed but return an empty point cloud)
• You need non-orthogonal projection (this Skill only performs orthogonal projection)