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:

```bash

# 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:

```python

# 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`:

```python

# 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

```python

{

    '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)



```python

{

    '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

```python

# Start webapp

python webapp/app.py



# Navigate to http://localhost:5000/live-camera

# Watch for anomaly detection alerts

```

### 2. Test with Video File

```python

# 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

```python

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()`:

```python

# 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:

```python

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