Filter Image Using Median Blur

SUMMARY

Filter Image Using Median Blur Filter applies median blur to reduce salt-and-pepper noise.

Median blur replaces each pixel with the median of its neighborhood, effectively removing impulse noise while preserving edges. This non-linear filter is particularly effective at removing isolated noise pixels (salt-and-pepper noise) without significantly blurring edges, making it ideal for cleaning up noisy images before further processing.

Use this Skill when you want to remove salt-and-pepper noise while preserving edges.

The Skill

from telekinesis import pupil

filtered_image = pupil.filter_image_using_median_blur(
    image=image,
    kernel_size=5,
)

API Reference

Example

Input Image

Original image with salt-and-pepper noise

Filtered Image

Filtered image with kernel_size=5 - noise removed, edges preserved

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

# Apply median blur for salt-and-pepper noise reduction
filtered_image = pupil.filter_image_using_median_blur(
    image=image,
    kernel_size=11,
)

# Access results
filtered_image_np = filtered_image.to_numpy()
logger.success("Applied Median Blur filter. Filtered 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 input image may be either grayscale or color; the median blur supports both formats.

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

# Load image
filepath = str(DATA_DIR / "images" / "flat_mechanical_component.webp")
image = io.load_image(filepath=filepath)

The main operation uses the filter_image_using_median_blur Skill from the pupil module. This Skill applies median blur to replace each pixel with the median of its neighborhood, effectively removing salt-and-pepper noise while preserving edges. The parameters can be tuned to control noise removal strength depending on the characteristics of the input image.

filtered_image = pupil.filter_image_using_median_blur(
    image=image,
    kernel_size=11,
)

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 impulse noise removal, image restoration, preprocessing for segmentation, and scanner artifact removal, where removing salt-and-pepper noise while preserving edges 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_median_blur

How to Tune the Parameters

The filter_image_using_median_blur Skill has 1 parameter:

kernel_size (default: 3): Controls the size of the median filter kernel. Must be odd.

• Units: Pixels
• Increase to remove larger noise spots but may blur fine details
• Decrease for faster processing and preserving more detail
• Typical range: 3–15 (min: 3, max: 15)
• Use 3–5 for small noise, 5–9 for moderate noise, 9–15 for heavy noise

TIP

Best practice: Start with kernel_size=3 for small noise and increase only if noise remains. Larger kernels significantly increase processing time as the algorithm must sort more pixels. Use 3–5 for small noise, 5–9 for moderate, 9–15 for heavy noise.

Where to Use the Skill in a Pipeline

Filter Using Median Blur is commonly used in the following pipelines:

• Impulse noise removal - Clean up salt-and-pepper noise from sensors or transmission errors
• Image restoration - Remove isolated artifacts while preserving structure
• Preprocessing for segmentation - Clean images before thresholding or clustering
• Scanner artifact removal - Remove scanning artifacts from digitized images
• Preprocessing for OCR - Clean document images before text recognition

Related skills to build such a pipeline:

• filter_image_using_morphological_open: Further clean binary images
• filter_image_using_morphological_close: Fill small gaps in binary images

Alternative Skills

Skill	vs. Filter Using Median Blur
filter_image_using_bilateral	Bilateral filter preserves edges for Gaussian noise. Use median for impulse noise, bilateral for Gaussian noise.
filter_image_using_gaussian_blur	Gaussian blur is faster but doesn't preserve edges as well. Use median for impulse noise, Gaussian for general smoothing.
filter_image_using_morphological_open	Morphological opening can also remove small noise spots. Use median for grayscale, opening for binary images.

When Not to Use the Skill

Do not use Filter Using Median Blur when:

• You have Gaussian noise instead of impulse noise (Use Gaussian or bilateral filter instead)
• You need very fast processing (Median blur is slower than linear filters like Gaussian)
• You're working with very large images and need real-time processing (Consider downsampling first or using faster filters)
• You need to preserve fine texture details (Median blur can remove small-scale texture)