Overview

The Occupancy Monitor (previously known as Queue Length Counter) node keeps track of the number and how long each detected, tracked object has been present in the specified region in the video, can highlight objects and generate max time alarms, and adds the queue analytics metadata to the frame metadata.

This node generates diverse queue metrics: the total number of objects served, the minimum and maximum queue size, the number of objects that waited on queue more than a pre-specified time (so-called alarms), the minimum, maximum and mean waiting time, etc.

This node requires a AI Model Node and a Track Objects Node before it in order to function properly.

Inputs & Outputs

Inputs : 1, Media Format : Raw Video
Outputs : 1, Media Format: Raw Video
Output Metadata : Queue Information

Properties

Property	Description	Type	Default	Required
`roi_labels`	Regions of interest labels	`string`	—	No
`rois`	Regions of interest. Conditional on `roi_labels`. Format: comma-separated normalized `x,y` coordinate pairs; separate multiple polygons with semicolons (for example, `0.1,0.1,0.9,0.1,0.9,0.9`).	`string`	`null`	No
`objects_to_track`	ex. `car`,`person`,`car.red`. Object types and classes to include. Leave blank to include all.	model-labels	`null`	No
`min_queue_activation_time`	Min. time an object should be present in the ROI in order to be considered on queue analytics. Unit: seconds.	`float`	`1.0`	Yes
`presence_threshold`	Create an alarm and shows an orange bounding box around object if present more than specified seconds in the ROI. Unit: seconds.	`float`	`null`	No
`max_occupancy_threshold`	Set a trigger when number of objects in the ROI exceeds or drops below this threshold.	`number`	`null`	No
`crossing_buffer`	Interval during which an object will not be repeatedly counted if it leaves and reenters the ROI. Unit: seconds.	`float`	`1.0`	Yes
`trigger_events`	Triggers these events. Leave blank to not trigger any events. Options: Object enters ROI (`enter`); Object exits ROI (`exit`); Object above max time in ROI (`max_wait`); ROI below max occupancy threshold (`below_max_occupancy`); ROI above max occupancy threshold (`above_max_occupancy`). Format: array of selected option values.	`string[]`	`null`	No
`event_template`	Template for enter/exit/max_wait events. Leave blank to use defaults. Available variables: `{object_type}`, `{object_attributes}`, `{state}`, `{roi}`.	`string`	`null`	No
`add_object_attributes`	Add specified labels as attributes to objects that interact with the ROI. ROI States include enter/exit/max_wait. Options: None (`none`); State (enter/exit/max_wait) (`state`); ROI (`roi`); ROI_State (`roi_state`).	`enum`	`none`	No
`display_roi`	Display ROI?	`bool`	`true`	No
`display_roi_meta`	Display ROI Statistics? Options: None (`none`): Do not display; Basic (`basic`): Display Occupancy counts only; Detailed (`detailed`): Display all ROI statistics.	`enum`	`detailed`	No
`display_objects`	Display objects? Options: None (`none`): Do not display; Basic (`basic`): Tracking point only; Detailed (`detailed`): Tracking point and time.	`enum`	`detailed`	No
`tracking_mode`	Tracking mode. Options: Centroid (`centroid`); Top center (`top-center`); Bottom center (`bottom-center`); Left center (`left-center`); Right center (`right-center`).	`enum`	`centroid`	No
`average_wait_mode`	Average wait time mode. Options: Moving (`moving`): Average of last N exited objects; Cumulative (`cumulative`): Average of all exited objects; Current (`current`): Average of current objects.	`enum`	`moving`	No
`average_wait_last_n`	Number of last exited objects to average over in moving average mode. Range: minimum `1`.	`number`	`10`	No
`roi_areas`	Comma separated list of areas of the ROIs. Used for density calculation.	`string`	`null`	No
`persistent_storage`	Persist analytics across restarts?	`bool`	`false`	No

Events

Triggering specific events using trigger_events and event_template fields allows you to add Events to metadata. These Events can then be processed by downstream nodes to publish metrics to a Dashboard, or send notifications or trigger alarms / bookmarks.

Output Metadata

The fields below are declared by this node's metadata schema; the JSON values are representative examples.

