Region Surveillance

Region entrance/exit monitoring with line-crossing detection, person tracking, and optional face recognition.

The Region Surveillance use case enables AI-driven monitoring of a defined spatial boundary using line-crossing analysis. It is designed for entry/exit tracking, controlled zone monitoring, and real-time event reporting for any camera feed or video source.

Overview

Region Surveillance tracks people as they cross a user-defined line within the camera scene. The system combines:

YOLOv8 person detection for robust people localization.
ByteTrack for persistent track IDs across frames.
Line-crossing logic to classify movement as entry or exit.
Face recognition caching for optional identity-aware events.
Reconnectable SSE streaming for live event updates.

Technologies Used

YOLOv8 for person detection.
ByteTrack for tracking persistent object IDs.
InsightFace for optional face recognition on recognized tracks.
LineCrossingTracker for region boundary analytics.
FastAPI for job control and event streaming.

Workflow

Define a region line by choosing two normalized points on the video frame.
Select an enter direction (enter_sign) to determine which side of the line counts as entry.
Start the surveillance job with the camera stream or recorded video source.
Track all persons crossing the line and label each crossing as ENTER or EXIT.
Stream events back to the UI using SSE and query recorded event history as needed.

Use Cases

Lobby access monitoring: Record entries/exits through a building entrance.
Restricted zone control: Watch a secure region for unauthorized crossing.
Gate flow analytics: Measure staff and visitor movement through checkpoint lines.
Identity-aware logging: Correlate line crossings with recognized individuals when face data is available.

Best Practices

Position the region line across the actual doorway, corridor, or zone boundary you want to monitor.
Use debounce_seconds to avoid duplicate events from jittery tracking.
Prefer a stable, overhead camera angle for clearer line-crossing detection.
Use identity caching only when you need recognized-person metadata on events.

Benefits

Real-time boundary monitoring for access control and safety.
Accurate entry/exit counts that support operational analytics.
Flexible source support for RTSP streams, video files, and webcams.
Event stream delivery for dashboard updates and alerting.