Filter Point Cloud Using Passthrough Filter

SUMMARY

Filter Point Cloud Using Passthrough Filter retains only the points within specified minimum and maximum bounds along each axis, effectively filtering a point cloud by axis-aligned ranges.

This Skill is useful in industrial, mobile, and humanoid robotics pipelines for focusing on specific workspace regions. For instance, it can isolate a conveyor belt area for object detection, select a corridor section for mobile robot navigation, or limit the workspace for a humanoid robot’s arm. By filtering points along individual axes, robots can reduce clutter and speed up downstream processing such as clustering, segmentation, or pose estimation.

Use this Skill when you want to apply simple axis-based cropping to a point cloud for targeted perception or manipulation tasks.

The Skill

from telekinesis import vitreous

filtered_point_cloud = vitreous.filter_point_cloud_using_pass_through_filter(
    point_cloud=point_cloud,
    x_min=-100.0,
    x_max=100.0,
    y_min=-100.0,
    y_max=100.0,
    z_min=-100.0,
    z_max=100.0,
)

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.

Passthrough Filter

Passthrough filter in red overlayed with the unprocessed point cloud. The corners of the box correspond to the min/max bounds for each axis.

Filtered Points

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

The Code

from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib
import numpy as np

# Optional for logging
from loguru import logger

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

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

x_min, y_min, z_min, x_max, y_max, z_max = np.array([-185.0, -164.0, 450.0, 230.0, 164.0, 548.0])

# Execute operation
filtered_point_cloud = vitreous.filter_point_cloud_using_pass_through_filter(
  point_cloud=point_cloud,
  x_min=x_min,
  x_max=x_max,
  y_min=y_min,
  y_max=y_max,
  z_min=z_min,
  z_max=z_max,
)
logger.success("Filtered points using axis-aligned range")

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_pass_through_filter

The Explanation of the Code

This example begins by importing the necessary modules for point cloud processing, data handling, numerical operations, and optional logging. Key imports include vitreous, datatypes, io, numpy, pathlib, and loguru.

from telekinesis import vitreous
from datatypes import datatypes, io
import pathlib
import numpy as np

# Optional for logging
from loguru import logger

Next, a point cloud is loaded from a .ply file. This point cloud contains 3D points representing the geometry of an object or scene. Logging is used to confirm the number of points successfully loaded, ensuring the input is ready for processing.

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

# Load point cloud
filepath = str(DATA_DIR / "point_clouds" / "mounts_3_raw.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_passthrough_filter Skill is applied. This filter uses axis-aligned minimum and maximum bounds along X, Y, and Z to retain only points within a specified range. It is a straightforward way to crop a point cloud to a region of interest. This Skill is especially useful in robotics and industrial pipelines for isolating objects, removing out-of-bound points, or preparing data for downstream tasks like registration, clustering, and manipulation.

x_min, y_min, z_min, x_max, y_max, z_max = np.array([-185.0, -164.0, 450.0, 230.0, 164.0, 548.0])

# Execute operation
filtered_point_cloud = vitreous.filter_point_cloud_using_pass_through_filter(
  point_cloud=point_cloud,
  x_min=x_min,
  x_max=x_max,
  y_min=y_min,
  y_max=y_max,
  z_min=z_min,
  z_max=z_max,
)
logger.success("Filtered points using axis-aligned range")

How to Tune the Parameters

The filter_point_cloud_using_pass_through_filter Skill has six parameters that control the axis-aligned filtering:

x_min, x_max (defaults: -100.0, 100.0):

• Minimum and maximum x coordinates
• Units: Uses the same units as your point cloud (e.g., if point cloud is in meters, bounds are in meters; if in millimeters, bounds are in millimeters)
• Increase x_max or decrease x_min to include more points (expands the box)
• Decrease x_max or increase x_min to include fewer points (shrinks the box)
• x_min should be less than x_max
• Typical range: -100.0 to 100.0 in point cloud units depending on scene scale

y_min, y_max (defaults: -100.0, 100.0):

• Minimum and maximum y coordinates
• Units: Uses the same units as your point cloud
• Increase y_max or decrease y_min to include more points
• Decrease y_max or increase y_min to include fewer points
• y_min should be less than y_max
• Typical range: -100.0 to 100.0 in point cloud units

z_min, z_max (defaults: -100.0, 100.0):

• Minimum and maximum z coordinates
• Units: Uses the same units as your point cloud
• Increase z_max or decrease z_min to include more points
• Decrease z_max or increase z_min to include fewer points
• z_min should be less than z_max
• Typical range: -100.0 to 100.0 in point cloud units

TIP

Best practice: Use calculate_axis_aligned_bounding_box to automatically compute bounds from a point cloud. Manually set bounds when you know the exact region you want to extract.

Where to Use the Skill in a Pipeline

Passthrough filtering is commonly used in the following pipelines:

• Workspace region extraction
• Axis-aligned cropping
• Simple region-of-interest filtering
• Background removal

A typical pipeline for workspace region extraction looks as follows:

# Example pipeline using passthrough filtering (parameters omitted).

from telekinesis import vitreous
import numpy as np

# 1. Load point cloud
point_cloud = vitreous.load_point_cloud(...)

# 2. Preprocess: remove outliers
filtered_cloud = vitreous.filter_point_cloud_using_statistical_outlier_removal(...)

# 3. Optional: Compute bounds from object
bbox = vitreous.calculate_axis_aligned_bounding_box(point_cloud=filtered_cloud)

# 4. Filter point cloud using passthrough filter
# Option A: Use computed bounds
cropped_cloud = vitreous.filter_point_cloud_using_pass_through_filter(
    point_cloud=filtered_cloud,
    x_min=-0.5,
    x_max=0.5,
    y_min=-0.5,
    y_max=0.5,
    z_min=0.0,
    z_max=1.0,
)

# 5. Process the cropped point cloud
clusters = vitreous.cluster_point_cloud_using_dbscan(...)

Related skills to build such a pipeline:

• calculate_axis_aligned_bounding_box: compute bounds from point cloud
• filter_point_cloud_using_bounding_box: alternative using Boxes3D object
• filter_point_cloud_using_statistical_outlier_removal: clean input before filtering
• cluster_point_cloud_using_dbscan: process filtered point clouds

Alternative Skills

Skill	vs. Filter Point Cloud Using Passthrough Filter
filter_point_cloud_using_bounding_box	Use bounding box when you need to use a pre-computed Boxes3D object. Use passthrough filter for simple min/max coordinate filtering.
filter_point_cloud_using_oriented_bounding_box	Use oriented bounding box when you need rotated filtering. Use passthrough filter for axis-aligned filtering.
filter_point_cloud_using_plane_proximity	Use plane proximity when you want to filter based on distance from a plane. Use passthrough filter when you want axis-aligned box filtering.

When Not to Use the Skill

Do not use filter point cloud using passthrough filter when:

• You need rotated/oriented filtering (use filter_point_cloud_using_oriented_bounding_box instead)
• You have a pre-computed Boxes3D object (use filter_point_cloud_using_bounding_box instead)
• You need to filter based on distance from a plane (use filter_point_cloud_using_plane_proximity instead)
• The bounds are invalid (ensure min values are less than max values for each axis)
• You need to filter based on other criteria (use other filtering methods like radius outlier removal, statistical outlier removal, etc.)