# People Counter Web App

A real-time web application that uses USB camera face detection to count people entering and leaving a room, with zone-based entry/exit tracking.

## Features

- Real-time face detection using OpenCV DNN face detector
- Zone-based entry/exit tracking (left zone = entry, right zone = exit)
- Live video streaming via MJPEG
- Real-time count updates via WebSocket
- Visual indicators for overpopulation warnings
- Clean, modern web interface

## Prerequisites

- Python 3.7 or higher
- USB camera connected to your computer
- Linux/Windows/macOS

## Installation

1. **Clone or download this repository**

2. **Install Python dependencies:**
   ```bash
   pip install -r requirements.txt
   ```

3. **Download the face detection model files:**
   ```bash
   python download_models.py
   ```
   
   This will download the required OpenCV DNN model files to the `models/` directory.
   
   **Note:** If the automatic download fails, you can manually download:
   - `deploy.prototxt` from: https://github.com/opencv/opencv/blob/master/samples/dnn/face_detector/deploy.prototxt
   - `res10_300x300_ssd_iter_140000.caffemodel` from: https://github.com/opencv/opencv_3rdparty/dnn_samples_face_detector_20170830/res10_300x300_ssd_iter_140000.caffemodel
   
   Place both files in the `models/` directory.

## Usage

1. **Make sure your USB camera is connected**

2. **Run the Flask application:**
   ```bash
   python app.py
   ```

3. **Open your web browser and navigate to:**
   ```
   http://localhost:5000
   ```

4. **The application will:**
   - Display live video feed from your camera
   - Detect faces in real-time
   - Count people entering (left zone) and exiting (right zone)
   - Display current occupancy and statistics
   - Show visual warnings when occupancy is high

## Configuration

You can modify the following settings in `app.py` and `camera.py`:

- **Camera index:** Change `camera_index=0` to use a different camera
- **Frame processing rate:** Adjust `process_every_n_frames` (default: 3) to balance performance and accuracy
- **Face detection confidence:** Modify `face_confidence` threshold (default: 0.5)
- **Zone boundaries:** Adjust `entry_zone_percent` and `exit_zone_percent` in `zone_tracker.py`
- **Cooldown period:** Change `cooldown_seconds` to prevent double-counting (default: 2.0 seconds)
- **Maximum occupancy:** Update `MAX_OCCUPANCY` in `static/js/main.js` for overpopulation warnings

## How It Works

1. **Camera Capture:** The camera module captures frames from your USB camera
2. **Face Detection:** OpenCV DNN detects faces in the video frames
3. **Zone Tracking:** The zone tracker determines which zone each face is in:
   - **Left 40%** = Entry zone (green)
   - **Right 40%** = Exit zone (red)
   - **Center 10%** = Buffer zone (ignored to prevent false counts)
4. **Counting Logic:** People are counted when they appear in entry/exit zones with a cooldown period to prevent double-counting
5. **Real-time Updates:** Counts are sent to the web interface via WebSocket for live updates

## Project Structure

```
PeopleCounter/
├── app.py                 # Flask main application
├── camera.py              # Camera capture wrapper
├── face_detector.py       # Face detection module
├── zone_tracker.py        # Zone-based tracking logic
├── download_models.py     # Script to download model files
├── requirements.txt       # Python dependencies
├── models/                # OpenCV DNN model files
│   ├── deploy.prototxt
│   └── res10_300x300_ssd_iter_140000.caffemodel
├── templates/
│   └── index.html         # Main web interface
└── static/
    ├── css/
    │   └── style.css      # Styling
    └── js/
        └── main.js        # Client-side JavaScript
```

## Troubleshooting

- **Camera not found:** Make sure your camera is connected and try changing the `camera_index` in `camera.py`
- **Model files missing:** Run `python download_models.py` to download required files
- **Slow performance:** Increase `process_every_n_frames` value or reduce video resolution
- **Double counting:** Increase the `cooldown_seconds` value in `zone_tracker.py`

## Security & Privacy

- All processing runs locally (no cloud storage)
- No face recognition - only detection (no personal identification)
- Video frames processed in memory, not stored
- Optional: You can modify the code to blur faces for display if privacy is a concern

## License

This project is open source and available for use and modification.