Filter Point Cloud Using Plane Proximity

SUMMARY

Filter Point Cloud Using Plane Proximity extracts points that lie within a specified distance from a plane defined in general form (ax + by + cz + d = 0).

This Skill is useful in industrial, mobile, and humanoid robotics pipelines for detecting and isolating planar surfaces. Examples include extracting floors or walls for mobile robot navigation, identifying work surfaces in industrial setups, or finding flat areas for humanoid robot interactions. Filtering points near a plane simplifies downstream perception tasks like segmentation, registration, and pose estimation.

Use this Skill when you want to focus on points close to a plane to enable accurate detection, alignment, or manipulation in your 3D perception pipeline.

The Skill

from telekinesis import vitreous

filtered_point_cloud = vitreous.filter_point_cloud_using_plane_proximity(
    point_cloud=point_cloud,
    plane_coefficients=[0.0, 0.0, 1.0, -0.5],
    distance_threshold=0.01,
)

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.

Extracted Points with a Small Distance

Only points within the specified distance of the plane are retained and points beyond this threshold are removed on either side. This filters out both the cans and the outliers below the plane.
Parameters: distance_threshold = 4 (scene units).

Extracted Points with a Moderate Distance

Raising the distance threshold filters out fewer points. Outliers below the plane are removed, but the cans’ lower-half points remain.
Parameters: distance_threshold = 50 (scene units).

Plane for Extraction

Input point cloud overlayed with the plane for extraction.

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

# Execute operation
# Define plane using coefficients
plane_coefficients = [0.028344755192329624, -0.5747207168510667, -0.8178585895344518, 555.4890362620131]
filtered_point_cloud = vitreous.filter_point_cloud_using_plane_proximity(
  point_cloud=point_cloud,
  plane_coefficients=plane_coefficients,
  distance_threshold=50.0,
)
logger.success("Filtered points using plane proximity")

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 filter_point_cloud_using_plane_proximity

The Explanation of the Code

The example starts by importing essential modules for point cloud manipulation, numerical operations, file handling, and optional logging. The primary modules used here are vitreous, datatypes, io, pathlib, and loguru.

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. Logging is used to confirm the number of points loaded, ensuring the dataset is ready for processing.

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

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

Finally, the filter_point_cloud_using_plane_proximity Skill is applied. The plane is defined using general plane coefficients, and the Skill filters out points that are farther than a specified distance from this plane. This operation is useful in robotics pipelines for tasks like isolating planar surfaces, segmenting regions of interest, or preprocessing point clouds for inspection, manipulation, or 3D perception applications.

# Execute operation
# Define plane using coefficients
plane_coefficients = [0.028344755192329624, -0.5747207168510667, -0.8178585895344518, 555.4890362620131]
filtered_point_cloud = vitreous.filter_point_cloud_using_plane_proximity(
  point_cloud=point_cloud,
  plane_coefficients=plane_coefficients,
  distance_threshold=50.0,
)
logger.success("Filtered points using plane proximity")

How to Tune the Parameters

The filter_point_cloud_using_plane_proximity Skill has two parameters that control the filtering:

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)
• Examples:
  • For a horizontal plane at z=0.5: [0, 0, 1, -0.5]
  • For a plane through origin with normal [1,0,0]: [1, 0, 0, 0]

distance_threshold (required):

• The maximum perpendicular distance from the plane to keep a point
• Units: Uses the same units as your point cloud (e.g., if point cloud is in meters, threshold is in meters; if in millimeters, threshold is in millimeters)
• Increase to keep points farther from the plane, including points on nearby parallel surfaces
• Decrease to keep only points very close to the plane
• Typical range: 0.001-0.1 in point cloud units
• For precise plane extraction, use 0.001-0.01
• For filtering near a plane, use 0.01-0.1

TIP

Best practice: Use segment_point_cloud_using_plane to detect planes and get plane coefficients. Adjust distance_threshold based on your point cloud density and the desired precision.

Where to Use the Skill in a Pipeline

Plane proximity filtering is commonly used in the following pipelines:

• Planar surface extraction
• Ground plane removal
• Tabletop or work surface detection
• Wall or floor identification

A typical pipeline for planar surface extraction looks as follows:

# Example pipeline using plane proximity filtering (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 plane to get plane coefficients
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. Filter point cloud using plane proximity
filtered_cloud = vitreous.filter_point_cloud_using_plane_proximity(
    point_cloud=downsampled_cloud,
    plane_coefficients=[0.0, 0.0, 1.0, -0.5],
    distance_threshold=0.01,
)

# 6. Process the filtered 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 filtering
• filter_point_cloud_using_plane_defined_by_point_normal_proximity: alternative method using point and normal
• filter_point_cloud_using_plane_splitting: alternative for splitting by plane

Alternative Skills

Skill	vs. Filter Point Cloud Using Plane Proximity
filter_point_cloud_using_plane_defined_by_point_normal_proximity	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].
filter_point_cloud_using_plane_splitting	Use plane splitting when you want to keep one side of the plane. Use plane proximity when you want to keep points within a distance threshold on both sides.
segment_point_cloud_using_plane	Use plane segmentation to detect and extract the largest plane. Use plane proximity filtering to extract points near a known plane.

When Not to Use the Skill

Do not use filter point cloud using plane proximity when:

• You have a point and normal vector (use filter_point_cloud_using_plane_defined_by_point_normal_proximity instead)
• You want to keep only one side of the plane (use filter_point_cloud_using_plane_splitting instead)
• The plane coefficients are invalid (ensure the normal vector [a, b, c] is normalized)
• You need to detect planes (use segment_point_cloud_using_plane first to find planes)
• You need to filter based on 3D box regions (use bounding box or passthrough filter instead)