Detection Zones

Detection zones define specific areas within a camera’s field of view where detections are processed. By drawing polygon boundaries, you control where detections trigger events and which object classes are relevant in each area. Zones also power occupancy counting and Home Assistant occupancy sensors.

Zone Types

Inclusion Zones

Inclusion zones define areas where detections should trigger events. When inclusion zones are configured, only detections within at least one enabled inclusion zone produce events. Areas outside all inclusion zones are ignored.

If no inclusion zones are defined, the entire frame is treated as the active detection area.

Exclusion Zones

Exclusion zones define areas where detections are suppressed. Any detection whose center point falls within an exclusion zone is discarded, even if it also falls within an inclusion zone. Exclusion zones take precedence.

Use exclusion zones for:

• Trees, flags, and water features that cause false positives from wind movement
• Display screens or monitors visible in the camera view
• Reflective surfaces that produce ghost detections
• Areas with constant expected movement (conveyor belts, escalators)

How Zone Filtering Works

For each detection from the AI model:

1. Calculate the center point of the bounding box.
2. Exclusion check — if the center falls within any enabled exclusion zone, discard the detection.
3. Inclusion check — if inclusion zones exist, verify the center falls within at least one enabled inclusion zone. If not, discard.
4. Class filter check — verify the detected class is in the matching zone’s class filter list. If the zone has a filter and the class is not in it, discard.
5. Accept — tag the detection with the zone’s zone_id and zone_name.

Note

A detection only needs to fall within one enabled inclusion zone to be accepted. If zones overlap, the first matching zone (in database order) is used for tagging.

Zone Editor

The zone editor is accessed from Settings > AI Detection, then selecting a camera.

Drawing a Zone

1. Click on the camera view to place the first polygon point.
2. Continue clicking to add points. Each point connects to the previous one.
3. Close the polygon by clicking near the first point or using the Close button.
4. Configure the zone properties:

Property	Description
Name	Descriptive name (e.g., “Main Entrance”, “Parking Bay A”)
Type	Inclusion or Exclusion
Color	Overlay color for visualization
Class filter	Which classes trigger events in this zone (optional)
Enabled	Toggle the zone on/off without deleting it

Zone Coordinates

Zones use normalized coordinates (0.0 to 1.0) relative to the frame:

• x: 0.0 = left edge, x: 1.0 = right edge
• y: 0.0 = top edge, y: 1.0 = bottom edge

This ensures zones remain valid regardless of stream resolution. The editor handles normalization automatically.

Per-Zone Class Filters

Each zone can have its own class filter restricting which detection classes trigger events within that zone.

Zone	Classes	Use Case
Main Entrance	Person	Only detect people at the entrance
Parking Area	Car, Truck, Motorcycle	Only vehicles in parking
Perimeter Fence	Person, Dog	Intruders and animals near fence
Loading Bay	Truck, Bus	Large vehicle arrivals only
Garden	— (all classes)	Detect everything in garden area

If a zone’s class filter is empty, all server-level enabled classes are detected within that zone.

Caution

Per-zone filters work in conjunction with server-level class selection. A class must be enabled at both the server level and zone level. Adding “dog” to a zone filter has no effect if “dog” is disabled in the server-level class list.

Multiple Zones Per Camera

A camera can have any number of detection zones:

+--------------------------------------------------+
|  [Exclusion: Trees]                              |
|     xxxxxxx                                      |
|     xxxxxxx     +----------+                     |
|                 | Zone A   |    +-----------+    |
|                 | (Person) |    | Zone B    |    |
|                 +----------+    | (Vehicle) |    |
|                                 +-----------+    |
|  +---------------------------------------------+|
|  | Zone C: Perimeter (Person, Dog)              ||
|  +---------------------------------------------+|
+--------------------------------------------------+

• Zone A at the entrance triggers only on people.
• Zone B covering the road triggers only on vehicles.
• Zone C along the bottom perimeter triggers on people and dogs.
• Exclusion zone over the trees suppresses all detections.
• Unzoned areas produce no events (inclusion zones are defined).

Zone-Based Occupancy Counting

Each inclusion zone maintains a real-time occupancy count — the number of distinct objects currently detected within the zone. This is useful for:

• Parking occupancy — count vehicles in a parking zone
• Room occupancy — count people in a defined area
• Queue monitoring — count people in a queue zone

How Counting Works

1. The detection engine runs inference and identifies objects within each zone.
2. Objects are tracked across frames using the centroid tracker.
3. The current count of unique tracked objects per zone is maintained.
4. Counts are reported to the management server with each event batch.

Occupancy Thresholds

Configure per-zone occupancy thresholds to trigger alarms:

Setting	Description
Max Occupancy	Trigger an alarm when zone count exceeds this value
Min Occupancy	Trigger an alarm when zone count drops below this value
Threshold Duration	How long the count must exceed the threshold before triggering (prevents transient triggers)

Home Assistant Integration

Detection zones are exposed in Home Assistant as binary sensors and occupancy data:

Zone Occupancy Sensors

Each enabled detection zone creates a binary sensor:

• Entity: binary_sensor.{camera_name}_{zone_name}
• Device class: Occupancy
• State: on when objects are detected in the zone, off when empty
• Attributes:

Attribute	Description
zone_id	UUID of the detection zone
zone_name	Human-readable zone name
last_event_type	Last detected class (person, car, etc.)
confidence	Confidence of the last detection
occupancy_count	Current number of objects in the zone

Automation Examples

Trigger lights when a person enters a zone:

automation:
  - alias: "Driveway person detected"
    trigger:
      - platform: state
        entity_id: binary_sensor.front_camera_driveway
        to: "on"
    action:
      - service: light.turn_on
        entity_id: light.driveway_floodlight

Alert when parking zone is full:

automation:
  - alias: "Parking full alert"
    trigger:
      - platform: numeric_state
        entity_id: binary_sensor.parking_camera_lot_a
        attribute: occupancy_count
        above: 50
    action:
      - service: notify.mobile_app
        data:
          title: "Parking Full"
          message: "Lot A has reached capacity"

Enabling and Disabling Zones

Each zone has an enabled toggle. Disabling a zone excludes it from detection filtering without deleting its configuration:

• Temporarily suppress detections during construction or maintenance
• Test zone configurations by enabling one at a time
• Seasonal adjustments (disable outdoor zones in extreme weather)

Events and Zone Tagging

When a detection matches a zone, the event record includes:

Field	Description
zone_id	UUID of the matching zone
zone_name	Human-readable name
zone_type	Inclusion or exclusion

This tagging enables filtering events by zone on the Events page and creating alarm rules that trigger only for detections in specific zones.

Best Practices

• Exclude high-noise areas with exclusion zones rather than trying to cover everything with inclusion zones.
• Use separate zones for different class needs rather than one large zone with all classes.
• Keep zones slightly larger than the target area to account for bounding box center-point detection (a person at the zone edge may have their center outside it).
• Name zones consistently across cameras for easier filtering (e.g., always “Perimeter” for fence-line zones).
• Test with Live Detection — use the Live Detection page to verify detections trigger as expected within your zones.
• Start with inclusion zones before adding exclusion zones. Often, well-placed inclusion zones eliminate the need for exclusions.