feat: initial implementation of People Counter web app

- Add Flask application with MJPEG video streaming
- Implement OpenCV DNN face detection module
- Add zone-based entry/exit tracking with cooldown mechanism
- Create web interface with real-time WebSocket updates
- Add model download script and comprehensive README
- Include OpenCV DNN model files for face detection

README.md

@@ -0,0 +1,123 @@
+# 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.