vigilar/docs/architecture/subsystems/detection.md

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.