Project Point Cloud to Plane Defined by Point Normal

SUMMARY

Project Point Cloud to Plane Defined by Point Normal projects 3D points onto a plane defined by a reference point and a normal vector.

This Skill is useful in industrial, mobile, and humanoid robotics pipelines for aligning or flattening point clouds onto planar surfaces. For instance, it can project parts onto a reference plane for inspection in manufacturing, flatten floor or wall scans for mobile robot mapping, or align graspable surfaces for humanoid robot manipulation. Projecting onto a plane simplifies computations and ensures consistent geometric reference for downstream tasks like registration, segmentation, or pose estimation.

Use this Skill when you want to map points to a planar surface to standardize geometry or facilitate analysis.

The Skill

from telekinesis import vitreous
import numpy as np

projected_point_cloud = vitreous.project_point_cloud_to_plane_defined_by_point_normal(
    point_cloud=point_cloud,
    point=np.array([0.0, 0.0, 0.0]),
    plane_normal=np.array([0.0, 0.0, 1.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
import numpy as np

# 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
plane_point = np.array([0.0, 0.0, 0.0])
plane_normal = np.array([0.0, 0.0, 1.0])

projected_point_cloud = vitreous.project_point_cloud_to_plane_defined_by_point_normal(
  point_cloud=point_cloud,
  point=plane_point,
  plane_normal=plane_normal,
  add_white_noise=False,
  white_noise_standard_deviation=0.0,
)
logger.success(
  f"Projected {len(projected_point_cloud.positions)} points to plane (point+normal)"
)

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_defined_by_point_normal

The Explanation of the Code

The code starts by importing the required modules: vitreous for point cloud processing, datatypes and io for data handling, pathlib for path management, numpy for numerical operations, and loguru for optional logging.

from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib
import numpy as np

# Optional for logging
from loguru import logger

Next, a point cloud is loaded from a .ply file, and the number of points is logged to ensure the data was correctly loaded.

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 main operation uses the project_point_cloud_to_plane_defined_by_point_normal Skill. This Skill projects all points in the cloud onto a plane defined by a reference point and a normal vector. Each point is orthogonally mapped to the plane, optionally with minimal noise for numerical stability. This operation is commonly used in industrial robotics pipelines for tasks like planar alignment, 2D feature extraction, or preparation for registration algorithms that assume coplanar input data.

# Execute operation
plane_point = np.array([0.0, 0.0, 0.0])
plane_normal = np.array([0.0, 0.0, 1.0])

projected_point_cloud = vitreous.project_point_cloud_to_plane_defined_by_point_normal(
  point_cloud=point_cloud,
  point=plane_point,
  plane_normal=plane_normal,
  add_white_noise=False,
  white_noise_standard_deviation=0.0,
)
logger.success(
  f"Projected {len(projected_point_cloud.positions)} points to plane (point+normal)"
)

How to Tune the Parameters

The project_point_cloud_to_plane_defined_by_point_normal Skill has four parameters that control the projection:

point (required):

• A 3D point that lies on the plane
• Units: Uses the same units as your point cloud (e.g., if point cloud is in meters, point is in meters; if in millimeters, point is in millimeters)
• Defines the plane's position in space
• Any point on the plane can be used
• Typically set to a known point on the plane (e.g., centroid, reference point)

plane_normal (required):

• The normal vector of the plane (perpendicular to the plane surface)
• Should be normalized (unit vector)
• Defines the plane's orientation
• Can be obtained from plane segmentation or estimation algorithms

add_white_noise (default: False):

• Whether to add random noise to the projected points
• True: Adds Gaussian noise to simulate measurement uncertainty
• 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. Ensure plane_normal is normalized (unit vector). Use calculate_point_cloud_centroid to get a reference point on the plane if needed.

Where to Use the Skill in a Pipeline

Point cloud projection to plane (point+normal) is commonly used in the following pipelines:

• Planar surface alignment
• 2D feature extraction
• Ground plane flattening
• Alignment and registration preparation

A typical pipeline for planar surface alignment looks as follows:

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

from telekinesis import vitreous
import numpy as np

# 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 plane to get point and normal
plane_points = vitreous.segment_point_cloud_using_plane(
    point_cloud=downsampled_cloud,
    distance_threshold=0.01,
    keep_outliers=False,
)

# 4. Get reference point (e.g., centroid of plane)
plane_centroid = vitreous.calculate_point_cloud_centroid(point_cloud=plane_points)

# 5. Get plane normal (from plane coefficients or estimation)
plane_normal = np.array([0.0, 0.0, 1.0])  # Example: vertical normal

# 6. Project point cloud to plane
projected_cloud = vitreous.project_point_cloud_to_plane_defined_by_point_normal(
    point_cloud=downsampled_cloud,
    point=plane_centroid,
    plane_normal=plane_normal,
    add_white_noise=False,
    white_noise_standard_deviation=0.0,
)

# 7. Process the projected point cloud

Related skills to build such a pipeline:

• segment_point_cloud_using_plane: detect planes and get plane information
• calculate_point_cloud_centroid: get reference point on the plane
• 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: alternative method using plane coefficients

Alternative Skills

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

When Not to Use the Skill

Do not use project point cloud to plane (point+normal) when:

• You have plane coefficients (use project_point_cloud_to_plane instead)
• The plane normal is not normalized (ensure it's a unit vector)
• 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)
• The point is not on the plane (the projection may not be as expected)