​
Overview

The pixelation effect is achieved by downscaling regions to a reduced resolution and then upscaling back to original size using nearest neighbor interpolation, creating distinctive blocky patterns. This technique provides privacy protection while maintaining object silhouettes.

​
Function Signature

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

​
Parameters

​
image
np.ndarray
required
Input image as BGR or RGB format numpy array. Shape should be (height, width, 3) or (height, width).
​
detections
Detections
required
Detection results containing bounding boxes. Each detection must have a ‘bbox’ attribute with (x1, y1, x2, y2) coordinates.
​
pixel_size
Optional[int]
default:"None"
Size of pixelation blocks in pixels. Larger values create more pronounced blocky effects. If None, automatically calculated based on image size. Range: [1, inf]. Default is None (adaptive sizing).
​
padding_percent
float
default:"0.05"
Additional padding around detections as percentage of bounding box dimensions. Range: [0.0, 0.5]. Default is 0.05 (5% padding on each side).

​
Returns

​
result
np.ndarray
Modified image with pixelated regions where objects were detected. Original image is modified in-place and also returned.

​
Examples

import cv2
import pixelflow as pf
from ultralytics import YOLO

# Load image and run object detection
image = cv2.imread("street_scene.jpg")
model = YOLO("yolo11n.pt")
outputs = model.predict(image)  # Raw YOLO outputs
results = pf.results.from_ultralytics(outputs)  # Convert to PixelFlow format

# Basic usage with adaptive pixel size
pixelated_image = pf.annotators.pixelate(image, results)

# Custom pixel size for stronger effect
strong_pixelated = pf.annotators.pixelate(image, results, pixel_size=20)

# Fine-tuned padding for better coverage
precise_pixelated = pf.annotators.pixelate(image, results, pixel_size=15, padding_percent=0.1)

# Minimal pixelation for subtle privacy protection
subtle_pixelated = pf.annotators.pixelate(image, results, pixel_size=5, padding_percent=0.02)

​
Error Handling

This function may raise the following exceptions:
  • AssertionError: If input image is not a numpy array.
  • AttributeError: If detections don’t have required ‘bbox’ attribute.
  • ValueError: If image dimensions are invalid or bounding boxes are malformed.

​
Notes

  • Image is modified in-place for memory efficiency
  • Pixel size is automatically clamped to minimum value of 1
  • Padding percentage is automatically clamped to range [0.0, 0.5]
  • Bounding boxes are automatically clipped to image boundaries
  • Small regions (smaller than pixel_size) are skipped to prevent artifacts
  • Uses INTER_LINEAR for downscaling (quality) and INTER_NEAREST for upscaling (pixelation effect)
  • Processes 11,000+ FPS on 320x240 images with small pixel sizes
  • Processes 900+ FPS on 4K images with moderate pixel sizes
  • Performance scales inversely with pixel_size (smaller blocks = more operations)
  • Uses OpenCV’s SIMD-optimized resize operations for maximum efficiency
  • Memory usage is minimal due to in-place ROI processing