From 67b8dd672c2dcf500681d73bec45a06b147b6bfb Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Sun, 5 Apr 2026 09:44:06 -0400 Subject: [PATCH] docs: add detection subsystem reference --- docs/architecture/subsystems/detection.md | 44 +++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 docs/architecture/subsystems/detection.md diff --git a/docs/architecture/subsystems/detection.md b/docs/architecture/subsystems/detection.md new file mode 100644 index 0000000..84ec56d --- /dev/null +++ b/docs/architecture/subsystems/detection.md @@ -0,0 +1,44 @@ +# detection + +## Purpose + +Library of computer-vision models and classifiers that the camera worker loads in-process. Provides YOLO/SSD object detection, pet identification, face recognition, wildlife threat scoring, package-delivery state machine, vehicle fingerprinting, activity heatmaps, and sunset-aware scheduling. It is not itself a supervised subsystem; there is no `detection` process and no direct MQTT involvement — the camera worker invokes these modules and publishes on their behalf. + +## Key files + +- `vigilar/detection/yolo.py` — YOLO object detector and category classifier (person/vehicle/pet/wildlife) +- `vigilar/detection/person.py` — MobileNet-SSD v2 detector for person/car/truck +- `vigilar/detection/pet_id.py` — MobileNetV3-Small pet identification classifier +- `vigilar/detection/trainer.py` — transfer-learning trainer for pet-ID model +- `vigilar/detection/face.py` — dlib/`face_recognition`-based face matcher against `face_profiles`/`face_embeddings` +- `vigilar/detection/wildlife.py` — wildlife species + threat-level classifier +- `vigilar/detection/package.py` — package-delivery state machine (`IDLE → PRESENT → REMINDED → COLLECTED`) +- `vigilar/detection/vehicle.py` — dominant-color and size fingerprinting for vehicles +- `vigilar/detection/zones.py` — polygon zones and intersection tests +- `vigilar/detection/heatmap.py` — accumulates detection bboxes into a grid for activity heatmaps +- `vigilar/detection/crop_manager.py` — saves detection crops into staging and training directories +- `vigilar/detection/solar.py` — stdlib NOAA sunset calculator for twilight-aware logic + +## MQTT topics + +**Subscribes:** none. Detection modules are library calls inside the camera worker. +**Publishes:** none directly. The camera worker publishes detection results on `vigilar/camera/{id}/motion/start` (person/vehicle, with an extra `detection` field), `vigilar/camera/{id}/pet/detected`, `vigilar/camera/{id}/wildlife/detected`, and `vigilar/pets/{pet_name}/location`. + +## Database tables + +No direct writes. `face.py` reads `face_profiles` and `face_embeddings` via `vigilar.storage.queries`. + +## Depends on + +- `storage` — `face.py` loads face profiles and embeddings +- `camera` — invoked as a library inside the camera worker process + +## Consumed by + +- `camera` — worker imports and calls these modules per frame +- `pets` — downstream consumer of pet-ID results (via MQTT topics published by camera) +- `events` — consumes the resulting detection topics off the bus + +## Notes + +Person and vehicle detections are piggybacked on `motion/start` rather than published on their own topics; the events processor currently collapses both back to `MOTION_START`. The package state machine in `package.py` is driven by the camera worker and uses `solar.get_sunset` to decide when a package has been "abandoned" after dusk.