Segment Point Cloud Using Vector Proximity

SUMMARY

Segment Point Cloud Using Vector Proximity keeps only the points near an infinite line defined by a point and a direction vector.

It treats reference_point + t * reference_vector (for all real t) as an infinite 3D line, and keeps only the points in point_cloud within distance_threshold (perpendicular distance) of that line — for example to isolate a rod, cable, or edge running along a known axis. Pass keep_outliers=True to invert the selection and keep the points that are not near the line instead.

Use this Skill when you want to isolate points near (or far from) a known 3D line, such as a rod, cable, or edge with a known direction.

The Skill

from telekinesis import vitreous

segmented_point_cloud = vitreous.segment_point_cloud_using_vector_proximity(
    point_cloud=point_cloud,
    reference_point=[0.0, 0.0, 0.0],
    reference_vector=[0.0, 0.0, 1.0],
    distance_threshold=0.1,
    keep_outliers=False,
)

API Reference

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

The Code

"""
Demonstrates segmenting points near a line defined by a point and direction vector.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def segment_point_cloud_using_vector_proximity_example():
    """
    Segments points near a line defined by a point and direction vector.

    Keeps points within a distance threshold of an infinite line through a
    reference point along a direction.
    """
    # ===================== 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 ==========================================
    result_point_cloud = vitreous.segment_point_cloud_using_vector_proximity(
        point_cloud=point_cloud,
        reference_point=[0.0, 0.0, 0.0],
        reference_vector=[0.0, 0.0, 1.0],
        distance_threshold=0.1,
        keep_outliers=False,
    )

    # ===================== Log ================================================
    logger.success(f"Segmented {point_cloud} using vector proximity.")
    logger.success(f"Results: {result_point_cloud}")
    logger.info(
        f"Result point cloud positions shape: {result_point_cloud.positions.shape}"
    )
    logger.info(
        f"Result point cloud has normals shape: "
        f"{result_point_cloud.normals.shape if result_point_cloud.has_normals else None}"
    )
    logger.info(
        f"Result point cloud has colors shape: "
        f"{result_point_cloud.colors.shape if result_point_cloud.has_colors else None}"
    )

    # ===================== Visualization  (Optional) ===========================
    rr.init("segment_point_cloud_using_vector_proximity_example", spawn=True)
    datatypes.visualize(point_cloud, entity_path="/1-input_point_cloud")
    datatypes.visualize(result_point_cloud, entity_path="/2-segmented_point_cloud")


if __name__ == "__main__":
    segment_point_cloud_using_vector_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/segment_point_cloud_using_vector_proximity.py

Parameter Configuration

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to segment.
reference_point	datatypes.Point3D | np.ndarray | list[float]	required	Any 3D point [x, y, z] that the reference line passes through. Must have exactly 3 elements.
reference_vector	datatypes.Vector3D | np.ndarray | list[float]	required	The line's direction [x, y, z]. Should be a unit vector, and must not be the zero vector; must have exactly 3 elements.
distance_threshold	datatypes.Float | float | int	required	Maximum perpendicular distance from the line, in the point cloud's coordinate units, for a point to be kept. Must be > 0.
keep_outliers	datatypes.Bool | bool	False	If True, returns the points that are not near the line (outliers) instead of the points that are (inliers).

Returns

Type	Description
datatypes.PointCloud	The points near the line (or the outliers, if keep_outliers=True); returns an empty datatypes.PointCloud if none qualify. 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, or (for a list reference_point/reference_vector) contains a non-numeric element (see the Parameter Configuration table above)
ValueError	reference_point or reference_vector does not have exactly 3 elements, or distance_threshold is not greater than 0
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

reference_point / reference_vector

• Controls: Together, these define the infinite 3D line that distance_threshold is measured from — reference_point is any point the line passes through, reference_vector is its direction.
• Units: The point cloud's coordinate units
• Default: required — no default, must be supplied
• reference_vector should be a unit vector and must not be the zero vector, or a ValueError is raised
• Derive these from known geometry (e.g. a CAD axis) or from a prior estimate, such as estimate_principal_axes/estimate_principal_axis_within_radius, when the line's direction isn't already known

distance_threshold

• Controls: How far (perpendicular to the line) a point can be and still count as "near" it.
• Units: The point cloud's coordinate units
• Default: required — no default, must be supplied
• Increase → keeps a wider cylinder of points around the line
• Decrease → keeps only points very close to the line
• Must be > 0, or a ValueError is raised
• Scale it to the object's expected radius (e.g. a rod's radius plus some margin for sensor noise)

keep_outliers

• Controls: Whether to keep the points near the line (False, default) or everything else (True).
• Default: False
• Flip to True when you want to remove a known linear structure (e.g. a cable) rather than isolate it

TIP

If you don't already know reference_vector, estimate it first with estimate_principal_axes or estimate_principal_axis_within_radius on a rough region containing the linear structure, then feed that direction into this Skill for a cleaner segmentation.

Where to Use the Skill

Common pipelines include:

• Cable/wire isolation – keeping only the points that make up a cable or wire running along a known direction
• Rod/pipe segmentation – isolating a rod- or pipe-shaped object from surrounding clutter along its known axis
• Edge extraction – keeping points near a known linear edge for further analysis
• Linear-structure removal – setting keep_outliers=True to strip out a known cable or rod before processing the rest of the scene

Alternative Skills

Skill	vs. Segment Point Cloud Using Vector Proximity
filter_point_cloud_using_plane_defined_by_point_normal_proximity	Segments by proximity to a plane (point + normal) instead of a line (point + direction) — use it for flat regions rather than linear structures.
segment_point_cloud_using_plane	Fits a plane automatically via RANSAC rather than requiring a known plane. There's no line-fitting equivalent Skill — if you don't already know reference_point/reference_vector, estimate them with estimate_principal_axes/estimate_principal_axis_within_radius first.
segment_point_cloud_using_color	Segments by color similarity instead of geometric proximity to a line.

When Not to Use the Skill

Do not use Segment Point Cloud Using Vector Proximity when:

• You don't know the line's direction – estimate it first, e.g. with estimate_principal_axes or estimate_principal_axis_within_radius, or use a different segmentation approach such as segment_point_cloud_using_plane or segment_point_cloud_using_color
• The structure of interest isn't linear – for a flat region, use filter_point_cloud_using_plane_defined_by_point_normal_proximity or segment_point_cloud_using_plane instead
• You need to segment by color rather than geometry – use segment_point_cloud_using_color instead

TIP

reference_vector doesn't need to be pre-normalized to a unit vector for the math to work, but the SDK's own docstring recommends it — pass a normalized vector for predictable, consistent results.