Watch the full video tutorial · Watch the Short
Where did vehicles appear most often in a traffic video? A heatmap can turn a few seconds of bounding boxes into a picture that changes as the video plays. In this tutorial, we build one with Python, YOLO and OpenCV, and explain exactly what the colours represent.
The demonstration uses an AI-generated traffic scene. It is a small educational example, not a real traffic survey or a test of production accuracy.
What does this heatmap measure?
We divide the 1280 × 720 video into a 32 × 18 grid of 40 × 40 pixel cells. For each frame, a cell receives one point if its centre lies inside at least one accepted vehicle bounding box. It receives zero otherwise. We add the points across the frames.
This is detected box presence over frames. It is not the number of cars, the speed of a car, or a measurement of actual road occupancy. If two boxes overlap a cell centre in the same frame, that cell still receives only one point. A slowly moving or stationary vehicle can contribute to the same cell across many frames.
The source clip contains 241 frames at 24 frames per second. To keep colours comparable throughout the demonstration, the display uses a fixed scale from zero to 241 frames rather than stretching the range separately for every image. At any time, a value of 24 would mean the cell centre was covered by an accepted box in 24 processed frames; with every source frame processed, that corresponds to about one second of detected box presence in the video. The value is still a model-derived observation, not a confirmed physical occupancy.
From video to map
- Read the traffic clip one frame at a time.
- Run YOLOv8n with a confidence threshold of 0.20 and accept COCO vehicle classes car, motorcycle, bus and truck. This demonstration uses ByteTrack results.
- For every grid cell, check whether its centre falls inside any accepted vehicle box in the current frame.
- Add at most one to each cell for that frame, map the accumulated values to colours and draw the result over the video.
A fixed camera matters: a cell represents a position in the image, so camera movement makes the same grid cell cover different parts of the scene. If the camera moves, stabilise or otherwise account for that motion before interpreting a spatial map.
The core update
The complete program below reads a local video, runs the selected local YOLO model and writes an annotated MP4, three example frames, the grid as a NumPy array and a JSON summary. For another video, use a fixed camera and a compatible trained model; results will differ. The clip used in the demonstration is not offered as a download here.
The tested Windows/CPU environment used ultralytics 8.4.24, opencv-python 4.13.0.92, numpy 2.3.5, lap 0.5.13 and a CPU installation of PyTorch 2.10.0. See the official PyTorch installation selector for a suitable installation command. In an activated Python environment, the other tested packages can be installed with:
python -m pip install ultralytics==8.4.24 opencv-python==4.13.0.92 numpy==2.3.5 lap==0.5.13
The first run needs the appropriate local model file and tracker dependencies installed; this example does not assume a network connection will fetch missing files. Package compatibility depends on the Python version and platform.
Save the code as heatmap.py. Put your own video and a compatible local yolov8n.pt in the working directory, then run:
python heatmap.py --video your_video.mp4 --model yolov8n.pt --out traffic_heatmap.mp4
In model mode the script selects CPU, a 0.20 confidence threshold, a 640-pixel inference size, vehicle classes 2, 3, 5 and 7, and bytetrack.yaml. The optional --cache mode is for a previously generated compatible frame-by-frame JSON cache, not for an arbitrary JSON file. When no model is available locally, supply the required weights through a legitimate source and review their terms before use.
The following example uses Ultralytics; review the Ultralytics licensing terms for your use. The demonstration code is provided under AGPL-3.0, Copyright ARTSCI - Author of the AI/ML/CV course materials. The AI-generated video is not included under that code license.
Show the complete Python script
"""Build a 40px-grid vehicle detection-presence heatmap (not a vehicle counter).
Examples:
python heatmap.py --video input.mp4 --model yolov8n.pt --out result.mp4
python heatmap.py --video input.mp4 --cache tracks_cache.json --out result.mp4
The cache option requires an identical source-file SHA-256; model mode performs
local inference. For reproducible model mode, use the versions in README.md.
"""
import argparse
import hashlib
import json
from pathlib import Path
import cv2
import numpy as np
def sha256(path):
h = hashlib.sha256()
with open(path, 'rb') as stream:
for chunk in iter(lambda: stream.read(1024 * 1024), b''):
h.update(chunk)
return h.hexdigest()
def presence(boxes, w, h, grid=40):
"""One boolean per cell, true if its center is in any detection box."""
# An edge cell can be narrower than grid; its true center is halfway
# between its starting coordinate and the clipped image edge.
left = np.arange((w + grid - 1) // grid) * grid
top = np.arange((h + grid - 1) // grid) * grid
x = (left + np.minimum(left + grid, w)) / 2
y = (top + np.minimum(top + grid, h)) / 2
present = np.zeros((len(y), len(x)), dtype=bool)
for x1, y1, x2, y2 in boxes:
present |= ((y[:, None] >= y1) & (y[:, None] <= y2) &
(x[None, :] >= x1) & (x[None, :] <= x2))
return present
def main():
p = argparse.ArgumentParser(description=__doc__)
p.add_argument('--video', required=True)
mode = p.add_mutually_exclusive_group(required=True)
mode.add_argument('--cache', help='frame-indexed detections cached for this exact file')
mode.add_argument('--model', help='local Ultralytics YOLO .pt file')
p.add_argument('--out', default='traffic_heatmap.mp4')
p.add_argument('--grid', type=int, default=40)
p.add_argument('--confidence', type=float, default=0.20)
p.add_argument('--save-cache', help='save inference results as JSON')
args = p.parse_args()
if args.grid < 1 or not 0 <= args.confidence <= 1 or (args.cache and args.save_cache):
p.error('--save-cache requires --model, not --cache' if args.cache and args.save_cache else 'grid must be positive, confidence must be between 0 and 1')
cap = cv2.VideoCapture(args.video)
if not cap.isOpened():
raise RuntimeError('Could not open video')
w, h = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH)), int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
fps = float(cap.get(cv2.CAP_PROP_FPS))
total = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
if total < 1 or fps <= 0 or w % 2 or h % 2:
raise ValueError('Video must have a known frame count, positive FPS, and even width and height; resize or pad odd dimensions first.')
cache = None
if args.cache:
cache = json.loads(Path(args.cache).read_text(encoding='utf-8'))
if cache['key']['source_sha256'] != sha256(args.video):
raise ValueError('Cache source hash mismatch; rerun with --model')
if len(cache['rows']) != total or any(row['frame'] != i for i, row in enumerate(cache['rows'])):
raise ValueError('Cache frame count or order mismatch')
if cache['key']['conf'] != args.confidence or cache['key']['classes'] != [2, 3, 5, 7]:
raise ValueError('Cache parameters differ from expected settings')
rows = cache['rows']
else:
if not Path(args.model).is_file():
raise FileNotFoundError('Model must be an existing local file')
from ultralytics import YOLO
model = YOLO(args.model)
rows = []
out = cv2.VideoWriter(args.out, cv2.VideoWriter_fourcc(*'mp4v'), fps, (w, h))
if not out.isOpened():
raise RuntimeError('Could not open video writer')
heat = np.zeros(((h + args.grid - 1)//args.grid, (w + args.grid - 1)//args.grid), dtype=np.uint32)
counts = []
try:
for frame_id in range(total):
ok, frame = cap.read()
if not ok:
raise RuntimeError(f'Cannot decode frame {frame_id}/{total}')
if cache is not None:
detections = rows[frame_id]['detections']
boxes = [d['xyxy'] for d in detections]
else:
result = model.track(frame, persist=True, conf=args.confidence, classes=[2,3,5,7],
imgsz=640, tracker='bytetrack.yaml', device='cpu', verbose=False)[0]
# Pilot stores only detections with an assigned track ID, so match it.
boxes = result.boxes.xyxy.cpu().tolist() if result.boxes.id is not None else []
ids = result.boxes.id.int().cpu().tolist() if result.boxes.id is not None else []
classes = result.boxes.cls.int().cpu().tolist() if result.boxes.id is not None else []
confidences = result.boxes.conf.cpu().tolist() if result.boxes.id is not None else []
rows.append({'frame': frame_id, 'detections': [
{'id': tid, 'class': cl, 'conf': conf, 'xyxy': box}
for tid, cl, conf, box in zip(ids, classes, confidences, boxes)]})
heat += presence(boxes, w, h, args.grid)
counts.append(len(boxes))
# Absolute, fixed scale: 0 is zero frames, 255 is total video frames.
intensity = np.uint8(np.clip(heat.astype(np.float32) * 255 / total, 0, 255))
# Repeat cells exactly grid pixels and crop the partial edge cells.
intensity = np.repeat(np.repeat(intensity, args.grid, axis=0), args.grid, axis=1)[:h, :w]
present_mask = np.repeat(np.repeat(heat > 0, args.grid, axis=0), args.grid, axis=1)[:h, :w]
colour = cv2.applyColorMap(intensity, cv2.COLORMAP_TURBO)
# Alpha is based on the unquantized count: a single detected frame
# must remain visible even if 8-bit colour rounds its value to zero.
alpha = np.where(present_mask, 0.58, 0.0).astype(np.float32)[..., None]
view = np.uint8(frame * (1 - alpha) + colour * alpha)
for x1,y1,x2,y2 in boxes:
cv2.rectangle(view, (int(x1),int(y1)), (int(x2),int(y2)), (210,225,240), 1)
out.write(view)
if frame_id in (0, total//2, total-1):
cv2.imwrite(str(Path(args.out).with_name(f'heatmap_frame_{frame_id:03d}.png')), view)
finally:
out.release(); cap.release()
np.save(Path(args.out).with_name('final_counts.npy'), heat)
result = {'source_sha256': sha256(args.video), 'frames': total, 'fps': fps,
'size': [w,h], 'cell_px': args.grid, 'grid_shape': list(heat.shape),
'scale_min_frames': 0, 'scale_max_frames': total,
'maximum_cell_frames': int(heat.max()), 'nonzero_cells': int(np.count_nonzero(heat)),
'detections_total': int(sum(counts)), 'frames_with_detections': sum(c > 0 for c in counts),
'definition': 'number of frames whose cell center lies inside one or more tracked detection boxes'}
Path(args.out).with_name('heatmap_result.json').write_text(json.dumps(result, indent=2), encoding='utf-8')
if args.save_cache:
key = {'source_sha256': sha256(args.video), 'weights_sha256': sha256(args.model),
'conf': args.confidence, 'classes':[2,3,5,7], 'imgsz':640, 'tracker':'bytetrack.yaml'}
Path(args.save_cache).write_text(json.dumps({'key':key,'rows':rows}), encoding='utf-8')
print(json.dumps(result, indent=2))
if __name__ == '__main__':
main()
In this particular run, 263 of the 576 cells received at least one observation; the largest cell total was 201 of 241 frames. These describe the algorithm's detected boxes in this synthetic clip, not confirmed vehicle counts.
How to read the result responsibly
- Detections are estimates. Missed objects leave gaps and false positives can add heat where there was no vehicle.
- Box coverage is approximate. A rectangular box is not a segmentation mask, and testing only cell centres misses coverage that does not contain a centre.
- Time and sampling matter. Results change with the number of sampled frames, frame rate, clip length and how long a vehicle stays in a place. Do not compare raw totals from clips of different lengths without a defined normalization.
- Perspective matters. Equal-sized image cells do not necessarily represent equal areas on the road. A spatial calibration would be needed for meaningful real-world area or distance measurements.
- Tracker identities are not verified car counts. An ID can change or disappear. This grid deliberately records box presence per frame; it does not use unique IDs as a count.
For comparison, a line counter answers a different question: how often an observed track crosses a chosen line. See my related traffic-counter article and video walkthrough.
Frequently asked questions
Can this count unique cars?
No. A cell stores detected presence across frames. Counting unique physical cars needs a separate tracking and validation method, and ID changes can still cause errors.
Why can a parked vehicle create a higher-value region?
Because its detected box can cover the same cell centre in many successive frames. The map reflects accumulated observations, not automatically traffic volume.
Does a blank cell prove no vehicle was there?
No. The model may miss a vehicle, a bounding box may cover only part of the cell without covering its centre, or the vehicle may be outside the frame.
For more on the underlying tools, see the official Ultralytics tracking documentation and OpenCV colour maps. Ultralytics also documents a separate heatmap solution; its implementation is distinct from the grid rule explained here.
If you would like to study more Python, OpenCV and YOLO projects, explore my Computer Vision course on Udemy. This is my instructor referral link.





