# 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