Filter Segments By Color

SUMMARY

Filter Segments By Color filters superpixels based on color.

Filter Segments By Color removes superpixels that fall outside a specified color range. This is useful for keeping only superpixels with specific color characteristics, such as filtering for objects of a particular color.

Use this Skill when you want to filter superpixels by their average color values.

The Skill

from telekinesis import cornea

result = cornea.filter_segments_by_color(
    image=image,
    labels=labels,
    min_color=0,
    max_color=125.0,
)

API Reference

Example

Input Image

Original image with superpixels

Output Image

Filtered image - only superpixels within color range shown

The Code

import pathlib

from telekinesis import cornea
from datatypes import datatypes, io

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

# Load image
filepath = str(DATA_DIR / "images" / "eggs_carton.jpg")
image = io.load_image(filepath=filepath)

# First, generate superpixels using Felzenszwalb
result_felzenszwalb = cornea.segment_image_using_felzenszwalb(
    image=image,
    scale=500,
    sigma=1,
    min_size=200,
)

# Extract superpixel labels
superpixel_labels = result_felzenszwalb["annotation"].to_dict()['labeled_mask']
superpixel_labels = datatypes.Image(superpixel_labels)

# Filter superpixels based on color (keep darker regions only)
result = cornea.filter_segments_by_color(
    image=image,
    labels=superpixel_labels,
    min_color=0,
    max_color=125.0,
)

# Access results
annotation = result["annotation"].to_dict()
mask = annotation['labeled_mask']

The Explanation of the Code

Filter Segments By Color computes the average color intensity for each superpixel and keeps only those within the specified color range.

The code begins by importing the required modules, loading an image, and generating superpixels:

import pathlib

from telekinesis import cornea
from datatypes import datatypes, io

DATA_DIR = pathlib.Path("path/to/telekinesis-data")
filepath = str(DATA_DIR / "images" / "eggs_carton.jpg")
image = io.load_image(filepath=filepath)

# Generate superpixels first
result_felzenszwalb = cornea.segment_image_using_felzenszwalb(
    image=image,
    scale=500,
    sigma=1,
    min_size=200,
)

superpixel_labels = result_felzenszwalb["annotation"].to_dict()['labeled_mask']
superpixel_labels = datatypes.Image(superpixel_labels)

The filter parameters are configured to show darker regions only (average color intensity 0-125):

result = cornea.filter_segments_by_color(
    image=image,
    labels=superpixel_labels,
    min_color=0,
    max_color=125.0,
)

The function returns a dictionary containing an annotation object. Extract the mask as follows:

annotation = result["annotation"].to_dict()
mask = annotation['labeled_mask']

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/cornea_examples.py --example filter_segments_by_color

How to Tune the Parameters

The filter_segments_by_color Skill has 3 parameters:

labels (required):

• Label image from superpixel segmentation
• Units: Image object
• Each unique value represents a different superpixel

min_color (default: 0.0):

• Minimum color value for keeping segments
• Units: Pixel intensity (0-255)
• Decrease to include darker colors
• Increase to exclude darker colors
• Typical range: 0-200

max_color (default: 255.0):

• Maximum color value for keeping segments
• Units: Pixel intensity (0-255)
• Increase to include brighter colors
• Decrease to exclude brighter colors
• Typical range: 50-255

TIP

Best practice: Use color analysis of target objects to determine appropriate color ranges. Adjust bounds to capture desired colors while excluding background.

Where to Use the Skill in a Pipeline

Filter Segments By Color is commonly used in the following pipelines:

• Color-based object filtering - Keep only objects of specific colors
• Background removal - Remove background-colored superpixels
• Post-processing - Refine superpixel segmentation by color
• Material sorting - Filter by color characteristics

A typical pipeline for color-based filtering looks as follows:

from telekinesis import cornea
from datatypes import datatypes, io

# 1. Load the image
image = io.load_image(filepath=...)

# 2. Generate superpixels
superpixel_result = cornea.segment_image_using_felzenszwalb(image=image, ...)

# 3. Extract labels
superpixel_labels = superpixel_result["annotation"].to_dict()['labeled_mask']
superpixel_labels = datatypes.Image(superpixel_labels)

# 4. Filter by color (keep darker regions)
result = cornea.filter_segments_by_color(
    image=image,
    labels=superpixel_labels,
    min_color=0,
    max_color=125.0,
)

# 5. Extract filtered mask
annotation = result["annotation"].to_dict()
mask = annotation['labeled_mask']

Related skills to build such a pipeline:

• segment_image_using_slic_superpixel: Generate superpixels
• filter_segments_by_area: Filter by area instead of color
• filter_segments_by_mask: Filter using a spatial mask

Alternative Skills

Skill	vs. Filter Segments By Color
filter_segments_by_area	Filter by area instead of color. Use area for size-based filtering, color for color-based filtering.
filter_segments_by_mask	Filter using a mask. Use mask for spatial filtering, color for color-based filtering.

When Not to Use the Skill

Do not use Filter Segments By Color when:

• You need size-based filtering (Use filter_segments_by_area instead)
• You need spatial filtering (Use filter_segments_by_mask instead)
• Color is not distinguishing (Use other filtering methods)

TIP

Filter Segments By Color is particularly effective for color-based object detection and material sorting applications.