Guardian AI - Accident Detection System

An AI-powered real-time accident detection system that analyzes video feeds using computer vision and machine learning to identify potential accidents and send instant alerts.

Live Demo: https://pabcal.github.io/accidentDetection-webpage/

---

Table of Contents

• Overview
• Technologies
• Project Structure
• Data Flow & Architecture
• Setup Instructions
• Usage
• Configuration
• Notes

---

Overview

This project combines a FastAPI backend with an HTML/JS frontend to create an intelligent accident detection system. Users upload video files, and the system processes them frame-by-frame using AI to detect accidents, display results in real-time, and send email alerts.

---

Technologies

Backend

Technology	Purpose
FastAPI	Modern Python web framework for building fast APIs
Python 3.8	Core programming language
OpenCV	Video processing and frame manipulation
Roboflow Inference	AI object detection model for accident detection
Uvicorn	ASGI server to run FastAPI
SendGrid	Email service for sending accident alerts
CORS Middleware	Enable frontend-backend communication

Frontend

Technology	Purpose
HTML5	Page structure and layout
CSS3	Modern styling with animations and gradients
JavaScript (ES6)	Interactive features and API communication
Font Awesome Icons	UI icons
Google Fonts	Typography (Inter, Sora)

Deployment

Service	Purpose
Render	Backend hosting (production)
Local Server	Frontend development server

---

Project Structure

AccidentDetection/
  backend/
    - main.py                    FastAPI application with video processing logic
    - requirements.txt           Python dependencies
    - runtime.txt                Python version specification
  frontend/
    - index.html                 Main webpage with upload form and live feed
    - script.js                  Client-side logic for file upload & API calls
    - styles.css                 Modern UI styling with animations
    - logo-placeholder.png       Brand logo
  test/
    - test_model.ipynb           Jupyter notebook for model testing
    - test.py                    Python test scripts
    - test/                      Test dataset with images and labels
  run.bat                        Automated startup script for Windows
  README.md                      This file

---

Data Flow & Architecture

User Interaction Flow

1. USER (Browser)

   • Navigate to http://localhost:8080
   • Select video file
   • Enter email address
   • Click "Upload & Analyze"

2. FORM DATA SENT TO FRONTEND (JavaScript)

   • Validate inputs
   • Send POST request to API_BASE_URL/upload_video/
   • Display video stream

3. BACKEND (FastAPI) - /upload_video/ endpoint

   • Receive video file
   • Store temporary file
   • Save email address

4. VIDEO PROCESSING (process_video function)

   • Open video with OpenCV
   • Loop through each frame
   • Run AI inference on frame
   • Draw bounding boxes
   • Encode frame as JPEG
   • Check for accidents

5. DUAL OUTPUT PATHS: Path A: JPEG Stream -> /video_feed/ endpoint -> Returns MJPEG stream -> Frontend Display Path B: Accident Detected -> SendGrid Email Service -> Send alert to email

6. FRONTEND DISPLAY

   • Show live video feed
   • Display detections

AI Detection Process (Per Frame)

1. Video Frame (MP4) loaded
2. OpenCV reads frame
3. Resize/Preprocess
4. Roboflow AI Model processes (YOLOv8-based object detection)
5. Detection Results returned:
   • Class: "accident"
   • Confidence: 0.7+
   • Bounding Box (x, y, w, h)
   • Location (x_center, y_center)
6. Draw Results on Frame:
   • Red rectangle around accident
   • Text label "accident"
7. Encode as JPEG
8. Stream to Frontend

---

Setup Instructions

Option 1: Automated Setup (Recommended)

Simp run the batch file on Windows:

./run.bat

This script automatically:

• Creates a Python virtual environment
• Installs all dependencies
• Starts the FastAPI backend (port 8000)
• Starts the frontend server (port 8080)
• Opens the application in your browser

Option 2: Manual Setup

Step 1: Create and activate a virtual environment

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate

Step 2: Install dependencies

pip install -r backend/requirements.txt

Step 3: Configure environment variables

Create a .env file in the project root:

SENDGRID_API_KEY=your_sendgrid_api_key_here
ROBOFLOW_API_KEY=your_roboflow_api_key_here

Step 4: Start the backend

cd backend
uvicorn main:app --reload --host 127.0.0.1 --port 8000

Backend available at http://127.0.0.1:8000

Step 5: Start the frontend

In a new terminal:

cd frontend
python -m http.server 8080

Frontend available at http://localhost:8080

---

Usage

1. Open Frontend: Navigate to http://localhost:8080 in your browser
2. Upload Video:
   • Click "Choose Video File" to select an MP4/AVI/MOV video
   • Enter your email address (for accident alerts)
3. Analyze: Click "Upload & Analyze"
4. View Results: Watch the live feed with AI detections in real-time
5. Get Alert: If an accident is detected, you'll receive an email notification

Supported Video Formats

• MP4 (.mp4)
• AVI (.avi)
• MOV (.mov)
• Other OpenCV-compatible formats

---

Configuration

Backend Settings (backend/main.py)

# Roboflow Model Configuration
model_name = "amazon-accident-detection-o3juo"
model_version = "3"
api_key = "ktSFVMakkE69oahKbqtv"

# Detection Thresholds
confidence = 0.7           # Minimum confidence score
iou_threshold = 0.5        # Intersection over Union threshold

# Email Notifications
sendgrid_api = os.getenv("SENDGRID_API_KEY")  # Load from environment

API Endpoints

Endpoint	Method	Purpose
/	GET	Serves HTML homepage
/upload_video/	POST	Upload video and get live feed
/video_feed/	GET	Stream processed video frames (MJPEG)

Frontend Configuration (frontend/script.js)

// Switch between local and production backend
const API_BASE_URL = 'https://accidentdetection-lx68.onrender.com';  // Production
// const API_BASE_URL = 'http://localhost:8000';                      // Local

---

Notes & Best Practices

• Ensure the backend is running before opening the frontend
• Configure your SendGrid API key in environment variables (not in code)
• Test with short video clips first (1-5 minutes)
• Use high-quality videos for better detection accuracy
• The system processes frames sequentially; larger videos take longer
• API keys should never be hardcoded in production—use environment variables
• Ensure your email is valid to receive accident alerts
• Supported video formats typically include MP4, AVI, and MOV

---

Security Recommendations

1. Move API Keys to Environment Variables:

   api_key = os.getenv("ROBOFLOW_API_KEY")
   sendgrid_api = os.getenv("SENDGRID_API_KEY")

2. Set CORS Origins in Production:

   allow_origins=["https://yourdomain.com"]  # Not ["*"]

3. Add Input Validation:

   • Limit video file size
   • Validate email format
   • Check video duration

---

Links

• Project Presentation: https://www.canva.com/design/DAG0kESyWoI/5ki-OR62UBf0bw39edvZ-A/edit