docs/PERSON_DETECTION_FEATURE.md

# 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