People Counter — Entry / Exit Detection Dashboard

A simple, real-world people counting system that uses a video (uploaded file or recorded camera footage) to detect people, track them across frames, and count how many crossed a virtual entry/exit line — all displayed live on a React dashboard.

Built to be beginner-friendly and easy to explain in a technical interview: no deep-learning frameworks, no database, no C++ — just OpenCV, Flask, and React.

---

Table of Contents

• Project Overview
• Real-World Use Case
• Features
• Technology Stack
• System Architecture
• How Person Detection Works
• How Tracking Works
• How Entry/Exit Counting Works
• Project Structure
• Installation
• Running the Backend
• Running the Frontend
• API Endpoints
• Testing
• Screenshots
• Future Improvements

---

Project Overview

You upload a video of people walking past a doorway, corridor, or gate. The backend processes the video frame by frame with OpenCV: it detects people, tracks each one across frames, and checks whether they crossed a horizontal "virtual line" drawn across the frame. Crossing the line one way counts as an Entry, crossing it the other way counts as an Exit. The frontend shows the live count and the final annotated video with bounding boxes, IDs, and the counting line burned in.

Real-World Use Case

This is the same basic idea used in:

• Retail stores — counting footfall in and out to measure conversion rate.
• Office buildings / co-working spaces — occupancy tracking for safety limits.
• Events and venues — real-time headcount for capacity management.
• Libraries, cafeterias, gyms — simple, camera-based attendance/occupancy tools.

Features

• Upload a video file directly from the browser.
• Detect people using OpenCV's built-in HOG + SVM pedestrian detector.
• Track each detected person across frames with a lightweight centroid tracker.
• Count Entries, Exits, and compute People Inside in real time.
• Draw bounding boxes, tracking IDs, and the virtual counting line onto the output video.
• Poll-based status updates (Ready → Processing → Completed / Error).
• Clean error handling for bad uploads, unsupported formats, and processing failures.
• Reset button to clear counts and start over.

Technology Stack

Frontend

• React 18 + TypeScript
• Vite (dev server + build tool)
• Axios (HTTP client)
• Plain CSS (no UI framework, kept simple on purpose)

Backend

• Python 3
• Flask (REST API)
• OpenCV (video I/O, detection, drawing)
• NumPy (numeric operations for the tracker)

No database is used — all state (counts, job status) lives in memory in the Flask process, and video files are stored on disk. No C++ code is written; OpenCV's Python bindings are used throughout.

System Architecture

Camera / Uploaded Video
        │
        ▼
   Python + OpenCV  (backend/video_processor.py)
        │
        ▼
   Person Detection   (backend/detector.py — HOG + SVM)
        │
        ▼
   Person Tracking    (backend/tracker.py — centroid tracker)
        │
        ▼
   Virtual Entry/Exit Line
        │
        ▼
   Entry / Exit Counting  (backend/counter.py)
        │
        ▼
   Flask REST API      (backend/app.py)
        │
        ▼
   React + TypeScript Dashboard (frontend/)

How Person Detection Works

backend/detector.py uses OpenCV's built-in HOG (Histogram of Oriented Gradients) + Linear SVM pedestrian detector — cv2.HOGDescriptor() with cv2.HOGDescriptor_getDefaultPeopleDetector(). This ships with every OpenCV install, so there's nothing extra to download or configure.

In plain terms: HOG looks at the pattern of edge directions in small blocks of the image (does the pattern of light/dark edges look like the outline of a walking person?). That pattern is fed into a linear SVM classifier that has already been trained to recognize the general shape of a standing or walking human. It's not a deep neural network — it's a classic, well-documented computer-vision technique that's easy to explain and reason about, which is why it fits the "keep it simple" requirement of this project.

Each detection returns a bounding box (x, y, w, h) around a detected person, with a confidence weight; low-confidence boxes are filtered out to reduce false positives.

How Tracking Works

backend/tracker.py implements a centroid tracker:

1. For every detected bounding box, compute its center point (centroid).
2. Compare new centroids to the centroids being tracked from the previous frame using simple Euclidean distance.
3. The closest match within a distance threshold is treated as the same person and keeps its ID.
4. Unmatched new centroids get a brand-new ID (a new person entered the frame).
5. Tracked people that aren't matched for several consecutive frames are removed (they left the frame, or detection missed them briefly).

This is intentionally simple — no Kalman filters, no deep-learning re-ID — a nearest-neighbour match is enough to track a handful of people moving through a doorway.

How Entry/Exit Counting Works

