diff --git a/README.md b/README.md index 06a821d..972af1f 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,10 @@ > This repo is a simple improvement/modification to https://www.pyimagesearch.com/2018/08/13/opencv-people-counter/ +
+ +

Live demo

+
- The primary aim is to use the project as a business perspective, ready to scale. - Use case: counting the number of people in the stores/buildings/shopping malls etc., in real-time. @@ -12,10 +16,113 @@ --- ## Table of Contents -* [Theory](#theory) +* [Simple Theory](#simple-theory) * [Running Inference](#running-inference) * [Features](#features) * [References](#references) * [Next Steps](#next-steps) -## Theory +## Simple Theory +**SSD detector:** +- We are using a SSD (Single Shot Detector) with a MobileNet architecture. In general, it only takes a single shot to detect whatever is in an image. That is, one for generating region proposals, one for detecting the object of each proposal. +- Compared to other 2 shot detectors like R-CNN, SSD is quite fast. +- MobileNet, as the name implies, is a DNN designed to run on resource constrained devices. For example, mobiles, ip cameras, scanners etc. +- Thus, SSD seasoned with a MobileNet should theoretically result in a faster, more efficient object detector. +--- +**Centroid tracker:** +- Centroid tracker is one of the most reliable trackers out there. +- To be straightforward, the centroid tracker computes the centroid of the bounding boxes. +- That is, the bounding boxes are (x, y) co-ordinates of the objects in an image. +- Once the co-ordinates are obtained by our SSD, the tracker computes the centroid (center) of the box. In other words, the center of an object. +- Then an unique ID is assigned to every particular object deteced, for tracking over the sequence of frames. + +## Running Inference +- Install all the required Python dependencies: +``` +pip install -r requirements.txt +``` +- To run inference on a test video file, head into the directory/use the command: +``` +python run.py --prototxt mobilenet_ssd/MobileNetSSD_deploy.prototxt --model mobilenet_ssd/MobileNetSSD_deploy.caffemodel --input videos/example_01.mp4 +``` +> To run inference on an IP camera: +- Setup your camera url in 'run.py': +```javascript +# the following is an ip camera url example +# just enter your camera url and it should work +url = 'http://191.138.0.100:8040/video' +vs = VideoStream(url).start() +``` +- Then run with the command: +``` +python run.py --prototxt mobilenet_ssd/MobileNetSSD_deploy.prototxt --model mobilenet_ssd/MobileNetSSD_deploy.caffemodel +``` + +## Features +The following are some of the added features. Note: You can easily on/off them in the config options at the start of 'run.py': + + +***1. Real-Time alert:*** +- If selected, we send an email alert in real-time. Use case: If the total number of people (say 30) exceeded in a store/building, we simply alert the staff. +- This is pretty useful considering the COVID-19 scenario. + + +- Note: To setup the sender email, please refer the instructions inside 'mylib/mailer.py' + +***2. Scheduler & Timer:*** +- Automatic scheduler to start the software. This is extremely useful in a business scenario, for instance, run it only at your desired time (9-5?). +- Stop running after a certain time, e.g., 30 min or 9 hours from now. +```javascript +##Runs at every day (9:00 am). You can change it. +schedule.every().day.at("9:00").do(run) +``` +```javascript +if Timer: + # Automatic timer to stop the live stream. Set to 8 hours (28800s). + t1 = time.time() + num_seconds=(t1-t0) + if num_seconds > 28800: + break +``` +***3. Simple log:*** +- Logs all data at end of the day. +- Useful for footfall analysis. + + +## References +***Main:*** +- SSD paper: https://arxiv.org/abs/1512.02325 +- MobileNet paper: https://arxiv.org/abs/1704.04861 +- Centroid tracker: https://www.pyimagesearch.com/2018/07/23/simple-object-tracking-with-opencv/ + +***Optional:*** +- https://towardsdatascience.com/review-ssd-single-shot-detector-object-detection-851a94607d11 +- https://pypi.org/project/schedule/ + +## Next steps +- Train the SSD on human data (with a top-down view). +- Experiment with other detectors and benchmark the results on computationally less expensive embedded hardware. +- Evaluate the performance on multiple IP cameras. + +

 

+ +--- + +## Thanks for the read & have fun! + +> To get started/contribute quickly (optional) ... + +- **Option 1** + - 🍴 Fork this repo and pull request! + +- **Option 2** + - 👯 Clone this repo: + ``` + $ git clone https://github.com/saimj7/People-Counting-in-Real-Time.git + ``` + +- **Roll it!** + +--- + +saimj7/ 18-08-2020 © Sai_Mj.