Crime Detection Backend: Complete Guide

🎯 What is This Project?

This is a weapon detection backend system that uses artificial intelligence to identify weapons in images and videos. Think of it as a smart security system that can automatically spot dangerous objects like guns or knives in camera footage.

Real-World Applications:

Security Cameras: Automatically alert security when weapons are detected
Public Safety: Monitor crowded areas like airports, schools, or events
Smart Surveillance: Reduce the need for human monitoring 24/7

🏗️ Architecture Overview

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Database      │
│   (React/Web)   │◄──►│   (Flask API)   │◄──►│   (PostgreSQL)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │   AI Models     │
                       │   (YOLO + LLM)  │
                       └─────────────────┘

How It Works:

Frontend sends images/videos to the backend
Backend processes them using AI models
AI Models detect weapons and return coordinates
Database stores detection results and analytics
Backend sends results back to frontend with bounding box coordinates

🛠️ Technology Stack

Backend Technologies:

Flask: Web framework (like the foundation of a house)
YOLO (YOLOv8): AI model for object detection
OpenCV: Computer vision library for image processing
PostgreSQL: Database for storing data
Ollama: Local AI service for additional intelligence

Python Libraries:

ultralytics: YOLO model implementation
opencv-python: Image and video processing
Flask-SQLAlchemy: Database management
numpy: Mathematical operations
Pillow: Image handling

📁 File Structure

crime-server/
├── 📄 app.py                          # Main application file
├── 📄 models.py                       # Database table definitions
├── 📄 config.py                       # Configuration settings
├── 📄 ollama_service.py               # AI chat service
├── 📄 requirements.txt                # Python dependencies
├── 📄 schema.sql                      # Database setup
├── 📁 model/
│   └── 📄 best.pt                     # Trained YOLO model
├── 📁 .venv/                          # Virtual environment
├── 📄 .env                            # Environment variables
├── 📄 README.md                       # Project documentation
├── 📄 COMPLETE_CODE_EXPLANATION.md    # Detailed code explanation
├── 📄 BOUNDING_BOX_IMPLEMENTATION.md  # Bounding box guide
└── 📄 test_api.py                     # API testing script

Key Files Explained:

🔧 `app.py` (The Heart)

Contains all API endpoints
Handles weapon detection logic
Manages database operations
Processes images and videos

🗃️ `models.py` (Database Structure)

Defines what data we store
Creates database tables
Sets up relationships between data

⚙️ `config.py` (Settings)

Database connection settings
File upload configurations
Security settings

🤖 `ollama_service.py` (AI Chat)

Connects to local AI for intelligent responses
Analyzes detection results
Provides context about detected weapons

🔄 How the System Works

Step-by-Step Process:

1. Initialization (When the server starts)

# Load the pre-trained YOLO model
model = YOLO('model/best.pt')
# Connect to database
# Start Flask application

2. Image Detection Process

User uploads image → Backend receives it → YOLO processes it → 
Detects weapons → Returns coordinates → Stores in database → 
Sends response to frontend

3. Video Detection Process

User uploads video → Backend splits into frames → 
Process each frame → Combine results → 
Return detection summary with timestamps

4. Response Format

{
    "success": true,
    "weapons_detected": true,
    "detections": [
        {
            "class": "gun",
            "confidence": 0.85,
            "bbox": [100, 50, 200, 150]  # [x1, y1, x2, y2]
        }
    ],
    "detection_count": 1
}

🌐 API Endpoints

📸 Image Detection

POST /detect-weapons-image

Purpose: Detect weapons in a single image
Input: Image file (JPG, PNG, etc.)
Output: Detection results with bounding boxes

🎥 Video Detection

POST /detect-weapons-video

Purpose: Detect weapons in video files
Input: Video file (MP4, AVI, etc.)
Output: Frame-by-frame detection results

📊 Analytics

GET /analytics

Purpose: Get detection statistics
Output: Total detections, weapon types, trends

🏥 Health Check

GET /health

Purpose: Check if the server is running
Output: System status

🤖 AI Chat

POST /chat

Purpose: Ask questions about detections
Input: Text question
Output: AI-generated response

📋 Detection History

GET /detections

Purpose: View past detection results
Output: List of previous detections

🗄️ Database Design

Tables:

📊 `DetectionResult`

Stores every weapon detection:

- id: Unique identifier
- filename: Name of processed file
- file_type: 'image' or 'video'
- weapons_detected: True/False
- detection_count: Number of weapons found
- confidence_scores: AI confidence levels
- timestamp: When detection occurred
- bounding_boxes: Weapon locations (JSON)

📈 `Analytics`

Stores summary statistics:

- id: Unique identifier
- date: Date of analytics
- total_detections: Daily detection count
- weapon_types: Types of weapons found
- average_confidence: Average AI confidence

🚀 Setting Up and Running

Prerequisites:

Python 3.8+ installed
PostgreSQL database
Git for version control

Step-by-Step Setup:

1. Clone and Navigate

git clone <repository-url>
cd crime-server

2. Create Virtual Environment

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac

3. Install Dependencies

pip install -r requirements.txt

4. Set Up Environment Variables

Create .env file:

DATABASE_URL=postgresql://username:password@localhost/crime_db
SECRET_KEY=your-secret-key
OLLAMA_BASE_URL=http://localhost:11434

5. Set Up Database

# Create database tables
python -c "from app import app, db; app.app_context().push(); db.create_all()"

6. Run the Server

