Segment Point Cloud Using Color

SUMMARY

Segment Point Cloud Using Color keeps only the points whose color is close to a target color.

Each point's color is compared to target_color, and only points within color_distance_threshold of it survive — like a color-range picker in 3D, useful for picking out a red part on a mixed-color conveyor. This is only meaningful for a point cloud that already has per-point colors (point_cloud.has_colors); a point cloud without colors has nothing to compare against.

Use this Skill when you want to isolate points belonging to a specific colored object or region within a point cloud.

The Skill

from telekinesis import vitreous

segmented_point_cloud = vitreous.segment_point_cloud_using_color(
    point_cloud=point_cloud,
    target_color=[255, 0, 0],  # red, 8-bit RGB
    color_distance_threshold=60.0,
)

API Reference

Full parameter and return type documentation for segment_point_cloud_using_color.

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 Pointcloud

Unprocessed point cloud.

Segmented Pointcloud

Segmented pointcloud.

The Code

"""
Demonstrates segmenting points by color similarity to a target color.
"""

from loguru import logger
import rerun as rr

from telekinesis import vitreous, datatypes


def segment_point_cloud_using_color_example():
    """
    Segments points by color similarity to a target color.

    Keeps points whose RGB color is within a distance threshold (Euclidean in
    RGB space) of a target color.
    """
    # ===================== Load Data ==========================================
    point_cloud_url = (
        "https://assets.telekinesis.ai/examples/v1/point_clouds/engine_parts_0.ply"
    )
    point_cloud = datatypes.PointCloud.from_url(url=point_cloud_url, use_cache=True)

    # ===================== Run Skill ==========================================
    segmented_point_cloud = vitreous.segment_point_cloud_using_color(
        target_color=[50, 75, 200],
        color_distance_threshold=60.0,
        point_cloud=point_cloud,
    )

    # ===================== Log ================================================
    logger.success(
        f"Segmented {point_cloud} by color similarity to target color [50, 75, 200] with distance threshold 60.0"
    )
    logger.success(f"Results: {segmented_point_cloud}")
    logger.info(
        f"Segmented point cloud positions shape: {segmented_point_cloud.positions.shape}"
    )
    logger.info(
        f"Segmented point cloud has normals shape: "
        f"{segmented_point_cloud.normals.shape if segmented_point_cloud.has_normals else None}"
    )
    logger.info(
        f"Segmented point cloud has colors shape: "
        f"{segmented_point_cloud.colors.shape if segmented_point_cloud.has_colors else None}"
    )

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


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

Parameter Configuration

These parameters control which points survive the color-similarity comparison; target_color and color_distance_threshold must be expressed in the same color-space units as point_cloud's own colors.

Key	Type	Default	Description
point_cloud	datatypes.PointCloud	required	The point cloud to segment. Must have per-point colors (point_cloud.has_colors) for a meaningful result
target_color	datatypes.Vector3D | np.ndarray | list[int]	required	The color to match, [R, G, B]. Use whichever range matches point_cloud's own color encoding — [0.0, 1.0] for normalized colors, or [0, 255] for 8-bit colors
color_distance_threshold	datatypes.Float | float | int	required	Maximum color-space distance from target_color for a point to be kept; higher keeps more color variation, lower keeps only close matches

Returns

Type	Description
datatypes.PointCloud	A point cloud containing only the points matching target_color. Use .positions/.colors for the surviving (N, 3) arrays, 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 target_color) contains a non-numeric element
ValueError	target_color does not have exactly 3 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 segment_point_cloud_using_color Skill exposes two parameters that together define which points count as a color match.

target_color

• Controls: The [R, G, B] color that every point's own color is compared against.
• Units: Depends on point_cloud's own color encoding — normalized [0.0, 1.0] or 8-bit [0, 255]. Must match whichever encoding the point cloud actually uses.
• Default: required — no default
• Pick a value sampled from (or close to) the object you want to isolate
• Mismatching the encoding (e.g. passing [255, 0, 0] against normalized [0.0, 1.0] colors) silently produces a meaningless comparison
• Typical range: N/A — any valid color in the point cloud's own encoding

color_distance_threshold

• Controls: How far, in color space, a point's color may be from target_color and still be kept.
• Units: Same color-space units as target_color — distance in normalized [0.0, 1.0] or 8-bit [0, 255] color space, matching the point cloud's encoding.
• Default: required — no default
• Increase → keeps points with more color variation (looser matching)
• Decrease → keeps only points very close to the target color (stricter matching)
• Typical range: 0.01–0.5 for normalized colors [0, 1]; 5–100 for 8-bit colors [0, 255] — use the lower end for strict matching, the upper end for lenient matching

TIP

Before calling this Skill, check whether point_cloud's colors are normalized [0.0, 1.0] or 8-bit [0, 255], and choose target_color/color_distance_threshold in that same range. Mixing the two silently produces a threshold that is either far too strict (almost nothing survives) or far too loose (almost everything survives).

Where to Use the Skill

Common pipelines include:

• Object identification by color – isolating a specific colored part or object from a mixed-color scene (e.g. a red part on a mixed-color conveyor)
• Multi-object segmentation before clustering – isolating a color class first, then running cluster_point_cloud_using_dbscan to split it into individual instances
• Color-coded landmark or fixture detection – picking out painted markers, fixtures, or components identified by a known color
• Quality inspection – flagging points or parts whose color deviates from an expected target color

Alternative Skills

Skill	vs. Segment Point Cloud Using Color
segment_point_cloud_using_plane	Segments by geometry (a flat surface) instead of color. Use plane segmentation when objects are distinguished by shape; use color segmentation when they're distinguished by color.
segment_point_cloud_using_vector_proximity	Segments points near a known 3D line/axis instead of by color. Use it for a rod, cable, or edge along a known direction; use color segmentation when the object instead has a distinct color.
cluster_point_cloud_using_dbscan	Groups points by spatial density regardless of color. Use DBSCAN when objects are spatially separated; use color segmentation when objects are touching but colored differently.

When Not to Use the Skill

Do not use Segment Point Cloud Using Color when:

• The point cloud has no per-point colors (point_cloud.has_colors is False) – there is nothing to compare target_color against, so the result won't be meaningful
• Objects share very similar colors – a color-distance comparison alone may not separate them; consider segment_point_cloud_using_plane or segment_point_cloud_using_vector_proximity if they differ geometrically, or cluster_point_cloud_using_dbscan if they're spatially separate
• Color varies significantly across the scene (lighting, sensor inconsistency) – a single fixed target_color/color_distance_threshold pair may not generalize across the whole cloud
• The distinguishing feature is geometry, not color – use segment_point_cloud_using_plane or segment_point_cloud_using_vector_proximity instead

TIP

Check point_cloud.has_colors before calling this Skill. If it's False, attach or load per-point colors first (e.g. from the original RGB-D capture) — this Skill has nothing to compare target_color against otherwise.