Heatmap
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_visitsmetric 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 | Comma separated list of labels for each ROI. Ex floor, lobby | list | null | No |
rois | Semicolon separated Regions of interest that limit where the heatmap is accumulated and drawn. Must correspond to labels defined in roi_labels. Leave blank to use the whole frame. Format: R1x1,R1y1,R1x2,R1y2,R1x3,R1y3; R2x1,R2y1,... | polygon | null | No |
objects_to_track | Object types and classes to include in the heatmap. Accepts object labels defined in the AI model (e.g. car, person) and classifier attributes (e.g. car.red). Leave blank to include all. | model-label | null | No |
metric | What the heatmap shading represents. Options: dwell_time (total object-seconds spent in each area), avg_occupancy (time-weighted average number of objects in each area), occupancy_pct (fraction of time each area had at least one object present), unique_visits (count of distinct objects that passed through each area). | enum | "dwell_time" | Yes |
accumulation_mode | How activity is accumulated over time. Options: decaying (recent activity, older activity fades — suits live streams), cumulative (accumulate from pipeline start — suits a fixed recorded clip). | enum | "decaying" | Yes |
window_seconds | Half-life of the decaying window in seconds; activity this many seconds old is weighted half as much. Conditional on accumulation_mode = decaying. | float | 60.0 | Yes (when decaying) |
tracking_mode | Point on each object's bounding box attributed to the heatmap. Bottom-center approximates floor position. Options: bottom-center, centroid, top-center, left-center, right-center. | enum | "bottom-center" | No |
normalization | How the color scale is normalized. Options: relative (auto-scale to the current hottest area), 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 the metric). Conditional on normalization = absolute. | float | null | Yes (when absolute) |
color_map | Heatmap color scheme. Options: turbo, jet, hot, viridis. | enum | "turbo" | No |
opacity | Blend strength of the heatmap over the video. Min: 0.0, Max: 1.0. | slider-optional | 0.5 | No |
min_display_threshold | Hide areas whose normalized value is below this fraction (raw video shows through). Min: 0.0, Max: 1.0. | slider-optional | 0.05 | No |
smoothing | Gaussian blur strength applied to the heatmap for smoother blobs. Min: 0, Max: 199. | slider | 24 | No |
grid_resolution | Number of heatmap cells across the frame width; height is derived from the aspect ratio. Min: 4. | number | 160 | No |
display_legend | Controls whether a color scale legend is drawn on the frame. | bool | true | No |