Segment Image Using Felzenszwalb

SUMMARY

Segment Image Using Felzenszwalb segments an image into superpixels using Felzenszwalb's graph-based method.

The algorithm builds a graph over the image's pixels, with edges weighted by color/intensity difference, then greedily merges regions whose internal variation is small relative to the difference between them. This produces irregularly-shaped superpixels that tend to follow object boundaries, rather than the uniform grid-like superpixels produced by segment_image_using_slic_superpixel.

Use this Skill when you want to create superpixels that adapt to image content and follow object boundaries.

The Skill

from telekinesis import cornea

segmented_image = cornea.segment_image_using_felzenszwalb(
    image=image,
    scale=500,
    sigma=1,
    min_size=200,
)

API Reference

Full parameter and return type documentation for segment_image_using_felzenszwalb.

View Reference →

Example

Input Image

Original image for Felzenszwalb segmentation

Output Image

Superpixel segmentation using the Felzenszwalb algorithm

The Code

"""
Demonstrates Felzenszwalb segmentation.
"""

from loguru import logger
import rerun as rr

from telekinesis import cornea, datatypes

def segment_image_using_felzenszwalb_example():
    """Segments an image using the Felzenszwalb algorithm."""
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/eggs_carton.jpg"
    image = datatypes.Image.from_url(url=image_url)

    # ===================== Run Skill ==========================================
    segmented_image = cornea.segment_image_using_felzenszwalb(
        image=image, scale=500, sigma=1, min_size=200
    )

    # ===================== Log ================================================
    logger.success(f"Segmented {image} using the Felzenszwalb algorithm.")
    logger.success(f"Results: {segmented_image}")
    logger.info(f"Segmented image label codes: {segmented_image.label_codes}")
    logger.info(f"Segmented image number of labels: {segmented_image.number_of_labels}")
    logger.info(f"Segmented image shape: {segmented_image.shape}")
    logger.info(f"Segmented image dtype: {segmented_image.dtype}")

    # ===================== Visualization  (Optional) ======================
    rr.init("segment_image_using_felzenszwalb_example", spawn=True)
    datatypes.visualize(image, entity_path="/input_image")
    datatypes.visualize(segmented_image, entity_path="/segmented_image")


if __name__ == "__main__":
    segment_image_using_felzenszwalb_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/segmentation/segment_image_using_felzenszwalb.py

Parameter Configuration

Key	Type	Default	Description
image	datatypes.Image | np.ndarray	required	Input image to segment, shape (H, W, 3)
scale	datatypes.Int | int	100	Sets the scale of observation. Higher values favor larger segments (a higher bar for merging regions); lower values produce more, smaller segments. Dimensionless — tune relative to your image
sigma	datatypes.Float | float	0.5	Standard deviation of the Gaussian smoothing applied before segmentation. 0 disables smoothing entirely
min_size	datatypes.Int | int	50	Minimum segment size, in pixels, enforced as a post-processing step. Segments smaller than this are merged into a neighbor

Returns

Type	Description
datatypes.SegmentationImage	A per-pixel label map, shape (H, W), where each pixel's value identifies which superpixel it belongs to. Use .data for the raw label array, .label_codes for the sorted array of unique superpixel ids, .number_of_labels for how many superpixels were found, and .shape/.dtype for its size and label dtype.

Raises

Exception	Condition
TypeError	A parameter's value does not match its expected type (see the Parameter Configuration table above)
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 Cornea service timed out
TransportError	A network failure occurred before a response was received
ClientError	The Cornea 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 Cornea service returned a 5xx or otherwise unexpected error response

How to Tune the Parameters

The segment_image_using_felzenszwalb Skill exposes three parameters that together control how many superpixels are produced and how closely they follow object boundaries.

scale

• Controls: The bar for merging two regions during the graph-based clustering — effectively the scale of observation.
• Default: 100
• Increase → favors larger segments (fewer, coarser superpixels)
• Decrease → produces more, smaller segments
• Typical range: 50–500

sigma

• Controls: The standard deviation of the Gaussian smoothing applied to the image before segmentation.
• Default: 0.5
• Increase → smooths out more noise/fine texture before segmenting, yielding fewer, coarser segments
• Decrease → (or 0) disables smoothing, keeping the algorithm sensitive to fine detail
• Typical range: 0.1–2.0

min_size

• Controls: The minimum segment size, in pixels, enforced as a post-processing step after the graph merge.
• Default: 50
• Increase → merges more small fragments into a neighboring segment, eliminating noise
• Decrease → preserves small segments
• Typical range: 20–200

TIP

Recommended tuning order: Start with the defaults and adjust scale first to land on roughly the right number of superpixels. Use sigma to control sensitivity to noise/texture, then raise min_size if small, spurious fragments remain.

Where to Use the Skill

Common pipelines include:

• Superpixel generation – Over-segmenting an image into boundary-following regions as a first step before further processing
• Object proposal generation – Producing irregular candidate regions that respect natural object boundaries
• Preprocessing for filtering – Pairing with filter_segments_by_area, filter_segments_by_color, or filter_segments_by_mask to keep only the superpixels relevant to a downstream task
• Image simplification – Reducing an image to a small number of content-adaptive regions before analysis

Alternative Skills

Skill	vs. Segment Image Using Felzenszwalb
segment_image_using_slic_superpixel	Produces uniform, grid-like superpixels instead of irregular, boundary-following ones. Use SLIC when you want a predictable superpixel count/size; use Felzenszwalb when you want superpixels that adapt to image content.
filter_segments_by_area	Not an alternative — a natural next step. Drops superpixels whose pixel area falls outside a chosen range.
filter_segments_by_color	Not an alternative — a natural next step. Drops superpixels whose mean intensity falls outside a chosen range.
filter_segments_by_mask	Not an alternative — a natural next step. Keeps only the superpixels that overlap a region-of-interest mask.

When Not to Use the Skill

Do not use Segment Image Using Felzenszwalb when:

• You need a predictable, uniform superpixel count or size — the number and shape of segments depend on scale and local image content, not a direct count you set. Use segment_image_using_slic_superpixel instead.
• You need regular, grid-like superpixel shapes — Felzenszwalb superpixels are irregular by design, following object boundaries rather than a spatial grid.

TIP

Because superpixel count and shape both come from scale, sigma, and image content rather than a direct target, treat the output as over-segmentation to refine — pair it with filter_segments_by_area, filter_segments_by_color, or filter_segments_by_mask to keep only the superpixels relevant to your task.