docs/ANOMALY_DETECTION_GUIDE.md

Anomaly Detection Model Integration Guide

Overview

The best.bin anomaly detection model has been successfully integrated into the NETRA webapp. This model detects unusual patterns and behaviors in video feeds in real-time.

Installation & Setup

1. Prerequisites

Ensure your environment has:

# Install required packages
pip install -r requirements.txt

Key dependencies:

• PyTorch 2.0+ (for model loading)
• TensorFlow 2.15+ (fallback)
• OpenCV with contrib modules
• NumPy

2. Model Location

Place the best.bin model file in one of these locations:

• ai_models/best.bin ✅ (Recommended)
• ai_models/anomaly_detection/best.bin
• NETRA/model/anomaly_detection.bin

The webapp will auto-detect and load the model from the first available location.

How It Works

Detection Flow

1. Frame Buffering: Collects 16 consecutive frames for temporal analysis
2. Preprocessing: Resizes to 224x224, normalizes to 0-1 range
3. Inference: Runs model on buffered frames
4. Scoring: Generates anomaly confidence score
5. Alert Generation: Creates alert if score exceeds threshold (default: 0.5)

Confidence Levels

• SAFE (0.0-0.5): Normal behavior, no alert
• LOW RISK (0.5-0.6): Minor anomaly detected
• MEDIUM RISK (0.6-0.8): Moderate anomaly detected
• HIGH RISK (0.8-1.0): Significant anomaly detected

Configuration

Adjusting Detection Sensitivity

Edit webapp/app.py in the load_models() method:

# Line ~155 - Modify threshold (0.0-1.0)
anomaly_model_path = next((p for p in anomaly_model_candidates if p.exists()), None)
if anomaly_model_path:
    # Lower threshold = more sensitive, more false positives
    # Higher threshold = less sensitive, fewer false positives
    self.models['anomaly'] = AnomalyDetector(
        model_path=str(anomaly_model_path),
        anomaly_threshold=0.5  # ← Adjust here (default: 0.5)
    )

Using GPU Acceleration

Enable GPU in NETRA/anomaly_detector.py:

# Change device parameter
anomaly_model = AnomalyDetector(
    model_path=str(anomaly_model_path),
    device='cuda'  # or 'cpu' for CPU-only
)

Monitoring & Debugging

Check if Model is Loaded

The Flask app startup will show:

[OK] Anomaly detection model loaded from: ai_models/best.bin

If not loaded:

[WARN] Anomaly detection model not loaded: missing model file

Real-time Monitoring

Open the webapp dashboard to see:

• Anomaly detection alerts in real-time
• Confidence scores per frame
• Alert history with timestamps

Logs

Check terminal output for:

• Model loading status
• Inference errors (if any)
• Frame processing details

API Reference

AnomalyDetection Result Object

{
    'is_anomaly': bool,           # True if anomaly detected
    'confidence': float,          # 0.0-1.0 confidence score
    'anomaly_score': float,       # Raw model output
    'alert_level': str,           # SAFE/LOW_RISK/MEDIUM_RISK/HIGH_RISK
    'description': str            # Human-readable message
}

Alert Format (from process_frame)

{
    'type': 'anomaly_detected',
    'severity': str,              # HIGH_RISK/MEDIUM_RISK/LOW_RISK
    'confidence': float,          # 0.0-1.0
    'message': str,               # Description
    'anomaly_score': float        # Raw score
}

Testing the Model

1. Test with Live Camera

# Start webapp
python webapp/app.py

# Navigate to http://localhost:5000/live-camera
# Watch for anomaly detection alerts

2. Test with Video File

# Upload a video file in webapp
# Go to http://localhost:5000/video-analysis
# Analyze the video
# Check for anomaly detection results

3. Direct Python Testing

from NETRA.anomaly_detector import AnomalyDetector
import cv2

# Load model
detector = AnomalyDetector('ai_models/best.bin')

# Process video
cap = cv2.VideoCapture('test_video.mp4')
while True:
    ret, frame = cap.read()
    if not ret:
        break

    result = detector.predict_frame(frame)
    if result:
        print(f"Anomaly: {result.is_anomaly}, Score: {result.anomaly_score}")

cap.release()

Performance Optimization

Reduce Processing Time

1. Skip frames: Process every Nth frame instead of all frames
2. Lower resolution: Use 168x168 instead of 224x224
3. GPU usage: Enable CUDA for faster inference
4. Batch processing: Process multiple frames simultaneously

Example modification in process_frame():

# Process every 2nd frame
if self.frame_index % 2 == 0:
    anomaly_result = anomaly_model.predict_frame(frame)

Troubleshooting

Issue	Solution
Model not loading	Check file path, ensure .bin file exists
Out of memory	Use CPU mode or reduce buffer size
Slow inference	Enable GPU acceleration or skip frames
False positives	Increase anomaly_threshold (0.5 → 0.7)
Missed detections	Decrease anomaly_threshold (0.5 → 0.3)

File Structure

NETRA_Project/
├── ai_models/
│   ├── best.bin                    ← Anomaly model
│   ├── object_detection/
│   ├── pose_detection/
│   └── wepan_detection/
├── NETRA/
│   ├── anomaly_detector.py         ← New detector class
│   ├── violence_detector.py
│   ├── yolo_detector.py
│   └── weapon_person_detector.py
└── webapp/
    ├── app.py                      ← Updated with integration
    ├── requirements.txt            ← Updated with torch
    └── ...

Integration Details

What Changed

1. ✅ New AnomalyDetector class in NETRA module
2. ✅ Model loading in ModelManager.load_models()
3. ✅ Frame processing in VideoProcessor.process_frame()
4. ✅ State reset in reset_session_state()
5. ✅ PyTorch dependency added to requirements

Backward Compatibility

• All existing detections continue to work
• Anomaly detection is additive (doesn't affect other models)
• Graceful fallback if model file is missing
• No breaking changes to API

Support & Extensions

Custom Anomaly Thresholds

You can modify the threshold per-session:

anomaly_model = model_manager.get_model('anomaly')
if anomaly_model:
    anomaly_model.anomaly_threshold = 0.6  # Adjust sensitivity

Custom Model Format

The AnomalyDetector supports:

• ✅ PyTorch (.bin, .pth)
• ✅ TensorFlow SavedModel format
• Can be extended for other formats

References

• PyTorch Model Saving: https://pytorch.org/docs/stable/generated/torch.save.html
• TensorFlow SavedModel: https://www.tensorflow.org/guide/saved_model
• Anomaly Detection Concepts: https://en.wikipedia.org/wiki/Anomaly_detection