AI_surveillance: The Tiny Geometry Trick That Turns Detections Into Security Events

A multi-service entrance monitor that goes beyond bounding boxes, using line-crossing state, snapshot evidence, and delayed notifications to convert vision into actionable alerts.

8 min read • View on GitHub • More from narendra-simha-pampati

A narrow security corridor with a single boundary line across the floor. A person approaches from one side while a stamped alert card, a snapshot thumbnail, and a message icon emerge from a control panel nearby. The scene explains how a detection becomes an operational event only after it crosses a rule boundary. — The project’s core trick is not seeing people. It is deciding when a person has crossed from observation into action.

Key Takeaways

AI_surveillance is interesting because it turns raw detections into events with memory, geometry, and alert logic.
The line-crossing system is the real product, because hysteresis and state tracking remove flicker at the boundary.
The split between FastAPI inference and Node.js orchestration keeps vision isolated from notifications and dashboard load.
The repo is best read as a clean educational prototype, not a full surveillance platform.

Most surveillance demos stop at boxes. This repo goes one step further and asks a better question: did anything actually happen? That shift matters because a camera feed becomes useful only when it can separate routine movement from an event worth waking a human for.

From boxes to events

The system starts with standard computer vision: YOLOv8 detects people and a few carried objects, then ByteTrack keeps identities stable across frames. The important part is what happens after detection. Instead of treating every frame as independent, the backend remembers where each person is relative to a monitored line and turns a crossing into an alert-worthy state change.

A close-up of a person’s path relative to a diagonal boundary line. Several recent positions cluster near the boundary inside a small buffer zone, showing that the system waits for stability before calling the crossing an entry or exit. The image explains how hysteresis prevents false alerts when a person hovers on the threshold. — The boundary logic is simple, but the state around it is not. That is what makes the alerts dependable.

The boundary line is the real product

The clever part lives in the state logic. A side-of-line test, usually expressed with a small cross-product calculation, tells the server which side of the boundary a person is on. Then a history map and stability counters stop the system from flip-flopping when someone lingers near the threshold.

// Conceptual shape of the logic
function lineSide(ax, ay, bx, by, px, py) {
  return (bx - ax) * (py - ay) - (by - ay) * (px - ax);
}

if (Math.abs(sideDistance) < LINE_HYSTERESIS_MARGIN) {
  stabilityCounter += 1;
}

if (stabilityCounter >= SIDE_STABILITY_FRAMES) {
  userStateMap.set(personId, 'Entered');
}

The architecture is intentionally split. Python handles inference, Node handles state and alerts, and the dashboard only listens to the event stream.

Why the repo splits vision from everything else

That separation is doing real work. The Python FastAPI service stays focused on inference, while the Node backend owns business rules, alert history, and notifications. In practice, that means the expensive parts of computer vision do not get tangled up with the slower parts of email delivery, WhatsApp integration, or dashboard traffic.

It is also a scaling choice. If the dashboard gets busy, the model service does not have to care. If inference spikes, the notification code still remains insulated. For a small project, that is a mature design instinct.

Snapshots are evidence, not decoration

The snapshot pipeline makes the system feel like security software instead of a demo. When an alert fires, the server captures the relevant frame, overlays the bounding box, and writes the image to disk for later review. The important detail is that this happens through a scheduled, non-blocking path, so evidence gathering does not stall the rest of the alert loop.

That matters because human operators do not need another live box. They need proof. A snapshot attached to the event makes the alert inspectable, forwards it cleanly to email, and gives the system a small but critical memory of what triggered the warning.

Notifications are the last mile

The notification layer closes the loop. HTML email, inline image attachments, and WhatsApp delivery turn a backend event into something a person can act on immediately. The repo is not just classifying movement. It is packaging an event for response.

That last mile is where many computer vision projects weaken. They can detect, but they do not deliver. Here, the delivery path is part of the product, not an afterthought.

What this repo gets right, and what mature platforms still do better

Against Frigate, Viseron, and DeepCamera, this project is smaller, simpler, and much less complete. That is not a flaw if the goal is to understand the mechanics of event creation. It is a flaw if the goal is to replace a full surveillance platform.

Project	Scope	Event logic	Integrations	Architecture	Best for
AI_surveillance	Demo to early prototype	Line-crossing state and basic behavior tracking	Email, WhatsApp, dashboard	Python inference plus Node orchestration	Learning the core pattern
Frigate	Full NVR platform	Mature detection and automations	Home Assistant, NVR workflows	Integrated platform	Production self-hosters
Viseron	Self-hosted AI NVR	Detection plus automation	Local monitoring and add-ons	Platform-style stack	DIY builders who want control
DeepCamera	AI camera platform	Higher-level scene analysis	Broader security features	Expanded ecosystem	Teams wanting richer camera intelligence

The comparison is not really about winners. It is about abstraction. Frigate and Viseron sell a platform. AI_surveillance shows the smallest useful slice of the idea: geometry, state, snapshot, notification.

Who built it, and what that tells us

The public footprint is thin, which suggests this is closer to a learning-oriented build than a polished commercial system. That actually fits the code. The repository shows disciplined ideas, but not the polish or ecosystem depth of a mature product. In a way, that makes the architecture more interesting, because the core insight is visible without platform noise.