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	Description	Type	Default	Required
`roi_labels`	Comma separated list of labels for each ROI in the `rois` list. Format: `label1, label2` Ex: `door, window`	hidden	null	false
`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`	polygon	null	false
`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)	model-label	null	true		`proximity_mode`	Proximity mode. Options:`distance`Object distance (A+B: A with B in distance limit, A-B: A without B in distance limit),`enclosed`Object within (A+B: A inside B, A-B: A outside B),`contains`Object contains (A+B: A contains B, A-B: A does not contain B)	enum	"distance"	false
`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. Min: 0, Max: 1.0, Step: 0.05. Conditional on proximity_mode being set to`distance`.	slider	0.1	true		`merge_mode`	Group merge mode. Options:`no_merge`, `same_type`, `any_type`	enum	same_type	false
`min_group_size`	Ignore groups smaller than this size.	number	1	true
`min_group_lifespan`	Ignore groups that exist for less than this amount of time in seconds.	float	1.0	true
`output_mode`	Group output mode. Options:`object`(Output each group as an individual object with a unique ID),`attribute`(Adds the 2nd (& subsequent) objects (B) as attributes to the primary object (A))	enum	"object"	false
`group_lifespan_trigger_threshold`	Set a trigger when the group lifespan exceeds this time in seconds.	float	5	true
`group_size_trigger_threshold`	Set a trigger when the group size exceeds this number.	number	1	true
`display_groups_mode`	Display groups on video. Options:`none`, `above_threshold`, `all`	enum	"above_threshold"	false
`display_properties`	Display group properties. Options:`basic`, `intermediate`, `detailed`	enum	"intermediate"	false
`display_roi`	Display ROI on video?	bool	true	false
`tracking_mode`	Tracking mode. Options:`centroid`, `top_center`, `bottom_center`, `left_center`, `right_center`	enum	"centroid"	false
`object_contain_mode`	Object containment mode. Options:`bbox`(Bounding box inside other object's bounding box),`tracking_point`(Selected tracking point inside other object's bounding box)	enum	"tracking_point"	false
`negative_attribute_prefix`	Prefix for negative attributes. Conditional on output_mode being set to "attribute".	string	"-"	false

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`)
`objects[x]`	Group is inserted as a new object with a unique ID, or object attributes are added to the existing object depending on the value of `output_mode` property.

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.