Installation Guide

Installation Guide

This takes about 20 to 30 minutes the first time, mostly because of downloads. After that it starts in seconds. Go step by step and don't skip the helmet model part.

Prerequisites

• Python 3.10 or newer. Grab it from python.org. Version 3.10.11 is a safe pick. Not 2.7. During install on Windows, tick "Add Python to PATH".
• A Windows or Linux laptop. A normal CPU is fine, and no GPU is needed.
• An internet connection for the first run only. YOLOv8n and the fast-alpr weights download automatically once.
• Optional: a webcam, or an Android phone with the "IP Webcam" app for the live demo.

Step-by-Step Setup

1. Open the project folder and create a virtual environment. Open a terminal inside the helmet_anpr folder and run:

   python -m venv venv
   venv\Scripts\activate

   On Linux or macOS, use source venv/bin/activate instead. You'll see (venv) at the start of the line once it's active.

2. Install the dependencies.

   pip install -r requirements.txt

   This pulls in Django, Ultralytics, fast-alpr, OpenCV, ReportLab, OpenPyXL and imageio-ffmpeg. It can take a few minutes, so let it finish.

3. Add the helmet model. This step is required. Download a pre-trained YOLOv8 helmet detection .pt file. Search "helmet detection yolov8" on Roboflow Universe (universe.roboflow.com) or on Hugging Face. Rename it and place it here:

   ml_models/helmet_best.pt

4. Match the class order. Look at the model card or its data.yaml to see which number means helmet. Then open config/settings.py and update:

   "HELMET_CLASS_NAMES": {
       0: "helmet",
       1: "no_helmet",
   },

   If your model has them the other way round, swap them. This one detail decides whether the project works correctly.

5. Set up the database and the admin login.

   python manage.py migrate
   python manage.py create_demo_admin

   That creates the user admin with password admin123. If you'd rather choose your own, run python manage.py createsuperuser.

6. Start the server.

   python manage.py runserver

   Open http://127.0.0.1:8000/ in your browser and log in.

Using Your Phone as the Camera

1. Install "IP Webcam" on your Android phone.
2. Connect the phone and laptop to the same Wi-Fi.
3. Tap "Start server" in the app and note the URL it shows, something like http://192.168.1.5:8080.
4. On the Live Detection page, pick "IP Camera / RTSP URL" and enter that URL with /video at the end, for example http://192.168.1.5:8080/video. Then click Start.

Common Issues

• "Helmet model not found" banner. The file isn't at ml_models/helmet_best.pt, or the name is slightly off (watch for helmet_best.pt.pt on Windows with hidden extensions). The app still runs, but helmet status shows as unknown until you fix it.
• Everyone is flagged as no helmet. Your class order is reversed. Swap 0 and 1 in HELMET_CLASS_NAMES.
• The webcam shows a black screen. Close Zoom, Teams, or anything else using the camera, then try webcam index 1 or 2 instead of 0.
• The IP camera won't connect. The phone and laptop are almost always on different networks, or the URL is missing /video.
• Very low FPS. Increase FRAME_SKIP or lower RESIZE_WIDTH in DETECTION_CONFIG.

How to Verify It's Working

1. Before opening the browser, run the command-line test on any traffic video:

   python scripts/test_pipeline.py path\to\traffic_video.mp4 --output scripts\test_output.avi

   Violations should print in the terminal, and an annotated video should be saved.
2. In the web app, upload a short clip on the upload page. The progress bar should move and the violation count should go up. At the end, the annotated output video should play right in the browser.
3. Open the violation history page. You should see rider and plate snapshots. Click one and download its E-Challan PDF.
4. Check the dashboard. The 7-day chart and the stat cards should now show your new violations.

If all four of those work, you're ready for your demo.