​
Overview

Blur annotator for privacy-preserving object detection visualization. This module provides Gaussian blur effects for detected regions, commonly used for privacy protection, aesthetic effects, or focus redirection in computer vision applications. The blur effect maintains natural appearance while obscuring sensitive details. Creates a natural-looking privacy filter by applying Gaussian blur to detected object regions while preserving the rest of the image. The function automatically handles boundary conditions and provides adaptive kernel sizing for optimal results.

​
Function Signature

blur(
    image: np.ndarray,
    detections: Detections,
    kernel_size: Optional[int] = None,
    padding_percent: float = 0.05
) -> np.ndarray

​
Parameters

​
image
np.ndarray
required
Input image as BGR or RGB array with shape (H, W, C). Must be a valid NumPy array.
​
detections
Detections
required
PixelFlow Detections object containing bounding boxes. Each detection must have a ‘bbox’ attribute with (x1, y1, x2, y2) coordinates in pixel units.
​
kernel_size
Optional[int]
default:"None"
Size of the Gaussian blur kernel in pixels. Larger values create stronger blur effect. Must be positive and odd. If None, uses adaptive sizing based on image dimensions. Default is None.
​
padding_percent
float
default:"0.05"
Additional padding around each detection as percentage of bounding box size. Range: 0.0-0.5. Default is 0.05 (5% padding on each side).

​
Returns

​
result
np.ndarray
Image with blurred regions where objects were detected. The input image is modified in-place for memory efficiency.

​
Examples

import cv2
import pixelflow as pf
from ultralytics import YOLO

# Load image and get model predictions
image = cv2.imread("faces_in_crowd.jpg")
model = YOLO("yolo11n.pt")
outputs = model.predict(image)  # Raw model outputs
detections = pf.results.from_ultralytics(outputs)  # Convert to PixelFlow format

# Apply blur with default adaptive settings
blurred_image = pf.annotators.blur(image, detections)

# Apply stronger blur with custom kernel size
strong_blur = pf.annotators.blur(image, detections, kernel_size=25)

# Apply blur with expanded padding for better coverage
padded_blur = pf.annotators.blur(image, detections, padding_percent=0.15)

# Minimal blur for subtle privacy protection
subtle_blur = pf.annotators.blur(image, detections, kernel_size=7, padding_percent=0.02)

​
Error Handling

This function may raise the following exceptions:
  • AssertionError: If image is not a NumPy array.
  • AttributeError: If detections objects don’t have required ‘bbox’ attribute.
  • IndexError: If bbox coordinates are invalid or outside image bounds.

​
Notes

  • Modifies the input image in-place for memory efficiency
  • Automatically adapts kernel size based on image dimensions when not specified
  • Even kernel sizes are automatically converted to odd numbers (required for Gaussian blur)
  • Skips regions smaller than the kernel size to prevent processing errors
  • Padding is automatically clamped to range [0.0, 0.5] to prevent excessive expansion
  • Bounding boxes are clipped to image boundaries to handle edge cases
  • Uses OpenCV’s highly optimized GaussianBlur implementation
  • Efficient for real-time video processing applications
  • Processing time scales linearly with number of detections and blur strength
  • Memory usage is minimal due to in-place modification