Zone Count

This API Reference is based on DeGirum Tools version 0.16.6.

Zone Count Analyzer Module Overview

This module provides an analyzer (ZoneCounter) for counting objects within polygonal zones in video frames or images. It integrates with AI inference results to determine whether detected or tracked objects lie within user-defined polygon zones.

Key Features

• Polygonal Zone Definition: Support for arbitrary polygon shapes as counting zones

• Multiple Trigger Methods: Choose between anchor-point or IoPA-based zone entry detection

• Per-Class Counting: Track object counts separately by class labels

• Tracking Integration: Smooth counts over time using frame and time-based track presence

• Timeout Control: Configurable grace period for objects temporarily missing from zones

• Visual Overlay: Draw zones and per-zone object counts on images

• Interactive Editing: Optional OpenCV mouse callback support for zone adjustment

• Zone Presence Tracking: Monitor how long objects remain within zones

Typical Usage

1. Define polygon zones over the target video/image frame

2. Create a ZoneCounter instance with desired zones and settings

3. Process inference results through the analyzer chain

4. Access per-zone counts and object presence data

5. Optionally visualize zones and counts using annotate method

Integration Notes

• Requires detection results with bounding boxes

• Optional track IDs for tracking-related functionality

• Works best with ObjectTracker analyzer upstream

• Supports standard DeGirum PySDK result formats

• Handles partial/missing detections gracefully

Key Classes

• ZoneCounter: Main analyzer class for counting objects in zones

• ZonePresence: Internal class for tracking object presence in zones

Configuration Options

• zones: List of polygon definitions for counting areas

• classes: Optional list of class labels to count

• trigger_method: Zone entry detection method (anchor or iopa)

• tracking_timeout: Frames to wait before removing lost objects

• show_overlay: Enable/disable visual annotations

• show_counts: Display count numbers on zone overlays

• show_presence: Show object presence duration in zones

Classes

ZoneCounter

ZoneCounter

Bases: ResultAnalyzerBase

Analyzer that counts objects inside user-defined polygonal zones.

This analyzer integrates with PySDK inference results to determine whether detected or tracked objects lie within user-defined polygon zones. It supports per-class counting and object tracking with timeout periods.

The analyzer adds per-zone presence flags and counts to detected objects, with optional per-class breakdown and object tracking support. It can use object tracking to provide frame-based and time-based presence metrics.

Attributes:

Name	Type	Description
zone_counts	List[dict]	List of per-zone count dictionaries updated after each call to analyze().
key_in_zone	str	Name of the key inserted into result objects that stores zone-presence flags.
key_frames_in_zone	str	Name of the key inserted into result objects that stores the number of frames spent in each zone.
key_time_in_zone	str	Name of the key inserted into result objects that stores the total time (in seconds) spent in each zone.

Methods:

Name	Description
analyze	Determine per-zone presence for result and update cumulative counts.
annotate	Draw zones and their counts on image.
window_attach	Attach an OpenCV window for interactive editing, if supported.

Functions

__init__(count_polygons, ...)

__init__(count_polygons, *, class_list=None, per_class_display=False, triggering_position=AnchorPoint.BOTTOM_CENTER, bounding_box_scale=1.0, iopa_threshold=0.0, use_tracking=False, timeout_frames=0, window_name=None, show_overlay=True, show_inzone_counters=None, annotation_color=None, annotation_line_width=None)

Constructor.

Parameters:

Name	Type	Description	Default
count_polygons	Union[ndarray, list]	Polygon or list of polygons to count objects in.	required
class_list	List[str]	List of class labels to count. If None, all detected classes are counted. Default None.	None
per_class_display	bool	If True, maintain and display counts per class separately. Default False.	False
triggering_position	list or AnchorPoint or None	Anchor point(s) on the bounding box to use for zone triggering. If None, uses IoPA threshold instead. Default AnchorPoint.BOTTOM_CENTER.	BOTTOM_CENTER
bounding_box_scale	float	Scale factor applied to detection bounding boxes before checking zone membership. Default 1.0 (no scaling).	1.0
iopa_threshold	float	Intersection over polygon area threshold for considering an object inside a zone when using IoPA. Default 0.0 (any overlap is counted).	0.0
use_tracking	bool	If True, use object tracking to maintain zone presence information over time. Default False.	False
timeout_frames	int	Number of consecutive frames an object can be missing and still be considered in-zone (requires tracking). Default 0.	0
window_name	str	Name of an OpenCV window for interactive polygon editing. If provided, enables interactive mode via window_attach(). Default None.	None
show_overlay	bool	If True, enable drawing zone outlines and counts on images in annotate(). Default True.	True
show_inzone_counters	str or None	Which per-object in-zone counters to display on annotations: 'time' for time-in-zone, 'frames' for frame count, 'all' for both, or None for none. Default None.	None
annotation_color	tuple	RGB color for zone outlines and text. Default None (automatically chosen).	None
annotation_line_width	int	Thickness of zone outline lines (in pixels). Default None (uses default overlay line width).	None

_install_mouse_callback

_install_mouse_callback()

Internal method to install the OpenCV mouse callback on the attached window.

_lazy_init(result)

_lazy_init(result)

Performs deferred initialization tasks.

• Initializes polygon zones from the model result, computing necessary masks and data.

• Installs mouse callback if interactive adjustment is enabled.

Parameters:

Name	Type	Description	Default
result		PySDK inference result object containing an image for dimension reference.	required

_mouse_callback(event, ...)

_mouse_callback(event, x, y, flags, self)

staticmethod

Mouse event callback for interactive polygon zone editing.

Supports:

• Left-click and drag to move entire polygon.

• Right-click and drag to move individual vertices.

• Updates internal polygon state on changes.

Parameters:

Name	Type	Description	Default
event	int	OpenCV mouse event code.	required
x	int	X coordinate of the mouse event.	required
y	int	Y coordinate of the mouse event.	required
flags	int	Additional event flags.	required
self	Any	Instance of ZoneCounter.	required

analyze(result)

analyze(result)

Analyzes the inference result to count objects inside each polygonal zone.

Updates the result in-place with zone analysis data. Specifically, it adds a zone_counts attribute (a list of per-zone count dictionaries) to the result. Each detected object's dictionary is augmented with an in_zone list of booleans indicating zone membership. If tracking is enabled, each object also receives frames_in_zone and time_in_zone lists for frame count and time-in-zone metrics.

This method filters detections based on the specified class list and, if tracking is enabled, ignores detections without track IDs. It updates internal object state to handle short absences (using timeout_frames) and computes the total and per-class counts of objects in each zone.

Parameters:

Name	Type	Description	Default
result	InferenceResults	Inference result to analyze and augment with zone information.	required

Returns:

Type	Description
None	This method modifies the input result object in-place.

Raises:

Type	Description
AttributeError	If result object is missing required attributes.
TypeError	If result object is not of the expected type.

window_attach(win_name)

window_attach(win_name)

Attach an OpenCV window for optional interactive zone adjustment.

Installs a mouse callback on the given window that enables dragging polygon zones or their vertices for adjustment.

Parameters:

Name	Type	Description	Default
win_name	str	Name of the OpenCV window.	required