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

# Zones

> Draw polygon zones on images with customizable styling and intelligent labeling.

## Overview

Renders defined zones as filled polygons with optional borders, displaying zone names, detection counts, and total entry statistics. Automatically adapts text size and thickness based on image resolution for optimal visibility across different image sizes.

## Function Signature

```python theme={null}
zones(
    image: np.ndarray,
    opacity: float = 0.3,
    border_thickness: Optional[int] = None,
    show_counts: bool = True,
    show_names: bool = True,
    font_scale: Optional[float] = None,
    font_thickness: Optional[int] = None,
    text_color: Optional[Tuple[int, int, int]] = None,
    text_bg_color: Optional[Tuple[int, int, int]] = None,
    text_bg_opacity: float = 0.7,
    count_position: str = 'center',
    draw_filled: bool = True,
    draw_border: bool = True
) -> np.ndarray
```

## Parameters

<ParamField path="image" type="np.ndarray" required>
  Input image to annotate. Must be 3-channel BGR format. zone\_manager: ZoneManager instance containing polygon zones with associated metadata. Must have 'zones' attribute containing Zone objects with polygon, color, name, and count attributes.
</ParamField>

<ParamField path="opacity" type="float" optional default="0.3">
  Fill opacity for zone polygons. Range: \[0.0, 1.0]. Default is 0.3 (30% transparency).
</ParamField>

<ParamField path="border_thickness" type="Optional[int]" optional default="None">
  Pixel thickness of zone borders. If None, automatically calculated based on image size. Range: \[1, 20]. Default adapts to image resolution.
</ParamField>

<ParamField path="show_counts" type="bool" optional default="True">
  Whether to display current detection count in each zone. Shows both current count and total entries if available. Default is True.
</ParamField>

<ParamField path="show_names" type="bool" optional default="True">
  Whether to display zone names as text labels. Default is True.
</ParamField>

<ParamField path="font_scale" type="Optional[float]" optional default="None">
  Scale factor for text size. If None, automatically calculated based on image resolution. Range: \[0.3, 2.0]. Default adapts to image size.
</ParamField>

<ParamField path="font_thickness" type="Optional[int]" optional default="None">
  Thickness of text stroke in pixels. If None, automatically calculated based on image size. Range: \[1, 5]. Default adapts to font scale.
</ParamField>

<ParamField path="text_color" type="Optional[Tuple[int, int, int]]" optional default="None">
  RGB color tuple for text labels. If None, uses white (255, 255, 255). Range: \[0, 255] per channel.
</ParamField>

<ParamField path="text_bg_color" type="Optional[Tuple[int, int, int]]" optional default="None">
  RGB color tuple for text background. If None, uses black (0, 0, 0). Range: \[0, 255] per channel.
</ParamField>

<ParamField path="text_bg_opacity" type="float" optional default="0.7">
  Opacity of text background rectangles. Range: \[0.0, 1.0]. Default is 0.7 (70% opacity).
</ParamField>

<ParamField path="count_position" type="str" optional default="'center'">
  Vertical position for count display relative to zone. Options: 'center' (zone centroid), 'top' (above zone), 'bottom' (below zone). Default is 'center'.
</ParamField>

<ParamField path="draw_filled" type="bool" optional default="True">
  Whether to fill zone polygons with semi-transparent color. Default is True.
</ParamField>

<ParamField path="draw_border" type="bool" optional default="True">
  Whether to draw zone polygon borders. Default is True.
</ParamField>

## Returns

<ResponseField name="result" type="np.ndarray">
  Annotated image with zones visualized. Modifies input image in-place and returns the modified array.
</ResponseField>

## Examples

<CodeGroup>
  ```python Example theme={null}
  import cv2
  import pixelflow as pf
  from shapely.geometry import Polygon

  # Load image and create zone manager with defined areas
  image = cv2.imread("surveillance_feed.jpg")
  zone_manager = pf.ZoneManager()
  zone_manager.add_zone("entrance", Polygon([(100, 100), (300, 100), (300, 200), (100, 200)]))
  zone_manager.add_zone("restricted", Polygon([(400, 150), (600, 150), (600, 300), (400, 300)]))

  # Basic usage - draw all zones with default semi-transparent fill
  annotated = pf.annotators.zones(image, zone_manager)

  # High-visibility zones with custom opacity and thick borders
  annotated = pf.annotators.zones(image, zone_manager, opacity=0.5,
  ```

  ```python Example theme={null}

  # Border-only zones with names positioned at bottom
  annotated = pf.annotators.zones(image, zone_manager, draw_filled=False,
  ```

  ```python Example theme={null}

  # Minimal zones with custom colors and no background
  annotated = pf.annotators.zones(image, zone_manager, text_color=(255, 255, 0),
  ```
</CodeGroup>

## Error Handling

<Warning>
  This function may raise the following exceptions:

  * **AssertionError**: If image is not a numpy ndarray.
  * **AttributeError**: If zone\_manager lacks 'zones' attribute or zones lack required properties (polygon, color, name, current\_count).
  * **IndexError**: If zone polygon coordinates are outside image boundaries during text positioning calculations.
</Warning>

## Notes

<Note>
  * Modifies the input image in-place for memory efficiency
  * Text size and thickness automatically adapt to image resolution when not specified
  * Zone colors are taken from individual Zone objects in the zone\_manager
  * Count display shows format "Count: X" or "Count: X (Total: Y)" when total\_entered available
  * Text positioning uses zone polygon centroid with automatic adjustment for top/bottom modes
  * Semi-transparent overlays are created using OpenCV's addWeighted for smooth blending
  * Polygon rendering uses anti-aliased lines for smooth appearance
  * Text background rectangles include padding calculated from adaptive parameters
  * Processing time scales with number of zones and image resolution
  * Memory usage is optimized through in-place image modification
  * Overlay operations create temporary image copies for transparency blending
  * Text rendering involves multiple OpenCV operations per label
</Note>