Telekinesis Agentic Skill Library

Appearance

Segment Image Using Local Threshold ​

SUMMARY

Segment Image Using Local Threshold performs local threshold segmentation.

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

Use this Skill when you want to segment images with non-uniform lighting or varying background intensity.

The Skill ​

python
from telekinesis import cornea

result = cornea.segment_image_using_local_threshold(
    image=image,
    block_size=23,
)

API Reference

Example ​

Input Image

Input image

Original image for local threshold segmentation

Output Image

Output image

Segmented image using local thresholding

The Code ​

python
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 local threshold segmentation
result = cornea.segment_image_using_local_threshold(
    image=image,
    block_size=23,
)

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

The Explanation of the Code ​

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

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

python
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 local threshold parameters are configured:

  • block_size determines the size of the local neighborhood used to compute the threshold for each pixel
python
result = cornea.segment_image_using_local_threshold(
    image=image,
    block_size=23,
)

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

python
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:

bash
cd telekinesis-examples
python examples/cornea_examples.py --example segment_image_using_local_threshold

How to Tune the Parameters ​

The segment_image_using_local_threshold Skill has 1 parameter:

block_size (default: 35):

  • Block size for local threshold computation
  • Units: Pixels (odd integer)
  • Increase for larger neighborhoods (smoother threshold surface)
  • Decrease for smaller neighborhoods (more adaptive to local changes)
  • Typical range: 11-101
  • Should be larger than the largest object of interest

TIP

Best practice: Set block_size to be larger than the largest object you want to segment. Too small blocks may cause noise, too large blocks may miss local variations.

Where to Use the Skill in a Pipeline ​

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

  • Non-uniform lighting - When lighting varies across the image
  • Varying background - When background intensity changes
  • Document scanning - Text extraction with shadows
  • Industrial inspection - Objects under varying illumination

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

python
from telekinesis import cornea
from datatypes import io

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

# 2. Apply local threshold (handles non-uniform lighting)
result = cornea.segment_image_using_local_threshold(image=image, block_size=23)

# 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_adaptive_threshold: Alternative adaptive method

Alternative Skills ​

Skillvs. Segment Image Using Local Threshold
segment_image_using_adaptive_thresholdAdaptive threshold is more sophisticated. Use adaptive for better results, local for simpler implementation.
segment_image_using_otsu_thresholdOtsu is global. Use Otsu for uniform lighting, local for non-uniform lighting.

When Not to Use the Skill ​

Do not use Segment Image Using Local Threshold when:

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

TIP

Local threshold is particularly effective for images with shadows, gradients, or other non-uniform lighting conditions that would cause global thresholding to fail.