Heatmaps Generation CNN

A real-time person traffic heatmap generator for retail and surveillance video. It detects and tracks people across video frames using YOLOv8 and DeepSORT, accumulates foot-traffic density into a Gaussian heatmap, and overlays it onto the original video. At the end of each run it produces a labeled 10×10 grid showing per-cell heat intensity as a percentage.

---

How It Works

1. Person Detection — YOLOv8n runs on every frame and returns bounding boxes for the person class.
2. Multi-Object Tracking — DeepSORT assigns persistent IDs to each detected person across frames using a MobileNetV2 appearance embedder.
3. Heat Accumulation — Each tracked person's foot position (bottom-center of bounding box) adds a 2D Gaussian blob to a float32 heatmap array.
4. Decay & Blur — The heatmap is multiplied by a decay factor and Gaussian-blurred every frame, so old traffic fades out over time.
5. Colorization & Overlay — The heatmap is normalized and colorized with the JET colormap, then blended onto the original frame (70% frame / 50% heatmap).
6. Grid Analysis — After processing, the frame is divided into a 10×10 grid. Each cell displays the average heat intensity as a 0–100% value.

---

Project Structure

Heatmaps-Generation-CNN/
├── main.py                      # Entry point — configure and run here
├── requirements.txt
├── heatmaps/
│   ├── __init__.py
│   ├── tracker.py               # PersonTracker — orchestrates the full pipeline
│   ├── heatmap_engine.py        # HeatmapEngine — Gaussian kernel, decay, colorize, overlay
│   ├── grid_visualizer.py       # Draws initial and final labeled grids
│   ├── file_manager.py          # Creates result/log files
│   ├── config.py                # All default parameter constants
│   └── model_utils.py
├── data/                        # Place input video files here (gitignored)
└── results/                     # All outputs are saved here (gitignored)

---

Setup

1. Clone the repository

git clone https://github.com/shanAweb/Heatmaps-Generation-CNN.git
cd Heatmaps-Generation-CNN

2. Create and activate a virtual environment

python3 -m venv hmenv
source hmenv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Place your video file in the data/ folder

data/
└── your_video.mp4

---

Running

Edit main.py to point to your video file and set your device, then run:

python main.py

main.py example

from heatmaps import PersonTracker

if __name__ == "__main__":
    tracker = PersonTracker(
        model_path="yolov8n.pt",
        device="cpu",           # Use "mps" for Apple Silicon, "cuda" for NVIDIA GPU
        kernel_size=100,
        sigma=30.0,
        decay_rate=0.98,
        heat_increment_value=350.0,
        max_absolute_heat_threshold=5.0,
    )
    tracker.detect_and_track("data/your_video.mp4", show=True)

Note: On first run, yolov8n.pt (~6 MB) is automatically downloaded from the Ultralytics model hub if it is not already present.

---

Configuration Parameters

Parameter	Default	Description
model_path	"yolov8n.pt"	Path to the YOLO model weights
device	"cuda"	Compute device: "cpu", "mps" (Apple Silicon), or "cuda"
conf	0.5	YOLO detection confidence threshold
iou	0.5	YOLO IoU threshold for NMS
kernel_size	100	Size (px) of the Gaussian heat blob per person
sigma	30.0	Spread of the Gaussian kernel — higher = wider blobs
decay_rate	0.98	Per-frame heatmap decay multiplier (1.0 = no decay)
heat_increment_value	350.0	Heat units added per tracked person per frame
max_absolute_heat_threshold	5.0	Heatmap value that maps to 100% (fully red)
result_dir	"results/"	Output directory for all saved files

---

Outputs

Every run saves the following files inside results/:

File	Description
output_with_heatmap.avi	Full processed video with heatmap overlay
initial_grid_<timestamp>.jpg	First frame with the labeled 10×10 reference grid
heatmap_grid_visual_<timestamp>.jpg	Final frame with heatmap overlay and per-cell heat % values
heatmap_grid_text_<timestamp>.txt	10×10 numerical grid data as plain text
<timestamp>.txt	Tracking log — records each new unique person ID as it appears
customer_count_summary_<timestamp>.txt	Total unique persons counted during the run

Example numerical grid output (heatmap_grid_text_*.txt)

numericalGridData: [
          [0.0, 0.0, 12.3, 45.1, 67.8, 55.2, 30.0, 5.1, 0.0, 0.0],
          [0.0, 3.2, 20.5, 78.9, 95.0, 88.4, 41.2, 8.7, 0.0, 0.0],
          ...
        ],

Each value is the average heat intensity for that cell as a percentage (0–100).

---

Device Guide

Your Machine	Recommended device setting
Mac with Apple Silicon (M1/M2/M3/M4)	"mps"
Mac with Intel CPU	"cpu"
Linux / Windows with NVIDIA GPU	"cuda"
Any machine (fallback)	"cpu"

---

Dependencies

Package	Purpose
ultralytics	YOLOv8 person detection
deep-sort-realtime	Multi-object tracking with persistent IDs
opencv-python	Video I/O, frame processing, visualization
torch	Deep learning backend for YOLO and DeepSORT embedder
numpy	Heatmap array operations
requests	Model weight downloads