Filter Point Cloud Using Plane Proximity

SUMMARY

Filter Point Cloud Using Plane Proximity keeps only the points that lie within a set distance of a plane, given the plane's [a, b, c, d] equation coefficients.

A point is kept if its perpendicular distance to the plane ax + by + cz + d = 0 is within distance_threshold. This is equivalent to filter_point_cloud_using_plane_defined_by_point_normal_proximity, just specifying the plane by its [a, b, c, d] coefficients (e.g. straight from segment_point_cloud_using_plane's plane_model output) instead of a point and a normal. Unlike filter_point_cloud_using_plane_splitting, which divides the whole cloud into two half-spaces, this keeps only a thin band of points near the plane on both sides.

Use this Skill when you want to isolate the points that lie on or near a known plane, using the plane's equation coefficients.

The Skill

from telekinesis import vitreous

filtered_point_cloud = vitreous.filter_point_cloud_using_plane_proximity(
    point_cloud=point_cloud,
    plane_coefficients=[0.0283, -0.5747, -0.8179, 555.489],
    distance_threshold=4.0,
)

API Reference

Full parameter and return type documentation for filter_point_cloud_using_plane_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.

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

"""
Demonstrates filtering points near a plane defined by its equation coefficients.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def filter_point_cloud_using_plane_proximity_example():
    """
    Filters points near a plane defined by coefficients.

    Keeps points within a distance threshold of a plane specified by its
    equation coefficients (ax + by + cz + d = 0).
    """
    # ===================== 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_proximity(
        distance_threshold=4.0,
        point_cloud=point_cloud,
        plane_coefficients=[
            0.028344755192329624,
            -0.5747207168510667,
            -0.8178585895344518,
            555.4890362620131,
        ],
    )

    # ===================== Log ================================================
    logger.success(f"Filtered {point_cloud} using plane proximity")
    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_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_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_proximity.py

Parameter Configuration

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to filter
plane_coefficients	datatypes.Vector4D | np.ndarray | list[float]	required	The plane equation coefficients [a, b, c, d] where ax + by + cz + d = 0. [a, b, c] is the plane normal (should be normalized) and d is the signed distance from the origin. Often obtained from segment_point_cloud_using_plane
distance_threshold	datatypes.Float | float | int	required	The maximum perpendicular distance from the plane, in meters, for a point to be kept

Returns

Type	Description
datatypes.PointCloud	A point cloud containing only the points within distance_threshold of the plane. 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 (see the Parameter Configuration table above), or (for a list plane_coefficients) it contains a non-numeric element
ValueError	plane_coefficients does not have exactly 4 elements
ConfigurationError	The TELEKINESIS_API_KEY environment variable is not set
SerializationError	The request input failed to serialize, 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 input, invalid data, or another unexpected 4xx response
AuthenticationError	The API key was rejected as invalid or expired
AuthenticationServiceError	The authentication service was unavailable
ServerError	The Vitreous service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

The filter_point_cloud_using_plane_proximity Skill exposes the plane's equation coefficients and a distance threshold that together define the thin band of points kept around the plane.

plane_coefficients

• Controls: The plane ax + by + cz + d = 0 that distances are measured against. [a, b, c] is the plane normal (should be normalized) and d is the signed distance from the origin.
• Units: Dimensionless normal components; d shares the point cloud's distance units (meters)
• Default: required — no default
• Obtain it from a plane-fitting skill such as segment_point_cloud_using_plane, whose plane_model output is already in [a, b, c, d] form
• Example: a horizontal plane at z=0.5 is [0, 0, 1, -0.5]; a plane through the origin with normal [1, 0, 0] is [1, 0, 0, 0]

distance_threshold

• Controls: The maximum perpendicular distance from the plane, in meters, that a point may have and still be kept.
• Units: Meters
• Default: required — no default
• 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 meters — use 0.001–0.01 for precise plane extraction, 0.01–0.1 for a looser filter near the plane

TIP

Get plane_coefficients from segment_point_cloud_using_plane rather than fitting a plane by hand, and start with a small distance_threshold (0.001–0.01) when you need a precise slice of the plane, widening it only if too many valid points are being dropped.

Where to Use the Skill

Common pipelines include:

• Planar surface extraction – isolating a wall, floor, or panel for further analysis
• Ground plane removal – keeping the thin band around the floor plane separate from objects sitting on it
• Tabletop or work-surface detection – isolating a work surface in an industrial robotics cell
• Preprocessing before segmentation or registration – narrowing a scene down to a known planar region before running heavier skills

Alternative Skills

Skill	vs. Filter Point Cloud Using Plane Proximity
filter_point_cloud_using_plane_defined_by_point_normal_proximity	Equivalent filtering, but the plane is specified as a point plus a normal vector instead of [a, b, c, d] coefficients. Use whichever form your plane data is already in.
filter_point_cloud_using_plane_splitting	Splits the whole cloud into two half-spaces and keeps one side, instead of a thin band near the plane. Use it to cut a scene in half rather than isolate the plane itself.
segment_point_cloud_using_plane	Detects and fits the dominant plane in a cloud, producing the plane_coefficients this Skill consumes. Run it first if you don't already have plane coefficients.

When Not to Use the Skill

Do not use Filter Point Cloud Using Plane Proximity when:

• You have a point and a normal vector rather than [a, b, c, d] coefficients – use filter_point_cloud_using_plane_defined_by_point_normal_proximity instead
• You want to keep an entire half-space rather than a thin band near the plane – use filter_point_cloud_using_plane_splitting instead
• You don't yet know the plane's coefficients – run segment_point_cloud_using_plane first to fit the plane
• The plane normal [a, b, c] isn't normalized – normalize it first, otherwise distance_threshold won't correspond to real-world distances