Filter Image Using Morphological Blackhat

SUMMARY

Filter Image Using Morphological Blackhat applies black-hat transform to extract small dark features.

Black-hat finds dark features smaller than the structuring element, useful for detecting small holes or dark details. This operation subtracts the original image from the morphologically closed image, isolating features that were filled by closing. It's the complement of top-hat and is particularly effective for extracting small dark objects or details on varying bright backgrounds.

Use this Skill when you want to extract or enhance small dark features and holes.

The Skill

from telekinesis import pupil

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

API Reference

Example

Input Image

Original image with small dark features

Output Image

Black-hat result emphasizing fine dark details on metallic surfaces.

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 grayscale image
filepath = str(DATA_DIR / "images" / "mechanical_parts_gray.png")
image = io.load_image(filepath=filepath, as_gray=True)

# Apply black-hat
filtered_image = pupil.filter_image_using_morphological_blackhat(
    image=image,
    kernel_size=15,
    kernel_shape="ellipse",
    iterations=2,
    border_type="default",
)
logger.success(f"Applied blackhat with blackhat image shape as {filtered_image.to_numpy().shape}")

The Explanation of the Code

The morphological black-hat 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" / "mechanical_parts_gray.png")
image = io.load_image(filepath=filepath, as_gray=True)

The image is loaded from the data directory using the io module. For morphological operations, the image is loaded as a grayscale image using the as_gray=True parameter, which prepares the image for black-hat transformation that isolates small dark features.

Next, the parameters controlling the black-hat operation are configured. Black-hat subtracts the original image from the morphologically closed image, isolating dark features smaller than the structuring element.

kernel_size determines the size of the structuring element used for black-hat computation. Larger kernels isolate larger dark features like cracks or holes, while smaller kernels detect finer defects. The kernel size should match the scale of the features you want to extract.

kernel_shape defines the geometric shape of the structuring element. Common shapes include "ellipse" for smooth, isotropic black-hat computation, "rectangle" for axis-aligned operations, and "cross" for directional effects. The shape affects how dark features are isolated and extracted.

iterations controls how many times the closing operation (used in black-hat) is applied sequentially. Each iteration fills progressively larger holes, affecting which dark features are isolated by the black-hat operation.

border_type specifies how pixels near image boundaries are handled during black-hat computation, where the structuring element extends beyond the image edges. This affects how features near borders are extracted.

Finally, the black-hat operation is applied using the filter_image_using_morphological_blackhat Skill.

filtered_image = pupil.filter_image_using_morphological_blackhat(
    image=image,
    kernel_size=15,
    kernel_shape="ellipse",
    iterations=2,
    border_type="default",
)
logger.success(f"Applied blackhat with blackhat image shape as {filtered_image.to_numpy().shape}")

Black-hat subtracts the original image from the morphologically closed image, isolating dark features smaller than the structuring element. This operation is the complement of top-hat and is particularly effective for crack detection, hole detection, and extracting small dark defects on bright surfaces, making it useful for quality inspection and surface defect detection in industrial vision applications.

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_blackhat

How to Tune the Parameters

The filter_image_using_morphological_blackhat Skill has 4 parameters that mirror top-hat. The key is kernel_size which determines what features are extracted - dark features smaller than the kernel will appear in the output.

TIP

Best practice: Black-hat is the complement of top-hat. Use it for detecting dark holes, cracks, or features on bright backgrounds. Set kernel_size based on the size of features you want to extract.

Where to Use the Skill in a Pipeline

Morphological Blackhat is commonly used in the following pipelines:

• Crack detection - Detect fine cracks in bright surfaces
• Hole detection - Find small holes or pores
• Dark feature enhancement - Enhance dark details obscured by bright backgrounds
• Defect detection - Find dark defects on bright surfaces
• Shadow extraction - Extract small shadow regions

A typical pipeline for crack detection looks as follows:

# Example pipeline using blackhat (parameters omitted).

from telekinesis import pupil
from datatypes import io

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

# 2. Apply black-hat to extract cracks
cracks = pupil.filter_image_using_morphological_blackhat(image=image, kernel_size=15, ...)

# 3. Threshold to binary
binary_cracks = ...

# 4. Analyze cracks
analysis = ...

Related skills to build such a pipeline:

• load_image: Load images
• filter_image_using_morphological_tophat: Extract bright features
• filter_image_using_gaussian_blur: Pre-smooth
• filter_image_using_morphological_close: Related operation

Alternative Skills

Skill	vs. Morphological Blackhat
filter_image_using_morphological_tophat	Tophat extracts bright features. Use blackhat for dark features, tophat for bright features.

When Not to Use the Skill

Do not use Morphological Blackhat when:

• You want to extract bright features (Use tophat instead)
• Features are larger than background variations (Black-hat won't help)
• Working with uniform backgrounds (Unnecessary)
• You need to preserve background information (Black-hat removes it)