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.

Inputs & Outputs

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

Properties

Property	Value
`rois`	Semicolon separated list of areas in the video within which the Proximity Detector tracks these objects. If none is specified, the Proximity Detector tracks objects within the entire frame. Format: `left1,top1,right1,bottom1; left2,top2,right2,bottom2` Ex: `10,10,100,100; 200,200,300,300`
`roi_labels`	Comma separated list of labels for each ROI in the `rois` list above. Format: `label1, label2` Ex: `door, window`
`proximity_groups`	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) Ex. `car+person,person+person,bag-person,car.red+person` Accepted formats: `object_label`: any object of this type, with or without a classifier attribute. Example: `car`, `object_label.class_type`: any object of this type that has a specific classifier attribute. Example: `car.red`, `object_label.`: any object of this type that has at least one classifier attribute. Example: `car.` (this will match `car.red`, `car.yellow`, etc)
`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.
`merge_mode`	Merge groups of same or any type that overlap each other within the Group Distance Limit. Options: `no_merge` : Do not merge overlapping groups, `same_type`: Only merge groups of the same type. For example, will only merge two `car+person` groups that overlap, `any_type` : Merge groups of any type. For example, will merge `car+person` and `car+bag` groups if there's a `car` with a `person` and `bag` near it.
`min_group_size`	Ignore groups smaller than this size.
`group_size_trigger_threshold`	Set a trigger when the group size exceeds this number.
`min_group_lifespan`	Ignore groups that exist for less than this amount of time in seconds.
`group_lifespan_trigger_threshold`	Set a trigger when the group lifespan exceeds this time in seconds.
`display_groups_mode`	Display groups that meet this criteria on the video. Options: `none` : None, `above_threshold` : Only those above the size or lifespan thresholds, `all` : All
`display_properties`	Display these group properties if Display Groups Mode is not None. Options: `basic` : Basic includes Lifespan + Size, `intermediate : Basic + Group type,` detailed : Intermediate + Group ID
`display_roi`	If true, ROI will be drawn on video

Metadata

Metadata Property	Description
`nodes.<node_id>`	Describes the ROIs monitored by this node, and their properties. Format : as defined in the table below. `<node_id>` for Proximity Detector Nodes is of the form `annotate_proximityX` (ex. `annotate_proximity1`)

Example

"nodes": {
    "annotate_proximity1": {
        "type": "annotate_proximity",
        "rois": {
            "<roi_label>": {
                "coords": [[<point1_x>, <point1_y>], 
                           [<point2_x>, <point2_y>], 
                           [<point3_x>, <point3_y>]],
                "groups_entered_delta": <int>,
                "groups_above_lifespan_threshold_count": <int>,
                "groups_above_lifespan_threshold_delta": <int>,
                "groups_above_size_threshold_count": <int>,
                "groups_above_size_threshold_delta": <int>,                  
                "current_group_count": <int>,
                "groups": [
                  	{
                        "id": <group unique ID>,
                        "label": "<group type>",
                        "objects": [<object_id1>, <object_id2>, ....],
												"lifespan": <seconds>                      
                    }
                ]
            }
        }
    }
}

Format

Key	Type	Description
`<roi_label>`	Array of dictionaries	Contains information about this specific ROI
`<roi_label>.coords`	Array of Arrays	Contains the bounding box coordinates that represent this ROI
`<roi_label>.current_group_count`	Integer	Number of groups currently in this ROI
`<roi_label>.groups_entered_delta`	Integer	Number of groups that entered the ROI between last frame and this frame
`<roi_label>.groups_above_lifespan_threshold_count`	Integer	Number of groups inside the ROI above the specified time threshold
`<roi_label>.groups_above_lifespan_threshold_delta`	Integer	Number of new groups that exceeded the time threshold between the last frame and this frame
`<roi_label>.groups_above_size_threshold_count`	Integer	Number of groups inside the ROI above the specified size threshold
`<roi_label>.groups_above_size_threshold_delta`	Integer	Number of new groups that exceeded the size threshold between the last frame and this frame
`<roi_label>.groups`	Array of dictionaries	Information about the groups currently in the ROI. `id` : Unique identifier for a specific group. `label` : Group Type (ex. `car+person`). `objects` : List of object IDs that make up this group, as obtained from Track Objects Node. `lifespan` : Time this group has been seen.