Filter Point Cloud Using Plane Defined by Point Normal Proximity

SUMMARY

Filter Point Cloud Using Plane Defined by Point Normal Proximity keeps only the points within a given distance of a plane specified by a point on it plus its normal direction.

A point survives if its perpendicular distance to the plane is within distance_threshold — the plane itself is defined here by any point plane_point that lies on it plus the plane's normal direction plane_normal, rather than [a, b, c, d] equation coefficients. This Skill is equivalent to filter_point_cloud_using_plane_proximity, just with a more geometrically direct way to specify the plane; use calculate_plane_normal to get a normal from coefficients, or the reverse if you have a point + normal and need coefficients.

Use this Skill when you want to filter a point cloud to a thin band around a plane you already have as a point and a normal direction.

The Skill

from telekinesis import vitreous
import numpy as np

filtered_point_cloud = vitreous.filter_point_cloud_using_plane_defined_by_point_normal_proximity(
    point_cloud=point_cloud,
    plane_point=np.array([0.0, 0.0, 0.5]),
    plane_normal=np.array([0.0, 0.0, 1.0]),
    distance_threshold=0.01,
)

API Reference

Full parameter and return type documentation for filter_point_cloud_using_plane_defined_by_point_normal_proximity.

View Reference →

Data Transfer Notice

There is no longer a fixed limit of 1 million points per request. However, very large datasets may result in slower data transfer and processing times. We are continuously optimizing performance as part of our beta program, with ongoing improvements to enhance speed and reliability.

Example

Raw Sensor Input

Unprocessed point cloud captured directly from the sensor.

Plane for Extraction

Input point cloud overlayed with the plane for extraction.

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).

The Code

"""
Demonstrates filtering points near a plane defined by a point and normal vector.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def filter_point_cloud_using_plane_defined_by_point_normal_proximity_example():
    """
    Filters points near a plane defined by a point and normal vector.

    Keeps points within a distance threshold of a plane specified by a point
    on the plane and its normal vector.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = "https://assets.telekinesis.ai/examples/v1/point_clouds/can_vertical_3_downsampled.ply"
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    filtered_point_cloud = (
        vitreous.filter_point_cloud_using_plane_defined_by_point_normal_proximity(
            distance_threshold=4.0,
            point_cloud=point_cloud,
            plane_point=[-15.74520074, 319.25105712, 454.3114797],
            plane_normal=[
                0.028344755192329624,
                -0.5747207168510667,
                -0.8178585895344518,
            ],
        )
    )

    # ===================== Log ================================================
    logger.success(f"Filtered {point_cloud} using plane defined by point and normal")
    logger.success(f"Results: {filtered_point_cloud}")
    logger.info(
        f"Filtered point cloud positions shape: {filtered_point_cloud.positions.shape}"
    )
    logger.info(
        f"Filtered point cloud has normals shape: "
        f"{filtered_point_cloud.normals.shape if filtered_point_cloud.has_normals else None}"
    )
    logger.info(
        f"Filtered point cloud has colors shape: "
        f"{filtered_point_cloud.colors.shape if filtered_point_cloud.has_colors else None}"
    )

    # ===================== Visualization  (Optional) ===========================
    rr.init(
        "filter_point_cloud_using_plane_defined_by_point_normal_proximity_example",
        spawn=True,
    )
    datatypes.visualize(point_cloud, entity_path="/1-input_point_cloud")
    datatypes.visualize(filtered_point_cloud, entity_path="/2-filtered_point_cloud")


if __name__ == "__main__":
    filter_point_cloud_using_plane_defined_by_point_normal_proximity_example()

Runnable examples are available in the Telekinesis examples repository.

Follow the README in that repository to set up the environment, run this specific example with:

cd telekinesis-examples
python examples/point_cloud/filter_point_cloud_using_plane_defined_by_point_normal_proximity.py

Parameter Configuration

All three parameters are required — this Skill has no defaults to fall back on.

Parameter	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to filter
plane_point	datatypes.Point3D | np.ndarray | list[float]	required	Any 3D point [x, y, z] that lies on the plane — defines the plane's position in space. Typically from plane fitting (e.g. segment_point_cloud_using_plane) or a manually chosen point
plane_normal	datatypes.Vector3D | np.ndarray | list[float]	required	The plane's normal direction [x, y, z], perpendicular to its surface — should be a unit vector. Its sign determines which side of the plane is "positive"
distance_threshold	datatypes.Float | float | int	required	Maximum perpendicular distance from the plane, in the point cloud's coordinate units, for a point to be kept. Must be > 0

Returns

