# 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.