Segment Image Using Threshold

SUMMARY

Segment Image Using Threshold performs basic threshold segmentation.

Basic threshold segmentation creates a binary mask by comparing pixel values to threshold values. This is the simplest and fastest thresholding method, useful when you know the appropriate threshold values for your application.

Use this Skill when you want to segment images using manually specified threshold values.

The Skill

from telekinesis import cornea

result = cornea.segment_image_using_threshold(
    image=image,
    min_value=45,
    max_value=255,
    threshold_type='binary',
)

API Reference

Example

Input Image

Original image for threshold segmentation

Output Image

Binary segmented image using threshold

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" / "nuts_scattered.jpg")
image = io.load_image(filepath=filepath, as_gray=True)

# Perform basic threshold segmentation
result = cornea.segment_image_using_threshold(
    image=image,
    min_value=45,
    max_value=255,
    threshold_type='binary',
)

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

The Explanation of the Code

Basic threshold segmentation compares each pixel value to threshold bounds and creates a binary mask. Pixels within the range are set to max_value, others are set to 0.

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" / "nuts_scattered.jpg")
image = io.load_image(filepath=filepath, as_gray=True)

The threshold parameters are configured:

• min_value and max_value define the threshold range
• threshold_type specifies the type of thresholding (e.g., 'binary')

result = cornea.segment_image_using_threshold(
    image=image,
    min_value=45,
    max_value=255,
    threshold_type='binary',
)

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_threshold

How to Tune the Parameters

The segment_image_using_threshold Skill has 3 parameters:

min_value (default: 127):

• Minimum threshold value
• Units: Pixel intensity (0-255)
• Decrease to include darker pixels
• Increase to exclude darker pixels
• Typical range: 0-200

max_value (default: 255):

• Maximum threshold value
• Units: Pixel intensity (0-255)
• Increase to include brighter pixels
• Decrease to exclude brighter pixels
• Typical range: 100-255

threshold_type (default: 'binary'):

• Type of threshold
• Options: 'binary', 'binary_inv', 'trunc', 'tozero', 'tozero_inv'
• 'binary' sets pixels in range to max_value, others to 0
• Use 'binary' for most applications

TIP

Best practice: Use histogram analysis to determine appropriate threshold values. Start with min_value around the valley between foreground and background peaks.

Where to Use the Skill in a Pipeline

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

• Manual thresholding - When threshold values are known
• Fast binary segmentation - When speed is critical
• Preprocessing - Creating binary masks for further processing
• Quality control - Defect detection with known thresholds

A typical pipeline for manual thresholding 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 threshold (manual)
result = cornea.segment_image_using_threshold(
    image=image,
    min_value=45,
    max_value=255,
    threshold_type='binary',
)

# 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_otsu_threshold: Automatic threshold alternative

Alternative Skills

Skill	vs. Segment Image Using Threshold
segment_image_using_otsu_threshold	Otsu is automatic. Use Otsu when threshold is unknown, manual threshold when known.
segment_image_using_adaptive_threshold	Adaptive handles non-uniform lighting. Use adaptive for varying lighting, manual for uniform.

When Not to Use the Skill

Do not use Segment Image Using Threshold when:

• Threshold value is unknown (Use Otsu or Yen for automatic)
• Lighting is non-uniform (Use adaptive threshold instead)
• You need automatic adaptation (Use adaptive or local threshold)

TIP

Basic threshold is the fastest thresholding method and is ideal when you know the appropriate threshold values for your application.