Filter Image Using Morphological Dilation

SUMMARY

Filter Image Using Morphological Dilation applies dilation to expand bright regions and fill holes.

Dilation adds pixels to object boundaries, useful for filling gaps and expanding objects. This morphological operation enlarges bright regions by replacing each pixel with the maximum value in its neighborhood. It's commonly used to join broken parts of objects, fill small holes, and enhance connectivity between regions.

Use this Skill when you want to expand objects and fill small gaps or holes.

The Skill

from telekinesis import pupil

filtered_image = pupil.filter_image_using_morphological_dilate(
    image=image,
    kernel_size=5,
    kernel_shape="ellipse",
    iterations=1,
    border_type="default",
)

API Reference

Example

Input Image

Original image with gaps and thin objects

Output Image

Dilated image with kernel_size=5 - gaps filled, objects expanded

The Code

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

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

# Load the binary image
filepath = str(DATA_DIR / "images" / "spanners_arranged.jpg")
image = io.load_image(filepath=filepath, as_binary=True, binary_method='fixed')

# Apply dilation
filtered_image = pupil.filter_image_using_morphological_dilate(
    image=image,
    kernel_size=5,
    kernel_shape="ellipse",
    iterations=5,
    border_type="default",
)
logger.success(f"Applied dilation with dilated image shape as {filtered_image.to_numpy().shape}")

The Explanation of the Code

The morphological dilation implementation follows a standard image processing workflow with proper parameter configuration.

First, import the required modules:

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

These imports provide access to the Pupil SDK, type-safe datatypes for both I/O and parameters, path handling utilities, and logging functionality.

Next, prepare your image data:

DATA_DIR = pathlib.Path("path/to/telekinesis-data")
filepath = str(DATA_DIR / "images" / "spanners_arranged.jpg")
image = io.load_image(filepath=filepath, as_binary=True, binary_method='fixed')

The image is loaded from the data directory using the io module. For morphological operations, the image is loaded as a binary image using the as_binary=True parameter, which creates a binary mask suitable for morphological processing.

Next, the parameters controlling the dilation operation are configured. Dilation expands bright regions by replacing each pixel with the maximum value in its neighborhood defined by the structuring element.

kernel_size determines the size of the structuring element used for dilation. Larger kernels expand objects more aggressively and fill larger gaps, while smaller kernels produce more subtle expansion and preserve finer details.

kernel_shape defines the geometric shape of the structuring element. Common shapes include "ellipse" for smooth, isotropic dilation, "rectangle" for axis-aligned operations, and "cross" for directional effects. The shape affects how objects expand and how gaps are filled.

iterations controls how many times the dilation operation is applied sequentially. Each iteration further expands objects, so more iterations result in more aggressive expansion. Multiple iterations can be used to fill progressively larger gaps or connect distant objects.

border_type specifies how pixels near image boundaries are handled during dilation, where the structuring element extends beyond the image edges. This affects how objects near borders are processed.

Finally, the dilation operation is applied using the filter_image_using_morphological_dilate Skill.

filtered_image = pupil.filter_image_using_morphological_dilate(
    image=image,
    kernel_size=5,
    kernel_shape="ellipse",
    iterations=5,
    border_type="default",
)
logger.success(f"Applied dilation with dilated image shape as {filtered_image.to_numpy().shape}")

Dilation expands bright regions by replacing each pixel with the maximum value in its neighborhood defined by the structuring element. This operation fills small holes and gaps, connects nearby objects, and enlarges object boundaries, making it useful for joining broken parts of objects and enhancing connectivity in segmentation pipelines.

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 filter_image_using_morphological_dilate

How to Tune the Parameters

The filter_image_using_morphological_dilate Skill has 4 parameters:

kernel_size (default: 5):

• The size of the structuring element
• Increase to expand objects more and fill larger gaps
• Typical range: 3-15

kernel_shape (default: "ellipse"):

• The shape of the structuring element
• Options: "ellipse", "rectangle", "cross"

iterations (default: 1):

• The number of times dilation is applied
• Typical range: 1-10

border_type (default: "default"):

• The border handling mode
• Options: "default", "constant", "replicate", "reflect", "wrap"

TIP

Best practice: Use dilation after erosion to restore object size while keeping noise removed. Match kernel_size and iterations with the preceding erosion operation.

Where to Use the Skill in a Pipeline

Morphological Dilation is commonly used in the following pipelines:

• Gap filling - Connect broken line segments or object parts
• Mask expansion - Expand regions of interest
• Feature enhancement - Make thin features more visible
• Object connection - Join nearby objects
• Hole filling - Fill small holes in objects

A typical pipeline for object restoration looks as follows:

# Example pipeline using dilation (parameters omitted).

from telekinesis import pupil
from datatypes import io

# 1. Load surface image
image = io.load_image(filepath=...)

# 2. Erode to remove noise
eroded = pupil.filter_image_using_erode(image=image, ...)

# 3. Dilate to restore object size
restored = pupil.filter_image_using_dilate(image=eroded, ...)

Related skills to build such a pipeline:

• filter_image_usingmorphological_erode: Shrink objects
• filter_image_usingmorphological_close: Combined dilation-erosion
• filter_image_usingmorphological_open: Remove noise while preserving size

Alternative Skills

Skill	vs. Morphological Dilation
filter_image_using_morphological_close	Closing is dilation followed by erosion. Use closing to fill holes while maintaining object size, dilation when you want to expand objects.

When Not to Use the Skill

Do not use Morphological Dilation when:

• You want to remove noise (Use erosion or opening instead)
• You need to preserve object boundaries (Dilation will expand them)
• You're working with already touching objects (Dilation will merge them)
• You need to maintain object sizes (Use closing instead)

WARNING

Dilation expands objects and can cause separate objects to merge if they're close together. Use carefully when object separation is important.