Add restricted zone detection module and demo

README.md

@@ -121,6 +121,45 @@ occasionally hallucinates objects on plain background surfaces, reading a suppor
 detection quality on out-of-domain footage (camera angles, lighting, and compression that COCO's
 photos do not really cover) is visibly weaker than on COCO's own validation images.
 
+## Restricted Zone Detection
+
+<img src="assets/zone_demo.gif" alt="A marked polygon zone over a plaza walkway, with tracked people highlighted and a red ALERT banner firing when someone enters the zone" width="420">
+
+[Full-length video (20s, MP4)](assets/zone_demo.mp4)
+
+A small layer on top of the tracker: `src/objectmodel_v1/zones.py` defines a polygon in the same
+pixel coordinates as the tracked boxes, and fires an event only on the transition into or out of
+it, not on every frame a track spends inside. It keys off each box's bottom-center point (roughly
+where feet touch the ground) rather than the box centroid, since a zone drawn on a floor plane
+should care where someone is standing, not where their torso is.
+
+Correctness is checked on a synthetic sequence, not just eyeballed on video: a track walking
+through a rectangle produces exactly one `entered` and one `exited` event, none of the frames
+spent inside re-fire, a track that never enters never fires, and a fresh id gets independent
+state. That test lives with the module.
+
+On the same plaza clip used above, the zone above the walkway fired 91 enter/exit events over 20
+seconds. Read that number carefully: most of it is not 91 different real crossings. It is the
+same tracker id churn already described in the section above, the same person's track resetting
+and re-entering the zone as a "new" id, plus a handful of misclassified objects (a backpack or
+handbag read as its own tracked object) that shouldn't have triggered an event at all. The event
+mechanics are verified correct; the real-world event count is exactly as reliable as the
+underlying detector and tracker are, which right now is "usable for a demo, not for anything
+where a false alert has a real cost."
+
+```python
+from objectmodel_v1.zones import RestrictedZoneMonitor
+
+zone = [(300, 150), (650, 150), (650, 320), (300, 320)]  # pixel-space polygon
+monitor = RestrictedZoneMonitor(zone)
+
+for frame_index, frame in enumerate(video_frames):
+    boxes, labels, scores = detect(frame)
+    tracks = tracker.update(boxes, labels, scores)
+    for event in monitor.update(tracks, frame_index):
+        print(event.track_id, event.kind, event.position)  # "entered" or "exited"
+```
+
 ## Architecture
 
 ```text