Filter Point Cloud Using Bounding Box

SUMMARY

Filter Point Cloud Using Bounding Box keeps only the points that fall inside an axis-aligned 3D box.

Like filter_point_cloud_using_pass_through_filter, this crops a point cloud to a box aligned with the world's X/Y/Z axes, but takes the box as a single datatypes.Boxes3D object instead of six separate min/max scalars — convenient when the box already exists as a Boxes3D, for example from calculate_axis_aligned_bounding_box (possibly expanded or translated first), rather than being hand-picked.

Use this Skill when you want to crop a point cloud to a region already expressed as a datatypes.Boxes3D object.

The Skill

from telekinesis import vitreous, datatypes

x_min, y_min, z_min, x_max, y_max, z_max = -163, -100, 470, 150, 100, 544
bbox = datatypes.Boxes3D.from_format(
    [[x_min, y_min, z_min, x_max, y_max, z_max]], source_format="xyzxyz"
)

filtered_point_cloud = vitreous.filter_point_cloud_using_bounding_box(
    point_cloud=point_cloud,
    bbox=bbox,
)

API Reference

Full parameter and return type documentation for filter_point_cloud_using_bounding_box.

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.

Axis-Aligned Bounding Box

Axis-aligned bounding box in red overlayed with the unprocessed point cloud.

Filtered Points

Only the points that fall within the specified 3D box defined by min/max coordinates along each axis are kept.

The Code

"""
Demonstrates filtering points within an axis-aligned bounding box defined by min/max coordinates.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def filter_point_cloud_using_bounding_box_example():
    """
    Filters points within an axis-aligned bounding box.

    Keeps only points that fall within the specified 3D box defined by
    min/max coordinates along each axis.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = (
        "https://assets.telekinesis.ai/examples/v1/point_clouds/plastic_2_raw.ply"
    )
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    x_min, y_min, z_min, x_max, y_max, z_max = -163, -100, 470, 150, 100, 544
    bbox = datatypes.Boxes3D.from_format(
        [[x_min, y_min, z_min, x_max, y_max, z_max]], source_format="xyzxyz"
    )

    filtered_point_cloud = vitreous.filter_point_cloud_using_bounding_box(
        point_cloud=point_cloud, bbox=bbox
    )

    # ===================== Log ================================================
    logger.success(f"Filtered {point_cloud} using bounding box")
    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_bounding_box_example", spawn=True)
    datatypes.visualize(point_cloud, entity_path="/1-input_point_cloud")
    datatypes.visualize(bbox, entity_path="/2-bounding_box")
    datatypes.visualize(filtered_point_cloud, entity_path="/3-filtered_point_cloud")


if __name__ == "__main__":
    filter_point_cloud_using_bounding_box_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_bounding_box.py

Parameter Configuration

bbox is checked as a single 3D box, not decomposed into separate scalar knobs.

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to filter
bbox	datatypes.Boxes3D	required	The axis-aligned box to keep points within. Its native [x, y, z, width, height, depth] layout is converted internally; construct one from min/max corners with datatypes.Boxes3D.from_format([[x_min, y_min, z_min, x_max, y_max, z_max]], source_format="xyzxyz")

Returns

Type	Description
datatypes.PointCloud	A point cloud containing only the points that fell inside bbox. Use .positions for the surviving (N, 3) position array and len(...) for the point count.

Raises

Exception	Condition
TypeError	point_cloud is not a datatypes.PointCloud, or bbox is not a datatypes.Boxes3D (see the Parameter Configuration table above)
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

filter_point_cloud_using_bounding_box has no numeric threshold to tune — bbox is an input defining the region to keep, not a knob with a range to sweep. What you control is the box itself:

bbox

• Controls: Which points are kept — everything inside the box's [x_min, y_min, z_min, x_max, y_max, z_max] extent survives, everything outside is removed.
• Construct it from known corners with datatypes.Boxes3D.from_format([[x_min, y_min, z_min, x_max, y_max, z_max]], source_format="xyzxyz"), or reuse an existing box, such as the result of calculate_axis_aligned_bounding_box (possibly expanded or translated first to add margin).
• Enlarge the box's extent to include more points; shrink it to include fewer.
• Reposition the box (shift the min/max corners together) to move the kept region without changing its size.

TIP

If your region of interest is already expressed as six independent scalars (x_min, x_max, ...) rather than a Boxes3D, filter_point_cloud_using_pass_through_filter skips the extra construction step and takes them directly.

Where to Use the Skill

Common pipelines include:

• Region-of-interest extraction – Isolating a known object footprint once its extent is already known as a box
• Reusing a computed bounding box – Feeding the output of calculate_axis_aligned_bounding_box (possibly expanded for margin) straight into filtering
• Workspace focusing – Restricting processing to a fixed, previously-defined box-shaped workspace
• Background removal – Dropping everything outside a known box-shaped region of the scene

Alternative Skills

Skill	vs. Filter Point Cloud Using Bounding Box
filter_point_cloud_using_pass_through_filter	Takes six separate min/max scalars instead of a datatypes.Boxes3D object. Use it when you have loose bounds rather than an existing box object.
filter_point_cloud_using_oriented_bounding_box	Uses a box that can rotate away from the world's X/Y/Z axes. Use it when the region of interest isn't axis-aligned; use this Skill when it is.

When Not to Use the Skill

Do not use Filter Point Cloud Using Bounding Box when:

• The region of interest is rotated relative to the world axes – use filter_point_cloud_using_oriented_bounding_box instead
• You only have loose min/max scalars, not a Boxes3D object – filter_point_cloud_using_pass_through_filter takes those directly without the extra construction step
• You need to filter by distance from a plane rather than a box – use filter_point_cloud_using_plane_proximity or filter_point_cloud_using_plane_defined_by_point_normal_proximity instead
• bbox isn't a valid datatypes.Boxes3D – a TypeError is raised if point_cloud isn't a datatypes.PointCloud or bbox isn't a datatypes.Boxes3D