Filter Image Using Morphological Thinning Filter

SUMMARY

Filter Image Using Morphological Thinning Filter applies skeletonization (thinning) to binary images.

Thinning reduces binary objects to their skeletons, useful for shape analysis and feature extraction. This operation iteratively removes pixels from object boundaries while preserving connectivity and topology, reducing objects to single-pixel-wide representations. It's particularly valuable for analyzing shapes, measuring lengths, and detecting branch points in binary structures.

Use this Skill when you want to reduce binary objects to their skeletal structure while preserving topology.

The Skill

from telekinesis import pupil

skeleton = pupil.transform_mask_using_blob_thinning(
    image=image,
    thinning_type=datatypes.String("thinning_zhangsuen"),
)

API Reference

Example

Input Image 1

Original binary image with handwriting

Input Mask

Thinned skeleton image - objects reduced to single-pixel width

Input Image 2

Original binary image with thick human shapes

Output

Thinned skeleton image - objects reduced to single-pixel width

The Code

from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

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

# Load image
filepath = str(DATA_DIR / "images" / "handwriting_mask.webp")
image = io.load_image(filepath=filepath, as_binary=True)
logger.success(f"Loaded image from {filepath}")

# Apply Zhang-Suen thinning algorithm for skeletonization
filtered_image = pupil.transform_mask_using_blob_thinning(
    image=image,
    thinning_type="thinning guohall",
)

# Access results
filtered_image_np = filtered_image.to_numpy()
logger.success("Applied Zhang-Suen thinning. Transformed output image shape: {}", filtered_image_np.shape)

The Explanation of the Code

The code begins by importing the necessary modules: pupil for image processing operations, io for data handling, pathlib for path management, and loguru for logging.

from telekinesis import pupil
from datatypes import io
import pathlib
from loguru import logger

Next, a binary mask is loaded from a .png file using the io.load_image function. The image is loaded as binary using as_binary=True, which is required for the thinning operation.

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

# Load the binary mask
filepath = str(DATA_DIR / "images" / "handwriting_mask.webp")
image = io.load_image(filepath=filepath, as_binary=True)

The main operation uses the transform_mask_using_blob_thinning Skill from the pupil module. This Skill applies skeletonization (thinning) to reduce binary objects to their skeletal structure while preserving connectivity and topology. The parameters can be tuned to control the thinning algorithm depending on the characteristics of the input mask.

filtered_image = pupil.transform_mask_using_blob_thinning(
    image=image,
    thinning_type="thinning guohall",
)

Finally, the skeleton is converted to a NumPy array using to_numpy() for further processing, visualization, or downstream tasks.

filtered_image_np = filtered_image.to_numpy()
logger.success(f"Output image shape: {filtered_image_np.shape}")

This operation is particularly useful in robotics and vision pipelines for shape analysis, feature extraction, branch point detection, and length measurement, where reducing binary objects to skeletal structure is required.

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/pupil_examples.py --example morphology_using_thinning

How to Tune the Parameters

The transform_mask_using_blob_thinning Skill has 1 parameter:

thinning_type (no default—required):

• The thinning algorithm to use
• Options: "thinning_zhangsuen", "thinning_guohall"
• "thinning_zhangsuen" is a commonly used algorithm with good performance; "thinning_guohall" may produce slightly different skeletons
• Use "thinning_zhangsuen" for most cases; "thinning_guohall" as an alternative

TIP

Best practice: Ensure your input image is properly thresholded to binary before applying thinning. The quality of the skeleton depends on the quality of the binary input.

Where to Use the Skill in a Pipeline

Morphological Thinning is commonly used in the following pipelines:

• Shape analysis - Reduce shapes to skeletons for analysis
• Length measurement - Measure path lengths along skeletons
• Branch point detection - Find branching points in structures
• Pattern recognition - Extract skeletal features for recognition
• Neuronal analysis - Analyze neurite structure

Related skills to build such a pipeline:

• filter_image_using_frangi: Detect vessels/neurites
• filter_image_usingmorphological_erode: Alternative thinning approach
• filter_image_usingmorphological_open: Clean binary images before thinning

Alternative Skills

Skill	vs. Morphological Thinning
filter_image_using_morphological_erode	Erosion shrinks objects but doesn't create skeletons. Use thinning for topology-preserving skeletonization, erosion for simple shrinking.

When Not to Use the Skill

Do not use Morphological Thinning when:

• You're working with grayscale images (Convert to binary first)
• You need to preserve object thickness (Thinning reduces everything to single pixels)
• Objects have holes that need preserving (Thinning may alter topology in some cases)
• You need very fast processing (Thinning is iterative and can be slow)