Filter Image Using Blur

SUMMARY

Filter Image Using Blur applies a simple box blur filter to an image.

Box blur is a basic smoothing operation that averages pixel values within a kernel. It's fast and straightforward but can blur edges. This filter is commonly used when processing speed is more important than preserving fine details, such as in quick preprocessing steps, background estimation, or creating artistic blur effects.

Use this Skill when you want to quickly smooth an image when edge preservation is not critical.

The Skill

from telekinesis import pupil

blurred_image = pupil.filter_image_using_blur(
    image=image,
    kernel_size=15,
    border_type="default",
)

API Reference

Example

Input Image

Original sharp image

Filtered Image

Blurred image with kernel_size=15 - smoothed uniformly across the image

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

# Apply simple average blur
filtered_image = pupil.filter_image_using_blur(
    image=image,
    kernel_size=7,
    border_type="default",
)

# Access results
filtered_image_np = filtered_image.to_numpy()
logger.success("Applied 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 .jpg file using the io.load_image function. The input image may be either grayscale or color; the box blur supports both formats.

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

# Load image
filepath = str(DATA_DIR / "images" / "nuts_scattered_noised.jpg")
image = io.load_image(filepath=filepath)

The main operation uses the filter_image_using_blur Skill from the pupil module. This Skill applies a simple box blur that averages pixel values within a kernel for fast smoothing. The parameters can be tuned to control blur intensity and border handling depending on the characteristics of the input image.

filtered_image = pupil.filter_image_using_blur(
    image=image,
    kernel_size=7,
    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 fast preprocessing, background estimation, noise reduction, and downsampling preparation, where quick uniform smoothing 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_blur

How to Tune the Parameters

The filter_image_using_blur Skill has 2 parameters that control the blur intensity:

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

• Units: Pixels
• Increase to create more blur, making the image softer
• Decrease for faster processing and less blur
• Typical range: 3–31 (min: 3, max: 31)
• Use 3–7 for light blur, 7–15 for moderate blur, 15–31 for heavy blur

TIP

Best practice: Start with kernel_size=3 for light blur and increase for stronger smoothing. Remember that larger kernels are slower but create smoother results. Use 3–7 for light blur, 7–15 for moderate, 15–31 for heavy blur.

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

• Options: "default", "constant", "replicate", "reflect", "reflect 101"
• "default" uses the library's default behavior
• Use "default" or "reflect" for most cases

Where to Use the Skill in a Pipeline

Filter Using Blur is commonly used in the following pipelines:

• Fast preprocessing - Quick smoothing before other operations
• Background estimation - Blur to remove fine details and estimate background
• Artistic effects - Create intentional blur for visual effects
• Downsampling preparation - Smooth before reducing image resolution
• Motion blur simulation - Approximate motion effects

Related skills to build such a pipeline:

• filter_image_using_gaussian_blur: More sophisticated smoothing with better quality

Alternative Skills

Skill	vs. Filter Using Blur
filter_image_using_gaussian_blur	Gaussian blur produces smoother, more natural results than box blur. Use gaussian when quality matters, box blur when speed is critical.
filter_image_using_bilateral	Bilateral filter preserves edges while smoothing. Use bilateral when edges are important, box blur when uniform smoothing is acceptable.
filter_image_using_median_blur	Median blur is better for removing salt-and-pepper noise. Use median for impulse noise, box blur for general smoothing.

When Not to Use the Skill

Do not use Filter Using Blur when:

• You need to preserve edges (Use bilateral filter or Gaussian blur instead)
• You're removing salt-and-pepper noise (Use median blur which is specifically designed for this)
• You need smooth, natural-looking blur (Use Gaussian blur for better visual quality)
• You're preparing for edge detection (Don't blur, or use minimal Gaussian smoothing)