backend/counter.py keeps a virtual horizontal line at the middle of the frame (configurable). For every tracked person, it remembers which side of the line they were on the last time they were seen:

Above line → Below line   =  Entry
Below line → Above line   =  Exit

People Inside = Entry Count − Exit Count

Each crossing is tagged with the tracked person's unique ID plus the direction of that specific crossing, so the same person is never counted twice for the same crossing event even if their centroid jitters near the line for a few frames.

Project Structure

people-counter/
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── VideoUploader.tsx
│   │   │   ├── VideoViewer.tsx
│   │   │   ├── PeopleStats.tsx
│   │   │   ├── ControlButtons.tsx
│   │   │   └── StatusIndicator.tsx
│   │   ├── services/
│   │   │   └── api.ts
│   │   ├── types.ts
│   │   ├── App.tsx
│   │   ├── App.css
│   │   ├── index.css
│   │   └── main.tsx
│   ├── index.html
│   ├── package.json
│   ├── tsconfig.json
│   ├── tsconfig.app.json
│   ├── tsconfig.node.json
│   └── vite.config.ts
│
├── backend/
│   ├── app.py
│   ├── detector.py
│   ├── tracker.py
│   ├── counter.py
│   ├── video_processor.py
│   ├── uploads/        (uploaded videos land here; ignored by git)
│   ├── processed/      (annotated output videos; ignored by git)
│   └── requirements.txt
│
├── .gitignore
└── README.md

Installation

Prerequisites

• Python 3.9+
• Node.js 18+ and npm

Clone

git clone https://github.com/<your-username>/people-counter.git
cd people-counter

Backend setup

cd backend
python3 -m venv venv
source venv/bin/activate        # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Frontend setup

cd frontend
npm install

Running the Backend

cd backend
source venv/bin/activate        # if not already active
python3 app.py

The API starts on http://localhost:5000.

Running the Frontend

In a separate terminal:

cd frontend
npm run dev

The dashboard is available at http://localhost:5173. It talks to the Flask API at http://localhost:5000 by default — set VITE_API_BASE_URL in a frontend/.env file if you run the backend somewhere else.

Then in the browser:

1. Click Upload Video and choose a video file (.mp4, .avi, .mov, .mkv, or .webm).
2. Click Start to begin processing.
3. Watch the Status panel move from Processing to Completed.
4. The annotated video and live People Inside / Entered / Exited counts appear once done.
5. Click Reset to clear counts and process another video.

API Endpoints

Method	Endpoint	Description
GET	/health	Simple health check.
POST	/upload	Upload a video file (multipart/form-data, field video).
POST	/process	Start processing an uploaded video ({ "filename": "..." }).
GET	/status	Poll current status, progress, and live counts.
GET	/processed/<file>	Stream/download the processed output video.
POST	/reset	Reset counts and job state back to ready.

Example status response while processing:

{
  "status": "processing",
  "progress": 42,
  "errorMessage": null,
  "entryCount": 3,
  "exitCount": 1,
  "peopleInside": 2,
  "processedVideoReady": false
}

Testing

The pipeline was verified end-to-end during development:

• Unit-level: tracker.py + counter.py were exercised with synthetic centroid paths moving across the line in both directions, confirming correct entry/exit counting and no double-counting.
• Pipeline-level: video_processor.py was run against a generated test video to confirm detection → tracking → counting → annotated video output runs without errors and produces a valid .mp4.
• API-level: Every endpoint (/health, /upload, /process, /status, /processed/<file>, /reset) was exercised with curl, including error paths — empty upload, missing file, unsupported format, processing a video that doesn't exist, and downloading a missing processed file.
• Frontend: tsc -b type-checks cleanly and npm run build produces a working production bundle with no errors.

To reproduce the manual test flow yourself, run the backend and frontend as described above and upload any short .mp4 clip of people walking through a doorway or corridor — the more clearly a full body is visible, the more reliably the HOG detector will pick it up.

Screenshots

(Add screenshots of the dashboard here once you have real footage — e.g. docs/screenshot-dashboard.png, docs/screenshot-processing.png.)

Future Improvements

• Swap the HOG detector for a lightweight deep-learning detector (e.g. MobileNet-SSD or YOLO-tiny) for better accuracy in crowded or low-light scenes.
• Support live camera streaming (not just uploaded files) directly in the browser via WebRTC or MJPEG streaming instead of upload-then-process.
• Persist counts to a lightweight database for historical reporting and daily/weekly footfall charts.
• Add configurable counting-line position/orientation from the UI.
• Add authentication for multi-camera / multi-location deployments.