kamera geht

SOFTWARE.md

@@ -4,8 +4,9 @@ Diese Version implementiert ein Livebild des vorhandenen Camera Module 3 NoIR
 über Picamera2, eine lokale WebUI, Moduswahl mit Speicherung und eine
 **Simulation** des Effektablaufs. Sie steuert noch keine GPIOs, Motoren,
 Servos, Lampen oder Lautsprecher. Eine lokale SQLite-Datenbank speichert
-Testereignisse und Profilkennungen. Automatische Personenerkennung und
-Profilzuordnung per Kamera, Clips und Maskierung sind noch nicht umgesetzt.
+Testereignisse und Profilkennungen. Lokale Personenerkennung mit Linienauslösung ist implementiert, muss aber
+am Pi installiert und kalibriert werden. Profilzuordnung per Kamera, Clips
+und Maskierung sind noch nicht umgesetzt.
 Die 30-Tage-Löschung ist für künftige Auto-Profile vorbereitet. Daher vorerst nur
 im privaten Testbereich verwenden; die Kamera nicht auf öffentliche Flächen
 richten.
@@ -126,3 +127,106 @@ SSH-Tunnel und GPIOs müssen am echten Pi bzw. Aufstellort geprüft werden.
 
 Technische Grundlagen: [Picamera2-Handbuch](https://datasheets.raspberrypi.com/camera/picamera2-manual.pdf),
 [FastAPI-StreamingResponse](https://fastapi.tiangolo.com/advanced/stream-data/).
+
+## Personenerkennung und Linienauslösung
+
+Nach Übertragung des aktuellen Codes im Projektordner auf dem Pi installieren:
+
+```bash
+cd ~/halloween
+sudo apt update
+sudo apt install python3-opencv python3-numpy
+python3 -m venv --system-site-packages .venv
+.venv/bin/python -c "import cv2, numpy; print(cv2.__version__, cv2.__file__); print(numpy.__version__)"
+.venv/bin/python tools/install_detection_model.py
+```
+
+Das Skript lädt ausschließlich das unquantisierte Modell
+`object_detection_nanodet_2022nov.onnx` des offiziellen OpenCV Zoo.
+Version, URL, Größe und SHA-256 stehen in `halloween/nanodet-model.json`.
+Das Modell liegt unter `data/models/`; ein bestehendes korrektes Modell wird
+nicht erneut geladen. Download erfolgt nur auf diesen ausdrücklichen Aufruf,
+HTTPS-Zertifikatsprüfung bleibt aktiv. Der Server lädt nichts aus dem Internet.
+Bei abweichendem `HALLOWEEN_STATE_DIR` diesen beim Installer ebenfalls setzen
+oder `--state-dir` angeben. Modellgewichte bleiben unversioniert und werden
+nicht vom Upload überschrieben. Auf dem Pi das fertige Systempaket verwenden;
+Picamera2 bleibt ebenfalls das Raspberry-Pi-Systempaket. OpenCV muss mindestens
+4.10 sein; die tatsächliche installierte Version und Inferenz am Pi prüfen.
+Für andere Entwicklungsrechner kann `requirements-detection.txt` genutzt werden:
+Es erlaubt ausschließlich fertige Wheels und bricht ohne passende Pakete ab.
+Ein vorheriger pip-Installationsversuch kann lokale Pakete hinterlassen, die
+Systempakete überdecken; bei Importfehlern die ausgegebenen Pfade prüfen.
+
+Server anschließend wie oben starten. In der Liveansicht:
+
+1. Orange Linienendpunkte und die zwei grünen Bereichsecken ziehen. Die Linie
+   muss vollständig innerhalb des Rechtecks liegen. Außerhalb des privaten
+   Testbereichs darf die Auslösung nicht eingerichtet werden.
+2. Mit „Richtung umkehren“ den Pfeil zum Grab ausrichten.
+3. „Automatisch auslösen“ auswählen und „Linie und Bereich speichern“ drücken.
+4. Mindestens zwei Sekunden den gesamten Bereich freihalten. Danach auf der
+   Ankunftsseite beginnen und über die Linie zum Grab gehen.
+
+Zunächst bleibt die automatische Auslösung aus. Gespeicherte Konfiguration
+und Aktivierung bleiben nach normalem Neustart erhalten, aber die
+Bereichsfreigabe und Tracking-IDs werden immer neu aufgebaut. Bei ungültiger
+Konfiguration bleibt die Automatik aus; der Fehler wird angezeigt.
+
+Es werden nur Personen ausgewertet (Startschwelle 0,6). Mindestens drei
+aufeinanderfolgende Erkennungen bestätigen einen Track. Der Fußpunkt ist die
+Mitte der unteren Rahmenkante. Er muss von der Ankunftsseite über das endliche
+Liniensegment auf die Grabseite wechseln, jeweils mindestens 3 % der Bildhöhe
+von der Linie entfernt. Kurz auftauchende Personen hinter der Linie,
+Rückwege, Bewegung entlang der Linie und Überquerungen außerhalb des
+Segments lösen nichts aus. Verdeckung oder zu schnelles Überqueren kann
+zur Nichterkennung führen; die Startwerte sind praktisch zu kalibrieren.
+
+Eine Gruppe erhält einen Effekt: Nach Auslösung sind zehn Sekunden Sperrzeit
+und mindestens zwei Sekunden freier Auslösebereich nötig. Auch unbestätigte
+Personenrahmen im Rechteck verhindern die Freigabe. Überquerungen während
+Sperre werden verworfen. Start, Moduswechsel, Rücksetzen und Änderungen der
+Konfiguration verlangen erneut einen freien Bereich. Stopp bleibt wirksam;
+ein manueller Testbutton umgeht keine Fehlersperre.
+
+Kamera-/Modellfehler und mehr als zwei Sekunden ohne gültige Auswertung
+sperren die aktivierte Automatik und stoppen den simulierten Ablauf. Nach
+Beheben des Fehlers „Nach Stopp zurücksetzen“ verwenden und Bereich
+freihalten. Modellprobleme bei deaktivierter Automatik verhindern keine
+manuellen Tests. Demo braucht weder OpenCV noch Modell; ihre synthetischen
+Bilder sind kein Test der echten Personenerkennung.
+
+Die Auswertung arbeitet im Hintergrund mit dem jeweils neuesten Bild, Ziel
+fünf Auswertungen/s. Die UI zeigt die gemessene Verarbeitungsrate. Bei
+Erkennungsergebnissen zeigt sie das zugehörige Bild statt des unabhängigen
+MJPEG-Bildes, damit Rahmen und Bild zusammenpassen. Nach zwei Sekunden sind
+Ergebnisse veraltet und die Rahmen verschwinden. Ohne Erkennungsbild bleibt
+der normale MJPEG-Stream verfügbar. `/api/detection` liefert Frame-Nummer,
+JPEG als Base64, normierte Personenrahmen, flüchtige Tracking-IDs und Status;
+`GET/POST /api/detection/config` liest/speichert Aktivierung, Linie, Richtung
+und Rechteck. `POST` benötigt wie andere Schreibaufrufe `X-Halloween-UI: 1`.
+`/api/status` enthält zusätzlich `detection`. Der Header ersetzt keinen Login.
+
+Automatische Auslösungen werden als `person_line_crossing` ohne Profil in der
+bestehenden Datenbank gespeichert. Weder Kamerabilder noch Tracking-IDs werden
+automatisch gespeichert; Profil-Wiedererkennung und Altersentscheidung fehlen.
+Aktoren bleiben ausschließlich simuliert.
+
+### Abnahme am echten Pi (noch offen)
+
+- Angezeigte Rate und Reaktionsverzögerung prüfen; Livebild und Stopp müssen
+  bedienbar bleiben. Zehn Annäherungen und zehn Rückwege ausprobieren.
+- Gruppe, Verdeckung, Stehenbleiben, Linie entlanggehen, Neustart mit Person
+  im Bereich sowie Kamera-/Erkennungsausfall und bewusstes Rücksetzen testen.
+- Danach Kostüme, tatsächliche Dunkelheit und IR-Beleuchtung am Aufstellort
+  testen. Nachtbetrieb und Zuverlässigkeit sind noch nicht bestätigt.
+
+Modellgrundlage: [OpenCV Zoo NanoDet](https://github.com/opencv/opencv_zoo/tree/47534e27c9851bb1128ccc0102f1145e27f23f98/models/object_detection_nanodet).
+
+Optionaler echter Modell-Smoke-Test auf einem Rechner mit OpenCV und Modell:
+
+```bash
+HALLOWEEN_TEST_MODEL="$PWD/data/models/object_detection_nanodet_2022nov.onnx" .venv/bin/python -m unittest discover -s tests -v
+```
+
+Ohne diese Variable wird nur der optionale Modell-Smoke-Test übersprungen;
+die Linien-/API-/Installer-Tests benötigen weder Modell noch OpenCV.