Segment Image Using Adaptive Threshold

SUMMARY

Segment Image Using Adaptive Threshold performs adaptive threshold segmentation.

Adaptive threshold computes a threshold value for each pixel based on a local neighborhood, making it effective for images with non-uniform lighting, shadows, or varying background intensity. This method adapts to local image characteristics.

Use this Skill when you want to segment images with non-uniform lighting using adaptive thresholding.

The Skill

from telekinesis import cornea

result = cornea.segment_image_using_adaptive_threshold(
    image=image,
    max_value=255,
    adaptive_method="gaussian constant",
    threshold_type='binary',
    block_size=61,
    offset_constant=5,
)

API Reference

Example

Input Image

Original image with non-uniform lighting

Output Image

Segmented image using adaptive threshold - handles non-uniform lighting

The Code

import pathlib

from telekinesis import cornea
from datatypes import io

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

# Load image as grayscale
filepath = str(DATA_DIR / "images" / "car_number_plate.png")
image = io.load_image(filepath=filepath, as_gray=True)

# Perform adaptive threshold segmentation
result = cornea.segment_image_using_adaptive_threshold(
    image=image,
    max_value=255,
    adaptive_method="gaussian constant",
    threshold_type='binary',
    block_size=61,
    offset_constant=5,
)

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

The Explanation of the Code

Adaptive threshold computes a threshold for each pixel based on statistics of its local neighborhood, allowing it to handle non-uniform lighting and varying backgrounds effectively.

The code begins by importing the required modules and loading a grayscale image:

import pathlib

from telekinesis import cornea
from datatypes import io

DATA_DIR = pathlib.Path("path/to/telekinesis-data")
filepath = str(DATA_DIR / "images" / "car_number_plate.png")
image = io.load_image(filepath=filepath, as_gray=True)

The adaptive threshold parameters are configured:

• max_value is the value assigned to pixels that exceed the threshold
• adaptive_method specifies how the local threshold is computed (e.g., "gaussian constant")
• threshold_type specifies the type of thresholding
• block_size determines the size of the local neighborhood
• offset_constant is subtracted from the mean to compute the threshold

result = cornea.segment_image_using_adaptive_threshold(
    image=image,
    max_value=255,
    adaptive_method="gaussian constant",
    threshold_type='binary',
    block_size=61,
    offset_constant=5,
)

The function returns a dictionary containing an annotation object in COCO panoptic format. 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 segment_image_using_adaptive_threshold

How to Tune the Parameters

The segment_image_using_adaptive_threshold Skill has 5 parameters:

max_value (default: 255):

• Maximum value for threshold
• Units: Pixel intensity (0-255)
• Value assigned to pixels exceeding threshold
• Typical: 255

adaptive_method (default: "gaussian constant"):

• Adaptive method for threshold computation
• Options: "gaussian constant", "mean constant"
• "gaussian constant" uses Gaussian-weighted mean
• "mean constant" uses simple mean

threshold_type (default: 'binary'):

• Type of threshold
• Options: 'binary', 'binary_inv'
• 'binary' sets pixels above threshold to max_value
• Use 'binary' for most applications

block_size (default: 11):

• Block size for adaptive threshold
• Units: Pixels (odd integer)
• Increase for larger neighborhoods (smoother threshold)
• Decrease for smaller neighborhoods (more adaptive)
• Typical range: 3-31
• Should be larger than objects of interest

offset_constant (default: 2):

• Offset constant subtracted from mean
• Units: Pixel intensity
• Increase to require higher intensity (more selective)
• Decrease to include lower intensity (more inclusive)
• Typical range: 0-10

TIP

Best practice: Set block_size larger than the largest object. Adjust offset_constant based on contrast - higher for high contrast, lower for low contrast.

Where to Use the Skill in a Pipeline

Segment Image Using Adaptive Threshold is commonly used in the following pipelines:

• Non-uniform lighting - When lighting varies across the image
• Document scanning - Text extraction with shadows
• Industrial inspection - Objects under varying illumination
• Outdoor robotics - Segmentation under natural lighting

A typical pipeline for non-uniform lighting looks as follows:

from telekinesis import cornea
from datatypes import io

# 1. Load the image (as grayscale)
image = io.load_image(filepath=..., as_gray=True)

# 2. Apply adaptive threshold (handles non-uniform lighting)
result = cornea.segment_image_using_adaptive_threshold(
    image=image,
    block_size=61,
    offset_constant=5,
)

# 3. Process segmented regions
annotation = result["annotation"].to_dict()
mask = annotation['labeled_mask']

Related skills to build such a pipeline:

• load_image: Load images from disk
• segment_image_using_local_threshold: Alternative local method

Alternative Skills

Skill	vs. Segment Image Using Adaptive Threshold
segment_image_using_local_threshold	Local threshold is simpler. Use adaptive for better results, local for simpler implementation.
segment_image_using_otsu_threshold	Otsu is global. Use Otsu for uniform lighting, adaptive for non-uniform lighting.

When Not to Use the Skill

Do not use Segment Image Using Adaptive Threshold when:

• Lighting is uniform (Use Otsu or manual threshold for speed)
• Speed is critical (Adaptive threshold is slower than global methods)
• Objects are very small (Block size may be too large)

TIP

Adaptive threshold is the go-to method for images with shadows, gradients, or other non-uniform lighting conditions that would cause global thresholding to fail.