Overview

The Heatmap node overlays a color heatmap on the video that shows how much objects of a given type or attribute have used each part of the frame, helping you understand space utilization — which areas are busy, for how long, and where the hotspots are.

Each frame, the tracking point of every matching object (by default the bottom-center of the bounding box, approximating floor position) is mapped to a cell in a low-resolution grid. The selected metric determines what is accumulated into that cell. The grid is smoothed, color mapped, and blended over the video; areas below the display threshold keep the raw video. You can optionally restrict the heatmap to one or more regions of interest — when set, only objects inside them are counted and the overlay is drawn only within those regions; otherwise the whole frame is used.

The node supports four metrics — total dwell time, average occupancy, occupancy % of time, and unique visits — and two accumulation modes. In decaying mode the accumulation continuously fades so the heatmap reflects recent activity and stays responsive on live streams. In cumulative mode it accumulates from the start of the pipeline, which is best for analyzing a fixed recorded clip end to end.

This node requires an AI Model Node before it in order to function properly. The unique_visits metric additionally requires a Track Objects Node so that objects carry stable tracking ids.

Inputs & Outputs

Inputs : 1, Media Format : Raw Video
Outputs : 1, Media Format: Raw Video
Output Metadata : None

Properties

Property	Description	Type	Default	Required
`roi_labels`	Regions of interest labels	`string`	—	No
`rois`	Limit the heatmap to these regions. Leave blank to use the whole frame. 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 in the heatmap. Leave blank to include all.	model-labels	`null`	No
`metric`	What the heatmap shading represents. Options: Total dwell time (`dwell_time`): Total object-seconds spent in each area; Average occupancy (`avg_occupancy`): Time-weighted average number of objects per area; Occupancy % of time (`occupancy_pct`): Fraction of time each area had at least one object; Unique visits (`unique_visits`): Count of distinct objects that passed through each area.	`enum`	`dwell_time`	Yes
`accumulation_mode`	Decaying suits live streams; cumulative suits analyzing a fixed recorded clip. Options: Decaying window (`decaying`): Recent activity, older activity fades; Cumulative (`cumulative`): Accumulate from pipeline start.	`enum`	`decaying`	Yes
`window_seconds`	Half-life of the decaying window: activity this many seconds old is weighted half as much. Conditional on `accumulation_mode` being `decaying`. Unit: seconds.	`float`	`60.0`	Yes
`tracking_mode`	Point on each object's bounding box attributed to the heatmap. Bottom-center approximates floor position. Options: Bottom center (`bottom-center`); Centroid (`centroid`); Top center (`top-center`); Left center (`left-center`); Right center (`right-center`).	`enum`	`bottom-center`	No
`normalization`	Relative always shows high contrast; absolute keeps colors comparable over time. Options: Relative (`relative`): Auto-scale to the current hottest area; Absolute (`absolute`): Scale to a fixed maximum value.	`enum`	`relative`	No
`max_value`	Value mapped to the hottest color when normalization is Absolute (seconds, object count or percent depending on metric). Conditional on `normalization` being `absolute`.	`float`	`null`	Yes
`color_map`	Color map. Options: Turbo (`turbo`); Jet (`jet`); Hot (`hot`); Viridis (`viridis`).	`enum`	`turbo`	No
`opacity`	Blend strength of the heatmap over the video. Range: minimum `0.0`, maximum `1.0`. Step: `0.05`.	`float`	`0.5`	No
`min_display_threshold`	Hide areas whose normalized value is below this fraction (raw video shows through). Range: minimum `0.0`, maximum `1.0`. Step: `0.01`.	`float`	`0.05`	No
`smoothing`	Gaussian blur strength applied to the heatmap for smoother blobs. Range: minimum `0`, maximum `199`. Step: `1`.	`integer`	`24`	No
`grid_resolution`	Number of heatmap cells across the frame width. Height is derived from the aspect ratio. Range: minimum `4`.	`number`	`160`	No
`display_legend`	Display legend?	`bool`	`true`	No

Output Metadata

Node does not insert any output metadata; upstream metadata continues through the pipeline