Segment Image Using Flood Fill

SUMMARY

Segment Image Using Flood Fill grows a connected region outward from a single seed pixel by color similarity.

Starting at seed_point, it repeatedly grows the region to include any neighboring pixel whose value is within tolerance of the seed pixel's value — like a paint-bucket tool in an image editor. Use it when you know a representative point inside the region you want (e.g. a background pixel to select the whole background), rather than a color range (segment_image_using_hsv, segment_image_using_rgb) or a bounding box (segment_image_using_grab_cut).

Use this Skill when you want to segment a connected region starting from a known point inside it.

The Skill

from telekinesis import cornea

segmented_image = cornea.segment_image_using_flood_fill(
    image=image,
    seed_point=(0, 0),
    tolerance=10,
)

API Reference

Full parameter and return type documentation for segment_image_using_flood_fill.

View Reference →

Example

Input Image

Original image for flood fill segmentation

Output Image

Segmented region using flood fill from seed point

The Code

"""
Demonstrates flood fill segmentation.
"""

from loguru import logger
import rerun as rr

from telekinesis import cornea, datatypes

def segment_image_using_flood_fill_example():
    """Segments an image using flood fill from a seed point."""
    # ===================== Load Image ==========================================
    image_url = "https://assets.telekinesis.ai/examples/v1/images/erode.jpg"
    image = datatypes.Image.from_url(url=image_url)

    # ===================== Run Skill ==========================================
    segmented_image = cornea.segment_image_using_flood_fill(
        image=image, seed_point=(0, 0), tolerance=10
    )

    # ===================== Log ================================================
    logger.success(f"Segmented {image} using flood fill.")
    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_flood_fill_example", spawn=True)
    datatypes.visualize(image, entity_path="/input_image")
    datatypes.visualize(segmented_image, entity_path="/segmented_image")


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

Parameter Configuration

These parameters control where the fill starts and how far it is allowed to spread.

Key	Type	Default	Description
image	datatypes.Image | np.ndarray	required	Input image to segment, shape (H, W) or (H, W, 3)
seed_point	datatypes.Point2D | np.ndarray | list | tuple	[0, 0]	Starting pixel coordinate [x, y] for the fill. Should lie within image's bounds
tolerance	datatypes.Int | int	10	Maximum absolute difference from the seed pixel's value that a neighboring pixel may have and still be included in the region

Returns

Type	Description
datatypes.SegmentationImage	A per-pixel label map, shape (H, W), where the region reachable from seed_point and the remaining background are each assigned a distinct label. Use .data for the raw label array, .label_codes for the sorted array of unique ids present, .number_of_labels for how many distinct labels 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_flood_fill Skill exposes two parameters: where the fill starts, and how much color variation it tolerates while spreading.

seed_point

• Controls: The starting pixel [x, y] from which the region grows outward.
• Units: Pixel coordinates
• Default: [0, 0] (the top-left corner)
• Choose a point that lies inside the region you want — e.g. a background pixel near an edge to select the whole background, or a pixel near the center of an object to select the object
• No fixed typical range; it depends entirely on the image and the target region

tolerance

• Controls: How much a neighboring pixel's value may differ from the seed pixel's value and still be absorbed into the growing region.
• Units: Pixel intensity difference
• Default: 10
• Increase → grows a larger, more inclusive region that tolerates more color/intensity variation
• Decrease → keeps the region tight, including only near-identical pixels
• Typical range: 1-50

TIP

Pick seed_point interactively — for example from a user click — and raise tolerance gradually until the filled region matches the target without spilling into neighboring areas.

Where to Use the Skill

Common pipelines include:

• Background removal – seeding at a corner or edge pixel to select and remove the background
• Region filling – filling holes or gaps inside an already-segmented mask
• Interactive segmentation – letting a user click a point inside an object to select it
• Connected-component extraction – pulling out one specific connected region for further processing

Alternative Skills

Skill	vs. Segment Image Using Flood Fill
segment_image_using_hsv	HSV segments by an explicit color range. Use HSV when you know the color range of the target; use flood fill when you only know a point inside it.
segment_image_using_rgb	RGB segments by an explicit color range in RGB space. Use RGB when you know the color range of the target; use flood fill when you only know a point inside it.
segment_image_using_grab_cut	GrabCut is prompted with a bounding box and models foreground/background color distributions. Use GrabCut when you know a box around the object; use flood fill when you only know a point inside it.

When Not to Use the Skill

Do not use Segment Image Using Flood Fill when:

• You don't have a representative seed point inside the target region — use a color range (segment_image_using_hsv/segment_image_using_rgb) or a bounding box (segment_image_using_grab_cut) instead
• The target region has strong internal color/intensity variation — the fill may stop early and only capture part of the region, or, with a high tolerance, leak into neighboring regions
• You need to segment several disconnected regions in one pass — flood fill only grows the single connected region reachable from one seed

TIP

Flood fill only grows into pixels connected to the seed point through the tolerance test — an occluding edge or a thin, high-contrast line inside the region will stop the fill before it reaches the far side.