Filter Point Cloud Using Plane Splitting

SUMMARY

Filter Point Cloud Using Plane Splitting splits a point cloud in two at a plane and keeps only the points on one side.

Given the plane's [a, b, c, d] equation coefficients, every point is evaluated against ax + by + cz + d; keep_positive_side=True keeps the points where that expression is positive (the side the normal points toward), False keeps the negative side. Unlike filter_point_cloud_using_plane_proximity, which keeps only a thin band of points near the plane, this splits the whole cloud into two half-spaces and keeps everything on one side — useful for cutting a scene in half (e.g. removing everything below a table plane) rather than isolating the plane itself.

Use this Skill when you want to keep only the points on one side of a plane, discarding the rest of the cloud outright.

The Skill

from telekinesis import vitreous

filtered_point_cloud = vitreous.filter_point_cloud_using_plane_splitting(
    point_cloud=point_cloud,
    plane_coefficients=[0, 0, 1, -547],
    keep_positive_side=False,
)

API Reference

Full parameter and return type documentation for filter_point_cloud_using_plane_splitting.

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. Shows full resolution, natural noise, and uneven sampling density.

Splitted Points

Filtered points on the negative side of the red plane.

Raw Sensor Input with Splitting Plane

Splitting Plane shown in red.

The Code

"""
Demonstrates splitting a point cloud by a plane, keeping one side.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def filter_point_cloud_using_plane_splitting_example():
    """
    Splits a point cloud by a plane, keeping one side.

    Divides a point cloud using a plane and keeps points on either the positive
    or negative side.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = (
        "https://assets.telekinesis.ai/examples/v1/point_clouds/mounts_3_raw.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_splitting(
        keep_positive_side=False,
        point_cloud=point_cloud,
        plane_coefficients=[0, 0, 1, -547],
    )

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

Parameter Configuration

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to split
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; the sign of ax + by + cz + d for a given point determines which side it's on
keep_positive_side	datatypes.Bool | bool	required	Which half-space to keep. True keeps points where ax + by + cz + d > 0 (the side the normal points toward); False keeps points where it's < 0

Returns

Type	Description
datatypes.PointCloud	A point cloud containing only the points on the selected side 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_splitting Skill exposes the plane's equation coefficients and a side selector that together determine which half of the cloud survives.

plane_coefficients

• Controls: The plane ax + by + cz + d = 0 used to split the cloud. [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
• 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]

keep_positive_side

• Controls: Which of the two half-spaces created by the plane is kept.
• Units: Boolean
• Default: required — no default
• True keeps points where ax + by + cz + d > 0 — the side the plane's normal vector points toward
• False keeps points where ax + by + cz + d < 0 — the opposite side
• If you're unsure which side is "positive" for your plane, try both and inspect which one keeps the region you want

TIP

Get plane_coefficients from segment_point_cloud_using_plane, then test both True and False for keep_positive_side on a small sample if the sign convention of the fitted normal isn't obvious.

Where to Use the Skill

Common pipelines include:

• Ground plane removal – keep everything above the floor plane and discard the floor itself
• Workspace segmentation – isolate the reachable half-space in front of a robot arm
• Object separation – split objects on either side of a conveyor, wall, or divider
• Half-space extraction – cut away background geometry that lies entirely on one side of a known plane

Alternative Skills

Skill	vs. Filter Point Cloud Using Plane Splitting
filter_point_cloud_using_plane_proximity	Keeps only a thin band of points near the plane on both sides, instead of a whole half-space. Use it to isolate the plane itself rather than cut the scene in half.
filter_point_cloud_using_plane_defined_by_point_normal_proximity	Also filters relative to a plane, but specifies it as a point plus a normal and keeps a band near it rather than splitting by side.
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 Splitting when:

• You want to keep only a thin band of points near the plane on both sides – use filter_point_cloud_using_plane_proximity instead
• 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 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 the sign test is still valid but distances derived from d won't correspond to real-world units