Overview

The Proximity Detector node detects and creates groups of objects when they are close to or far from each other. This node makes it easy to build common use cases such as Object left behind, Crowd forming, Service times for drive throughs, etc.

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

Current implementation limitation: the As Objects property value is object, but the script currently checks for objects. Configuring As Objects through the property UI therefore follows the attributes path instead of adding a group object. Use the node's group metadata downstream until this code mismatch is corrected.

Inputs & Outputs

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

Properties

Property	Description	Type	Default	Required
`roi_labels`	Region of interest label	`string`	—	No
`rois`	Region 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
`proximity_groups`	ex. `car+person,person+person,bag-person`. Comma-separated list of group types to detect. Format: A+B (objects of type A which have type B nearby), A-B (objects of type A without any type B nearby).	model-labels	`null`	Yes
`proximity_mode`	Proximity mode. Options: Object distance (`distance`): A+B (A with B in distance limit), A-B (A without B in distance limit); Object within (`enclosed`): A+B (A inside B), A-B (A outside B); Object contains (`contains`): A+B (A contains B), A-B (A does not contain B).	`enum`	`distance`	No
`distance_threshold`	Pixel distance between two objects to be considered as within a '+' group or outside a '-' group. Range: 0-1. Specified as percentage of video source width. Conditional on `proximity_mode` being `distance`. Range: minimum `0`, maximum `1.0`. Step: `0.05`. Unit: %.	`float`	`0.1`	Yes
`merge_mode`	Merge groups of same or any type that overlap each other within the group distance limit. Options: No merge (`no_merge`); Same type (`same_type`); Any type (`any_type`).	`enum`	`same_type`	No
`min_group_size`	Ignore groups smaller than this size.	`number`	`1`	Yes
`min_group_lifespan`	Ignore groups that exist for less than this amount of time in seconds. Unit: seconds.	`float`	`1.0`	Yes
`output_mode`	Output groups as individual objects or as attributes to the primary object. Options: As Objects (`object`): Output each group as an individual object with a unique ID; As Attributes (`attribute`): Adds the 2nd (& subsequent) objects (B) as attributes to the primary object (A).	`enum`	`object`	No
`group_lifespan_trigger_threshold`	Set a trigger when the group lifespan exceeds this time in seconds. Unit: seconds.	`float`	`5`	Yes
`group_size_trigger_threshold`	Set a trigger when the group size exceeds this number.	`number`	`1`	Yes
`display_groups_mode`	Display groups that meet this criteria on the video. Options: None (`none`); Above threshold (`above_threshold`); All (`all`).	`enum`	`above_threshold`	No
`display_properties`	Display these group properties. Basic includes lifespan and size, intermediate adds group type, detailed adds group ID. Options: Basic (`basic`); Intermediate (`intermediate`); Detailed (`detailed`).	`enum`	`intermediate`	No
`display_roi`	Display ROI on video?	`bool`	`true`	No
`tracking_mode`	The point to be used as tracking point, refers to the position on the object's bounding box. Options: Centroid (`centroid`); Top Center (`top-center`); Bottom Center (`bottom-center`); Left Center (`left-center`); Right Center (`right-center`).	`enum`	`centroid`	No
`object_contain_mode`	Object containment mode. Options: Bounding Box (`bbox`): Bounding box inside other object's bounding box; Tracking Point (`tracking_point`): Selected tracking point (above) inside other object's bounding box; Overlap (`bbox_overlap`): Bounding box overlaps other object's bounding box.	`enum`	`tracking_point`	No
`negative_attribute_prefix`	Prefix for negative attributes. For example, if a group of 'car-person' is detected, the person object will be tagged with the attribute `-car` or `no_car`. Conditional on `output_mode` being `attribute`.	`string`	`-`	No

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>.current_group_count`	`integer`	Number of proximity groups currently present.
`nodes.<node_id>.rois.<roi_label>.groups_entered_delta`	`integer`	When one or more new groups enter the ROI
`nodes.<node_id>.rois.<roi_label>.groups_above_lifespan_threshold_count`	`integer`	Number of groups older than the configured lifespan threshold.
`nodes.<node_id>.rois.<roi_label>.groups_above_lifespan_threshold_delta`	`integer`	When one or more groups exceeds lifespan threshold
`nodes.<node_id>.rois.<roi_label>.groups_above_size_threshold_count`	`integer`	Number of groups larger than the configured size threshold.
`nodes.<node_id>.rois.<roi_label>.groups_above_size_threshold_delta`	`integer`	When one or more groups exceeds size 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>.groups[].id`	`integer`	Identifier assigned to the proximity group.
`nodes.<node_id>.rois.<roi_label>.groups[].label`	`string`	Object-class combination represented by the group.
`nodes.<node_id>.rois.<roi_label>.groups[].objects`	`array`	Array of tracking IDs of objects belonging to the group.
`nodes.<node_id>.rois.<roi_label>.groups[].lifespan`	`number`	Time in seconds that the group has persisted.
`nodes.<node_id>.rois.<roi_label>.objects_of_interest_keys`	`array`	Array of metadata keys that contain object IDs relevant to downstream integrations.
`nodes.<node_id>.rois.<roi_label>.description`	`string`	Human-readable summary of the node’s current result.
`nodes.<node_id>.type`	`string`	Identifies the node type that produced this metadata.

JSON example

{
  "nodes": {
    "annotate_proximity1": {
      "rois": {
        "roi1": {
          "coords": [],
          "current_group_count": 0,
          "description": "value",
          "groups": [
            {
              "id": 0,
              "label": "person+car",
              "lifespan": 10.0,
              "objects": [123456789,1231121321]
            }
          ],
          "groups_above_lifespan_threshold_count": 0,
          "groups_above_lifespan_threshold_delta": 0,
          "groups_above_size_threshold_count": 0,
          "groups_above_size_threshold_delta": 0,
          "groups_entered_delta": 0,
          "objects_of_interest_keys": []
        }
      },
      "type": "annotate_proximity"
    }
  }
}

Additional details

Object labels and attributes

Object labels/classes added: When the output_mode is object output mode, a configured proximity-group label is added as a new object with class 999.
Object attribute labels/classes added: When the output_mode is attribute, for positive relationships, each secondary object's label is added to the primary object as an attribute with . replaced by _, retaining the secondary object's class ID. Negative relationships add <negative prefix><secondary label> attribute (also replacing . with _) with class 999 to the primary object.