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

Filtered Image

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

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" / "mechanical_parts_gray.webp")
image = io.load_image(filepath=filepath, as_gray=True)
logger.success(f"Loaded image from {filepath}")

# Apply blackhat morphological operation
filtered_image = pupil.filter_image_using_morphological_blackhat(
    image=image,
    kernel_size=15,
    kernel_shape="ellipse",
    iterations=2,
    border_type="default",
)

# Access results
filtered_image_np = filtered_image.to_numpy()
logger.success("Applied blackhat morphological operation. 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, an image is loaded from a .png file using the io.load_image function. The image is loaded in grayscale mode using as_gray=True, which is appropriate for morphological black-hat operations that isolate small dark features.

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

# Load the grayscale image
filepath = str(DATA_DIR / "images" / "mechanical_parts_gray.webp")
image = io.load_image(filepath=filepath, as_gray=True)

The main operation uses the filter_image_using_morphological_blackhat Skill from the pupil module. This Skill applies the black-hat transform to extract small dark features by subtracting the original from the morphologically closed image. The parameters can be tuned to control feature scale, kernel shape, iteration strength, and border handling depending on the characteristics of the input image.

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

Finally, the filtered image 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 crack detection, hole detection, defect detection, and surface inspection, where extracting small dark features on bright backgrounds 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 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.

kernel_size (default: 3): Controls the size of the structuring element used for the closing step in black-hat.

• Units: Pixels
• Increase to extract larger dark features (cracks, holes); Decrease to extract finer dark details
• Typical range: 3–15 (min: 3, max: 15)
• Use 3–5 for fine defects, 5–9 for moderate cracks, 9–15 for larger holes

kernel_shape (default: ellipse): Defines the geometric shape of the structuring element used for black-hat computation.

• Options: "ellipse", "rectangle", "cross", "diamond"
• "ellipse" gives smooth, isotropic extraction of dark features; "rectangle" and "cross" for directional effects
• Use "ellipse" for most cases

iterations (default: 1): Specifies how many times the closing operation (used in black-hat) is applied sequentially.

• Units: Count
• Increase to isolate larger dark features; Decrease for smaller dark details
• Typical range: 1–10 (min: 1, max: 10)
• Each iteration compounds the effect

border_type (default: default): Determines how image borders are handled when the structuring element extends beyond the image boundary.

• Options: "default", "constant", "replicate", "reflect", "reflect 101"
• Use "default" or "reflect" for most cases

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

Related skills to build such a pipeline:

• 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)