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:

1. Frontend sends images/videos to the backend
2. Backend processes them using AI models
3. AI Models detect weapons and return coordinates
4. Database stores detection results and analytics
5. 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:

1. Python 3.8+ installed
2. PostgreSQL database
3. 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:

1. Check Logs: Flask provides detailed error messages
2. Test Endpoints: Use test_api.py to verify functionality
3. Database Inspection: Use PostgreSQL client to check data
4. Model Validation: Test YOLO model independently
5. 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:

1. Set up the project locally
2. Test the API endpoints
3. Understand the database structure
4. Experiment with different images

For ML/CV Engineers:

1. Analyze model performance
2. Consider custom training data
3. Implement performance optimizations
4. Add new detection classes

For Full-Stack Developers:

1. Build a frontend interface
2. Implement real-time detection
3. Add user authentication
4. Deploy to production

---

📚 Additional Resources

• YOLO Documentation
• Flask Documentation
• OpenCV Tutorials
• PostgreSQL Guide
• Computer Vision Basics

---

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.