python app.py

The server will start at http://localhost:5000

💻 Understanding the Code

🔍 Core Detection Function

def detect_weapons_in_image(image_path):
    """
    This function takes an image and finds weapons in it
    
    Steps:
    1. Load the image using OpenCV
    2. Run YOLO model on the image
    3. Filter results for weapons only
    4. Extract bounding box coordinates
    5. Return results with confidence scores
    """
    
    # Load and process image
    image = cv2.imread(image_path)
    
    # Run AI detection
    results = model(image)
    
    # Process results
    detections = []
    for result in results:
        for box in result.boxes:
            # Extract weapon information
            class_name = model.names[int(box.cls)]
            confidence = float(box.conf)
            bbox = box.xyxy[0].tolist()  # [x1, y1, x2, y2]
            
            detections.append({
                'class': class_name,
                'confidence': confidence,
                'bbox': bbox
            })
    
    return detections

🎯 Bounding Box Coordinates

What are bounding boxes?

Rectangular boxes that surround detected objects
Defined by 4 coordinates: [x1, y1, x2, y2]
(x1, y1): Top-left corner
(x2, y2): Bottom-right corner

Example:

bbox = [100, 50, 300, 200]
# This means:
# - Box starts at pixel (100, 50) from top-left
# - Box ends at pixel (300, 200)
# - Width: 300 - 100 = 200 pixels
# - Height: 200 - 50 = 150 pixels

👶 For Beginners: Key Concepts

🤖 What is AI/Machine Learning?

AI: Computer programs that can "think" and make decisions
Machine Learning: AI that learns from examples
YOLO: A specific AI model trained to find objects in pictures

🌐 What is an API?

API: Application Programming Interface
Think of it as a waiter in a restaurant:
- You (frontend) order food (send request)
- Waiter (API) takes order to kitchen (backend)
- Kitchen (AI model) prepares food (processes data)
- Waiter brings food back (returns results)

🗃️ What is a Database?

A organized storage system for data
Like a digital filing cabinet
Stores detection results, user data, statistics

🔧 What is Flask?

A Python framework for building web applications
Handles HTTP requests (when someone visits a webpage)
Routes requests to the right functions
Returns responses back to users

📦 What are Dependencies?

External code libraries that our project uses
Like ingredients in a recipe
Listed in requirements.txt
Installed using pip install

🎓 For ML/CV Engineers: Technical Details

🔬 Model Architecture

Base Model: YOLOv8 (You Only Look Once, version 8)
Custom Training: Fine-tuned on weapon detection dataset
Classes: Gun, knife, and other weapon categories
Input Size: 640x640 pixels (configurable)
Framework: Ultralytics implementation

🎯 Detection Pipeline

# 1. Preprocessing
image = cv2.imread(image_path)
image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

# 2. Inference
results = model(image_rgb)

# 3. Post-processing
for result in results:
    boxes = result.boxes
    if boxes is not None:
        # Non-maximum suppression already applied
        confidences = boxes.conf.cpu().numpy()
        class_ids = boxes.cls.cpu().numpy()
        bboxes = boxes.xyxy.cpu().numpy()

📊 Performance Considerations

Inference Time: ~50-100ms per image (depending on hardware)
Memory Usage: ~2GB VRAM for model loading
Batch Processing: Supported for multiple images
Video Processing: Frame-by-frame with temporal aggregation

🔄 Model Updates

Model file: model/best.pt
Easy to swap with retrained models
Maintains API compatibility
Version control recommended for model files

🏗️ Scalability

Horizontal Scaling: Multiple Flask instances behind load balancer
GPU Acceleration: CUDA support for faster inference
Caching: Redis for repeated detection results
Async Processing: Celery for background tasks

🐛 Troubleshooting

Common Issues:

1. Model Not Loading

Error: "No module named 'ultralytics'"
Solution: pip install ultralytics

2. Database Connection Error

Error: "could not connect to server"
Solution: Check DATABASE_URL in .env file

3. File Upload Issues

Error: "File too large"
Solution: Check UPLOAD_FOLDER and MAX_CONTENT_LENGTH settings

4. YOLO Model Error

Error: "Model file not found"
Solution: Ensure model/best.pt exists

5. Memory Issues

Error: "CUDA out of memory"
Solution: Reduce batch size or use CPU inference

🔧 Debugging Tips:

Check Logs: Flask provides detailed error messages
Test Endpoints: Use test_api.py to verify functionality
Database Inspection: Use PostgreSQL client to check data
Model Validation: Test YOLO model independently
Environment Check: Verify all environment variables

🎉 Conclusion

This weapon detection backend is a complete AI-powered system that:

✅ Detects weapons in images and videos using YOLO
✅ Returns bounding box coordinates for frontend visualization
✅ Stores detection results in a PostgreSQL database
✅ Provides analytics and detection history
✅ Includes AI chat for intelligent responses
✅ Offers comprehensive APIs for frontend integration

🎯 Next Steps:

For Beginners:

Set up the project locally
Test the API endpoints
Understand the database structure
Experiment with different images

For ML/CV Engineers:

Analyze model performance
Consider custom training data
Implement performance optimizations
Add new detection classes

For Full-Stack Developers:

Build a frontend interface
Implement real-time detection
Add user authentication
Deploy to production

📚 Additional Resources

This guide covers the complete codebase structure and functionality. For specific implementation details, refer to the individual markdown files and code comments throughout the project.

Table of Contents