Filter Image Using Box

SUMMARY

Filter Image Using Box applies a normalized box filter with configurable depth and normalization.

Box filter performs normalized averaging within a kernel region, useful for basic smoothing operations. This filter allows control over output bit depth and normalization, making it flexible for different preprocessing needs in computer vision pipelines. It's particularly useful when you need precise control over numerical precision in the filtering output.

Use this Skill when you want to perform basic averaging with control over output precision and normalization.

The Skill

from telekinesis import pupil

filtered_image = pupil.filter_image_using_box(
    image=image,
    kernel_size=datatypes.Int(5),
    normalize=datatypes.Bool(True),
    output_format=datatypes.String("64bit"),
    border_type=datatypes.String("default"),
)

API Reference

Example

Input Image

Original image

Output Image

Filtered image with kernel_size=5, normalize=True, output_format="8bit" - smoothed with normalized kernel

The Code

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

# Load the image
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)

# Apply box filter
filtered_image = pupil.filter_image_using_box(
    image=image,
    kernel_size=5,
    normalize=True,
    output_format="8bit",
    border_type="reflect",
)
logger.success(f"Applied box filter with filtered image shape as {filtered_image.to_numpy().shape}")

The Explanation of the Code

The box filter performs a normalized averaging operation over a fixed-size kernel, allowing explicit control over normalization behavior and output numerical precision. This makes it suitable for basic smoothing tasks where predictable behavior and control over output depth are required.

The code begins by importing the necessary modules. These imports provide access to the Pupil SDK for image processing operations and optional logging utilities for monitoring execution.

from telekinesis import pupil
from datatypes import datatypes
from loguru import logger

Next, the input image is prepared. The image is expected to be of Telekinesis Image datatype with either grayscale shape (H, W) or color shape (H, W, C). The box filter supports both formats and applies the averaging operation independently to each channel when working with color images.

# Load the image
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 filter parameters are then configured. The box filter performs normalized averaging over a square kernel, providing explicit control over normalization and output precision, making it useful when predictable behavior and memory control are important.

kernel_size defines the size of the square averaging window. Larger kernels produce stronger smoothing but increase computation time.

normalize determines whether the kernel values are normalized so that their sum equals one, which preserves the average image brightness. When disabled, the filter acts as a simple sum rather than an average.

output_format specifies the numerical precision of the output image, allowing control over memory usage and computational accuracy. Different depths (8bit, 16bit, 32bit, 64bit) affect both storage requirements and precision.

border_type controls how pixels near the image boundaries are handled when the kernel extends beyond the image edge, affecting edge behavior in the filtered output.

Finally, the box filter is applied using the filter_image_using_box Skill. The original image remains unchanged, and a new filtered image is returned.

filtered_image = pupil.filter_image_using_box(
    image=image,
    kernel_size=5,
    normalize=True,
    output_format="8bit",
    border_type="default",
)
logger.success(f"Applied box filter with filtered image shape as {filtered_image.to_numpy().shape}")

This operation applies a uniform box-averaging filter with the specified configuration. It is commonly used for controlled smoothing, preprocessing before downsampling, or numerical operations where explicit control over normalization and output precision 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_box

How to Tune the Parameters

The filter_image_using_box Skill has 4 parameters that control the averaging operation:

kernel_size (default: 5):

• The size of the box kernel. Must be odd.
• Units: Pixels
• Increase to create larger averaging area and more smoothing
• Decrease for less smoothing and faster processing
• Typical range: 3-15
• Use 3-5 for subtle smoothing, 5-9 for moderate smoothing, 9-15 for heavy smoothing

normalize (default: True):

• Whether to normalize the kernel so the sum equals 1
• When True, preserves average brightness of the image
• When False, may brighten or darken the image depending on the kernel values
• Set using datatypes.Bool(True) or datatypes.Bool(False)
• Use True for standard smoothing, False only for special effects or specific mathematical operations

TIP

Best practice: Always use normalize=True unless you have a specific reason not to. Un-normalized kernels can lead to unexpected brightness changes.

output_format (default: "64bit"):

• The output bit depth
• Options: "8bit", "16bit", "32bit", "64bit"
• Higher depth preserves more precision but uses more memory
• Set using datatypes.String("depth")
• Use "8bit" for standard image display, "16bit" or "32bit" for intermediate processing, "64bit" for maximum precision in scientific applications

border_type (default: "default"):

• The border handling type for pixels near image edges
• Options: "default", "constant", "replicate", "reflect", "wrap"
• "default" uses the library's default behavior
• Use "default" or "reflect" for most cases

Where to Use the Skill in a Pipeline

Box Filtering is commonly used in the following pipelines:

• Preprocessing for downsampling - Smooth before reducing resolution
• Local averaging operations - Compute local statistics
• Integral image computation - Efficient sum computation
• Feature extraction preprocessing - Initial smoothing stage
• Noise estimation - Estimate noise levels through averaging

A typical pipeline for multi-scale image processing looks as follows:

# Example pipeline using box filter (parameters omitted).

from telekinesis import pupil
from datatypes import io

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

# 2. Apply box filter for initial smoothing
smoothed = pupil.filter_image_using_box(image=image, ...)

# 3. Downsample the smoothed image
downsampled = pupil.enhance_image_using_pyramid_downsampling(image=smoothed, ...)

# 4. Process at multiple scales
result = ...

Related skills to build such a pipeline:

• load_image: Load images from disk
• transform_image_using_pyramid_downsampling: Downsample images for multi-scale processing
• filter_image_using_gaussian_blur: Higher quality alternative for smoothing

Alternative Skills

Skill	vs. Box Filtering
filter_image_using_blur	filter_image_using_blur is simpler (fewer parameters) but less configurable. Use filter_image_using_box when you need control over normalization and output depth.
filter_image_using_gaussian_blur	Gaussian blur produces smoother, more natural results. Use gaussian for better visual quality, box for speed and simplicity.
filter_image_using_bilateral	Bilateral filter preserves edges. Use bilateral when edges matter, box for uniform smoothing.

When Not to Use the Skill

Do not use Box Filtering when:

• You need edge-preserving smoothing (Use bilateral filter instead)
• You want smooth, natural-looking results (Use Gaussian blur for better visual quality)
• You're removing salt-and-pepper noise (Use median blur instead)
• You need the absolute simplest API (Use filter_image_using_blur for fewer parameters)

WARNING

Box filters can create blocky artifacts in the output. For higher quality results, consider using Gaussian blur which provides smoother transitions.