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

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:

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

Response:

{
  "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:

{
    "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

// 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

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

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