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

<ParamField path="image" type="np.ndarray" required>
  Input image as BGR or RGB format numpy array. Shape should be (height, width, 3) or (height, width).
</ParamField>

<ParamField path="detections" type="Detections" required>
  Detection results containing bounding boxes. Each detection must have a 'bbox' attribute with (x1, y1, x2, y2) coordinates.
</ParamField>

<ParamField path="pixel_size" type="Optional[int]" optional 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).
</ParamField>

<ParamField path="padding_percent" type="float" optional 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).
</ParamField>

## Returns

<ResponseField name="result" type="np.ndarray">
  Modified image with pixelated regions where objects were detected. Original image is modified in-place and also returned.
</ResponseField>

## Examples

<CodeGroup>
  ```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)

  ```
</CodeGroup>

## 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.
</Warning>

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