​
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

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

​
image
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.
​
opacity
float
default:"0.3"
Fill opacity for zone polygons. Range: [0.0, 1.0]. Default is 0.3 (30% transparency).
​
border_thickness
Optional[int]
default:"None"
Pixel thickness of zone borders. If None, automatically calculated based on image size. Range: [1, 20]. Default adapts to image resolution.
​
show_counts
bool
default:"True"
Whether to display current detection count in each zone. Shows both current count and total entries if available. Default is True.
​
show_names
bool
default:"True"
Whether to display zone names as text labels. Default is True.
​
font_scale
Optional[float]
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.
​
font_thickness
Optional[int]
default:"None"
Thickness of text stroke in pixels. If None, automatically calculated based on image size. Range: [1, 5]. Default adapts to font scale.
​
text_color
Optional[Tuple[int, int, int]]
default:"None"
RGB color tuple for text labels. If None, uses white (255, 255, 255). Range: [0, 255] per channel.
​
text_bg_color
Optional[Tuple[int, int, int]]
default:"None"
RGB color tuple for text background. If None, uses black (0, 0, 0). Range: [0, 255] per channel.
​
text_bg_opacity
float
default:"0.7"
Opacity of text background rectangles. Range: [0.0, 1.0]. Default is 0.7 (70% opacity).
​
count_position
str
default:"'center'"
Vertical position for count display relative to zone. Options: ‘center’ (zone centroid), ‘top’ (above zone), ‘bottom’ (below zone). Default is ‘center’.
​
draw_filled
bool
default:"True"
Whether to fill zone polygons with semi-transparent color. Default is True.
​
draw_border
bool
default:"True"
Whether to draw zone polygon borders. Default is True.

​
Returns

​
result
np.ndarray
Annotated image with zones visualized. Modifies input image in-place and returns the modified array.

​
Examples

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,

​
Error Handling

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.

​
Notes

  • 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