Filter Point Cloud Using Radius Outlier Removal

SUMMARY

Filter Point Cloud Using Radius Outlier Removal removes isolated points that don't have enough neighbors within a fixed search radius.

For every point, it counts how many other points fall within neighborhood_radius, and drops the point if that count is below num_points. This is a simple, geometric way to remove sparse or isolated noise points. Compare with filter_point_cloud_using_statistical_outlier_removal, which instead flags outliers using each point's average neighbor distance relative to the whole cloud's distance statistics — radius outlier removal is simpler and more predictable, while statistical removal adapts better to point clouds with varying density.

Use this Skill when you want to remove sparse or isolated noise points using a fixed, predictable search radius.

The Skill

from telekinesis import vitreous

filtered_point_cloud = vitreous.filter_point_cloud_using_radius_outlier_removal(
    point_cloud=point_cloud,
    num_points=75,
    neighborhood_radius=25,
)

API Reference

Full parameter and return type documentation for filter_point_cloud_using_radius_outlier_removal.

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

Note: The effect of radius-based outlier removal depends heavily on the density and scale of the input point cloud. The parameter values shown below (num_points and neighborhood_radius) are only examples, different datasets may require larger or smaller radii and neighbor counts to achieve similar results. Always tune the parameters according to the point spacing and physical size of your scene.

Raw Sensor Input

Unprocessed point cloud captured directly from the sensor. Contains sparse speckle noise and isolated outlier points.

Mild Outlier Removal

Light filtering that removes only the most isolated noisy points while preserving all valid structures.
Parameters: num_points = 50, neighborhood_radius = 50.

Moderate Outlier Removal

Balanced filtering that removes most sparse clutter and small isolated clusters while keeping overall structure intact.
Parameters: num_points = 75, neighborhood_radius = 35.

Aggressive Outlier Removal

Strong outlier removal that produces a very clean point cloud but may remove thin structures and surface-edge details.
Parameters: num_points = 75, neighborhood_radius = 25.

The Code

"""
Demonstrates removing points with too few neighbors within a radius.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def filter_point_cloud_using_radius_outlier_removal_example():
    """
    Removes points with too few neighbors within a radius.

    Removes points that have fewer than a specified number of neighbors within
    a given radius.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = "https://assets.telekinesis.ai/examples/v1/point_clouds/engine_parts_1_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_radius_outlier_removal(
        num_points=75, neighborhood_radius=25, point_cloud=point_cloud
    )

    # ===================== Log ================================================
    logger.success(f"Filtered {point_cloud} using radius outlier removal")
    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_radius_outlier_removal_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_radius_outlier_removal_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_radius_outlier_removal.py

Parameter Configuration

Parameter	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to filter
num_points	datatypes.Int | int	required	The minimum number of neighbors, within neighborhood_radius, a point needs to be kept. Must be > 0
neighborhood_radius	datatypes.Float | float | int	required	The search radius, in the point cloud's coordinate units, used to count neighbors around each point. Must be > 0

Returns

Type	Description
datatypes.PointCloud	A point cloud with the sparse/isolated points removed; returns an empty datatypes.PointCloud if every point is removed. 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)
ValueError	num_points or neighborhood_radius is not > 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_radius_outlier_removal Skill exposes two parameters that together define how much local support a point needs to survive.

num_points

• Controls: The minimum number of neighbors, within neighborhood_radius, a point needs to be kept.
• Units: Count (integer), must be > 0
• Default: required — no default
• Increase → removes more points (stricter, keeps only points in dense regions)
• Decrease → keeps more points but may leave some outliers
• Typical range: 3–20 — use 5–10 for dense point clouds, 3–5 for sparse ones; set based on the point density you expect

neighborhood_radius

• Controls: The search radius, in the point cloud's coordinate units, used to count neighbors around each point.
• Units: The point cloud's coordinate units (commonly meters), must be > 0
• Default: required — no default
• Increase → considers a larger area (less sensitive to local density variation, but may remove valid points in genuinely sparse regions)
• Decrease → more locally sensitive, but may miss outliers in sparse areas
• Set to roughly 2–3x the typical point spacing in your cloud
• Typical range: 0.01–0.1 meters for small objects, 0.1–1.0 for larger scenes

TIP

Set neighborhood_radius to roughly 2–3x your point spacing first, then adjust num_points up for dense clouds or down for sparse ones based on how much noise is left.

Where to Use the Skill

Common pipelines include:

• Point cloud denoising – removing sensor speckle noise before further processing
• Preprocessing before segmentation – cleaning a cloud before segment_point_cloud_using_plane or clustering
• Noise removal for registration – improving register_point_clouds_using_point_to_point_icp accuracy by removing outliers first
• Data cleaning for clustering – reducing spurious small clusters produced by isolated noise points

Alternative Skills

Skill	vs. Filter Point Cloud Using Radius Outlier Removal
filter_point_cloud_using_statistical_outlier_removal	Flags outliers using each point's average neighbor distance relative to the whole cloud's distance statistics instead of a fixed radius. Handles varying point density better, at the cost of being less predictable.

When Not to Use the Skill

Do not use Filter Point Cloud Using Radius Outlier Removal when:

• The point cloud has strongly varying density – a single fixed neighborhood_radius may over-remove sparse regions while under-removing dense ones; use filter_point_cloud_using_statistical_outlier_removal instead
• You need to preserve thin structures – points on thin edges may have too few neighbors within the radius and get removed along with real noise
• The point cloud is already very sparse overall – the filter may remove too many valid points if num_points isn't lowered to match

TIP

If results are inconsistent across scenes captured at different distances or densities, that's a sign the cloud's density varies more than a fixed radius can handle well — try filter_point_cloud_using_statistical_outlier_removal instead.