Path	Type	Description
`nodes.<node_id>.rois.<roi_label>.total_served`	`integer`	Cumulative number of objects that have left the queue.
`nodes.<node_id>.rois.<roi_label>.wait_alarms`	`integer`	Cumulative number of excessive-wait alarms.
`nodes.<node_id>.rois.<roi_label>.current_queue_size`	`integer`	Number of objects currently in the queue.
`nodes.<node_id>.rois.<roi_label>.min_queue_size`	`integer`	Smallest queue size observed during the measurement window.
`nodes.<node_id>.rois.<roi_label>.max_queue_size`	`integer`	Largest queue size observed during the measurement window.
`nodes.<node_id>.rois.<roi_label>.min_wait_time`	`integer`	Shortest observed wait time in seconds.
`nodes.<node_id>.rois.<roi_label>.max_wait_time`	`integer`	Longest observed wait time in seconds.
`nodes.<node_id>.rois.<roi_label>.mean_wait_time`	`integer`	Mean observed wait time in seconds.
`nodes.<node_id>.rois.<roi_label>.estimated_wait_time`	`integer`	Estimated current queue wait time in seconds.
`nodes.<node_id>.rois.<roi_label>.objects_entered_delta`	`integer`	When one or more new objects enter the ROI
`nodes.<node_id>.rois.<roi_label>.objects_exited_delta`	`integer`	When one or more objects exit the ROI
`nodes.<node_id>.rois.<roi_label>.objects_above_max_waiting_time_count`	`integer`	Number of objects whose waiting time exceeds the configured maximum.
`nodes.<node_id>.rois.<roi_label>.objects_above_max_waiting_time_delta`	`integer`	When one or more objects exceed the maximum waiting time
`nodes.<node_id>.rois.<roi_label>.objects_above_max_occupancy_count`	`integer`	Number of objects above the configured occupancy limit.
`nodes.<node_id>.rois.<roi_label>.occupancy_above_max_threshold_delta`	`integer`	When occupancy hits or exceeds the maximum threshold
`nodes.<node_id>.rois.<roi_label>.occupancy_below_max_threshold_delta`	`integer`	When occupancy falls below the maximum threshold
`nodes.<node_id>.rois.<roi_label>.coords`	`array`	Array of pixel coordinates defining the configured ROI or line.
`nodes.<node_id>.rois.<roi_label>.current_density`	`number`	Current object density within the ROI.
`nodes.<node_id>.rois.<roi_label>.objects_below_max_occupancy_count`	`integer`	Number of objects within the configured occupancy limit.
`nodes.<node_id>.rois.<roi_label>.current_objects.<object_id>.first_seen`	`number`	Pipeline timestamp when the object first entered the ROI.
`nodes.<node_id>.rois.<roi_label>.current_objects.<object_id>.first_seen_utc`	`string`	UTC timestamp in ISO 8601 when the object first entered the ROI.
`nodes.<node_id>.rois.<roi_label>.current_objects.<object_id>.time_present`	`number`	Time in seconds that the object has been present in the ROI.
`nodes.<node_id>.rois.<roi_label>.exited_objects.<object_id>.first_seen`	`number`	Pipeline timestamp when the exited object first entered the ROI.
`nodes.<node_id>.rois.<roi_label>.exited_objects.<object_id>.first_seen_utc`	`string`	UTC timestamp in ISO 8601 when the exited object first entered the ROI.
`nodes.<node_id>.rois.<roi_label>.exited_objects.<object_id>.time_present`	`number`	Time in seconds that the exited object was present in the ROI.
`nodes.<node_id>.events_delta`	`integer`	When one or more Occupancy events are triggered
`nodes.<node_id>.events`	`array`	Array of event names generated by this node for the current frame.
`nodes.<node_id>.type`	`string`	Identifies the node type that produced this metadata.

JSON example

{
  "nodes": {
    "annotate_queue1": {
      "events": ["person entered room"],
      "events_delta": 1,
      "rois": {
        "roi1": {
          "coords": [
              [468, 172],
              [597, 307],
              [912, 206],
              [1227, 277],
              [1247, 135],
              [1054, 91],
              [946, 121],
              [797, 87],
              [645, 104],
              [468, 172]
          ],
          "current_density": 0.0,
          "current_objects": {
            "<object_tracking_id>": {
              "first_seen": 0.0,
              "first_seen_utc": "2022-10-21T16:16:06.363395Z",
              "time_present": 0.0
            }
          },
          "current_queue_size": 0,
          "estimated_wait_time": 0,
          "exited_objects": {
            "<object_tracking_id>": {
              "first_seen": 0.0,
              "first_seen_utc": "2022-10-21T16:16:06.363395Z",
              "time_present": 0.0
            }
          },
          "max_queue_size": 0,
          "max_wait_time": 0,
          "mean_wait_time": 0,
          "min_queue_size": 0,
          "min_wait_time": 0,
          "objects_above_max_occupancy_count": 0,
          "objects_above_max_waiting_time_count": 0,
          "objects_above_max_waiting_time_delta": 0,
          "objects_below_max_occupancy_count": 0,
          "objects_entered_delta": 0,
          "objects_exited_delta": 0,
          "occupancy_above_max_threshold_delta": 0,
          "occupancy_below_max_threshold_delta": 0,
          "total_served": 0,
          "wait_alarms": 0
        }
      },
      "type": "annotate_queue"
    }
  }
}

Object labels and attributes

Object labels/classes added: No new class is created. The node can reinsert a tracked upstream object, preserving its original label and class.
Object attribute labels/classes added: Time present uses class 10101. Depending on add_object_attributes, the queue state (enter, exit, or max_wait) uses class 35101, the ROI label uses class 35102, and <ROI>_<state> uses class 35103.