# Person Detection Feature Guide

## Overview

The NETRA system now tracks and stores person detection data in the live camera feed. This feature automatically remembers person detection counts across camera sessions using SQLite database.

## What's New

### 1. **Live Camera Statistics Display**

Two new statistics fields have been added to the live camera monitoring interface:

- **👤 Person Detected**: Total count of unique persons detected in the current session
- **👁️ Person Present**: Real-time indicator showing if a person is currently in the frame (✅ Yes / ❌ No)

### 2. **Bounding Box Visualization** (v2.0)

Green bounding boxes now appear around detected persons:
- Real-time green rectangles around each person
- Confidence score displayed above box
- Coordinates stored in database with detection
- Enables precise person location tracking

### 3. **SQLite Database Storage**

A new `PersonDetection` model stores all person detection records with:

- User ID (tracks which user made the detection)
- Person count (number of people detected)
- Current presence status
- Detection confidence score
- **Bounding box coordinates** (x1, y1, x2, y2)
- Timestamp of detection
- Session date (for daily grouping)

### 4. **Data Persistence**

Person detection data is automatically saved to the database and persists across camera sessions, allowing you to:

- View detection history for the current day
- Track person detection patterns
- Review confidence scores and bounding boxes
- Analyze detection timeline with precise locations

## Database Schema

### PersonDetection Table

```sql
CREATE TABLE person_detection (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL FOREIGN KEY,
    person_count INTEGER DEFAULT 0,
    is_present BOOLEAN DEFAULT FALSE,
    confidence FLOAT DEFAULT 0.0,
    detection_details TEXT,
    detected_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    session_date DATE DEFAULT CURRENT_DATE
);
```

## API Endpoints

### 1. Save Person Detection

**Endpoint**: `/api/save-person-detection`
**Method**: `POST`
**Authentication**: Required (session must exist)

**Request Body**:

```json
{
  "person_count": 2,
  "is_present": true,
  "confidence": 0.95,
  "detection_details": "{...additional data...}"
}
```

**Response**:

```json
{
  "success": true,
  "message": "Person detection saved",
  "detection_id": 123
}
```

### 2. Get Person Detection History

**Endpoint**: `/api/person-detection-history`
**Method**: `GET`
**Authentication**: Required (session must exist)

**Response**:

```json
{
    "success": true,
    "data": {
        "total_detections": 5,
        "currently_present": true,
        "latest_confidence": 0.95,
        "detection_count": 12,
        "detection_records": [
            {
                "id": 1,
                "person_count": 1,
                "is_present": true,
                "confidence": 0.92,
                "detected_at": "2026-05-02T14:30:45.123456"
            },
            ...
        ]
    }
}
```

## How It Works

### Initialization

1. When camera starts, the system loads previous person detection data
2. `loadPersonDetectionHistory()` fetches today's detection records
3. Stats are populated from the database

### Detection Recording

1. As the camera processes frames, person detections are identified
2. When a person is detected, `recordPersonDetection()` is called
3. The detection count is incremented
4. Data is saved to database via `savePersonDetection()`

### Real-time Display

- **Person Detected**: Shows cumulative count of detections (increases with each new person)
- **Person Present**: Shows current status (updates in real-time based on latest detection)

## Integration with Existing Models

The person detection feature integrates with:

- **YOLO Object Detection**: Detects 'person' class objects
- **Pose Detection**: Uses person keypoints for presence validation
- **Weapon Detection**: Tracks persons carrying weapons

## JavaScript Functions

### Core Functions

- `loadPersonDetectionHistory()` - Loads previous detection data
- `savePersonDetection(count, isPresent, confidence)` - Saves new detection
- `updatePersonDetectionUI()` - Updates displayed statistics
- `recordPersonDetection(detectionData)` - Processes detection results
- `initializePersonDetection()` - Initializes system on camera start

### Usage Example

```javascript
// Load history on camera start
await initializePersonDetection();

// Record a person detection
recordPersonDetection({
  objects: [
    { label: "person", confidence: 0.95 },
    { label: "person", confidence: 0.92 },
  ],
});

// Update stats
updatePersonDetectionUI();
```

## Feature Benefits

✅ **Data Persistence**: Detection data survives browser refresh
✅ **Historical Tracking**: See all detections for the current day
✅ **Real-time Updates**: Live person presence indicator
✅ **Confidence Scoring**: Know how confident each detection is
✅ **User-Specific**: Each user has their own detection history
✅ **Date-Based Organization**: Data grouped by session date

## Future Enhancements

Possible improvements for this feature:

- Export detection history to CSV/PDF reports
- Visualize person detection trends over time
- Alert notifications when persons are detected
- Confidence threshold settings
- Multi-person tracking with ID persistence
- Heat mapping of person locations in frame

## Troubleshooting

### Data Not Saving

- Ensure user is logged in (authentication required)
- Check browser console for API errors
- Verify database connection in Flask app

### History Not Loading

- Data only loads for current day (session_date = today)
- Check if database has records for current user
- Clear browser cache and reload

### Stats Not Updating

- Verify `recordPersonDetection()` is being called
- Check that detection objects have 'person' label
- Ensure YOLO or other person detection model is selected

## Database Maintenance

### View All Person Detections

```python
from app import db, PersonDetection
detections = PersonDetection.query.all()
for d in detections:
    print(f"User {d.user_id}: {d.person_count} people at {d.detected_at}")
```

### Clear Old Records

```python
from datetime import datetime, timedelta
from app import db, PersonDetection

# Delete records older than 30 days
cutoff = datetime.utcnow() - timedelta(days=30)
PersonDetection.query.filter(PersonDetection.detected_at < cutoff).delete()
db.session.commit()
```

---

**Last Updated**: May 2, 2026
**Feature Version**: 1.0
**Status**: Production Ready