> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datamarkin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pixelate

> Applies pixelation effect to detected regions in the image with configurable padding.

## 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

```python theme={null}
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

```python Example theme={null}
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

> [!WARNING]
>
> 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

> [!NOTE]
>
> * 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.