Type	Description
datatypes.PointCloud	A point cloud containing only the points within distance_threshold of the plane; returns an empty datatypes.PointCloud if none are. Colors and normals from point_cloud are not carried over. Use .positions for the surviving (N, 3) position array and len(...) for the point count.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type, or (for a list plane_point/plane_normal) contains a non-numeric element (see the Parameter Configuration table above)
ValueError	plane_point or plane_normal does not have exactly 3 elements, or distance_threshold is <= 0
ConfigurationError	The TELEKINESIS_API_KEY environment variable is not set
SerializationError	The request input failed to serialize, the response was not returned as an Arrow stream, or the response failed to deserialize
RequestTimeoutError	The request to the Vitreous service timed out
TransportError	A network failure occurred before a response was received
ClientError	The Vitreous service rejected the request due to invalid or malformed input (HTTP 400/422), an unrecognized endpoint (HTTP 404), or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired (HTTP 401)
AuthenticationServiceError	The authentication service returned an invalid response, was temporarily unavailable, or timed out (HTTP 502/503/504)
ServerError	The Vitreous service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

The filter_point_cloud_using_plane_defined_by_point_normal_proximity skill exposes three parameters — a reference point, a normal direction, and a distance threshold — that together define the thin band of space kept around the plane.

plane_point

• Controls: The plane's position in space — any point known to lie on the plane.
• Units: The point cloud's coordinate units (see the tip below)
• Typically obtained from plane fitting (e.g. segment_point_cloud_using_plane) or a manually chosen point known to sit on the surface
• Any point on the plane works equally well — there's no "more correct" choice among them

plane_normal

• Controls: The plane's orientation — the direction perpendicular to its surface.
• Should be a unit vector (normalized)
• Its sign determines which side of the plane is treated as "positive" — for a horizontal plane use [0, 0, 1] or [0, 0, -1]; for a vertical plane use [1, 0, 0], [0, 1, 0], etc.
• Get one from plane coefficients with calculate_plane_normal if you only have [a, b, c, d]

distance_threshold

• Controls: How far from the plane, on either side, a point can be and still be kept.
• Units: The point cloud's coordinate units
• Must be > 0 — a value of 0 or less raises a ValueError
• Increase → keeps points farther from the plane, including points on nearby parallel surfaces
• Decrease → keeps only points very close to the plane
• Typical range: 0.001–0.1 — use 0.001–0.01 for precise plane extraction, 0.01–0.1 for a looser filter near the plane

TIP

distance_threshold is in whatever length unit your point cloud is actually stored in, not necessarily meters — a value of 4.0 is a reasonable near-plane tolerance for a point cloud whose coordinates run into the hundreds (effectively millimeters), but would be an enormous, everything-passes tolerance for a point cloud genuinely measured in meters. Sanity-check against point_cloud.positions's actual scale before picking a value.

Where to Use the Skill

Common pipelines include:

• Tabletop or work-surface extraction – Isolating a known planar surface once its point and normal are known
• Floor or wall identification – Extracting mapped planar structure in mobile robot navigation
• Post-fit refinement – Re-filtering with a point+normal pair derived from segment_point_cloud_using_plane's output via calculate_plane_normal
• Thin-slice extraction – Keeping only a narrow band of points around a known reference plane for inspection

Alternative Skills

Skill	vs. Filter Point Cloud Using Plane Defined by Point Normal Proximity
filter_point_cloud_using_plane_proximity	Equivalent filtering behavior, but specifies the plane using [a, b, c, d] equation coefficients instead of a point + normal. Use whichever form of the plane you already have on hand.
filter_point_cloud_using_plane_splitting	Splits the whole cloud into two half-spaces at the plane and keeps everything on one side, instead of a thin band near it. Use plane splitting to cut a scene in half; use this Skill to isolate the plane itself.
segment_point_cloud_using_plane	Detects the largest plane in a point cloud via RANSAC and returns both its inlier points and its [a, b, c, d] equation. Use it first to find a plane you don't already have a point/normal for.

When Not to Use the Skill

Do not use Filter Point Cloud Using Plane Defined by Point Normal Proximity when:

• You already have [a, b, c, d] plane coefficients – filter_point_cloud_using_plane_proximity takes them directly without converting to a point + normal
• plane_normal isn't normalized – the Skill assumes a unit vector; normalize it first for a distance_threshold that means what you expect
• You want to keep one whole side of the plane, not a thin band near it – use filter_point_cloud_using_plane_splitting instead
• You don't yet know where the plane is – run segment_point_cloud_using_plane first to detect one
• You need to filter by a 3D box region instead of a plane – use filter_point_cloud_using_bounding_box, filter_point_cloud_using_oriented_bounding_box, or filter_point_cloud_using_pass_through_filter instead