Halloween/halloween/instructions.md

# Modul `halloween/`

Hier liegt die erste Pi-WebUI. `run.py` im Projektstamm startet sie.

- `camera.py` liefert ein gemeinsames MJPEG-Bild für mehrere Betrachter.
  `--demo` erzeugt ausdrücklich gekennzeichnete Testbilder; echte Kamera
  läuft nur über Picamera2 auf dem Pi. Kamerafehler sichtbar melden.
- `controller.py` enthält bislang ausschließlich die simulierte
  Effekt-Zustandslogik. Stopp bleibt bis zum Rücksetzen bestehen; nach Start
  oder Rücksetzen muss erst der Bereich frei sein und dann ein neuer Trigger
  kommen. Beschädigte Einstellungen schalten auf `aus`.
- `web.py` bietet WebUI und API; `index.html` ist die Oberfläche. `run.py`
  bindet an `127.0.0.1`, Zugriff vom Laptop erfolgt per SSH-Tunnel.
  Für den vom Nutzer gewünschten direkten Heimnetzzugriff kann Uvicorn
  `halloween.web:create_app` als Factory auf `0.0.0.0:8000` starten;
  siehe `SOFTWARE.md`. `run.py` bleibt bei Loopback; systemd nutzt die
  beim Upload gewählte Bind-Adresse, initial Loopback.
- `event_store.py` verwaltet `data/events.sqlite3`. Erfolgreiche manuelle
  Testauslösungen werden als Ereignisse gespeichert; Profile besitzen
  Kennungen und können Ereignissen zugeordnet werden. Profil-Löschen entfernt
  die Zuordnung, nicht das Ereignis. Auto-Profile können Merkmalsvektoren
  aufnehmen und verfallen 30 Tage nach letzter Sichtung. Start, stündlicher
  Lauf und Lesezugriffe räumen abgelaufene Profile auf; die Kamera liefert
  derzeit noch keine Merkmalsvektoren.
- Automatische Profilzuordnung per Kamera ist ein neuer Nutzerwunsch, aber
  noch nicht implementiert. Eine künftige Erkennung muss Unsicherheit und
  mögliche Fehlzuordnungen sichtbar machen und am echten Pi geprüft werden.
- Der Header `X-Halloween-UI` ist nur eine einfache Schranke für
  Schreibaufrufe, kein echter Zugangsschutz. Der direkte Heimnetzzugriff ist
  auf Nutzerwunsch für den aktuellen Test ohne Login vorgesehen; öffentliche
  Internetfreigabe ist nicht beauftragt. Zugangsschutz bleibt offen.
- Laufzeitdaten liegen standardmäßig unter `data/` und werden weder
  hochgeladen noch in Git aufgenommen.
- Echte GPIO-/Aktorsteuerung erst nach geklärter Mechanik, Versorgung,
  sicherem Stopp und den Hardwaretests aus `PLAN.md` ergänzen.

Bei Änderungen an Zustandsübergängen oder Endpunkten die zugehörigen Tests
unter `tests/` und die Bedienhinweise in `SOFTWARE.md` prüfen.

## Personendetektion

- `detection.py` wertet den gemeinsamen Kamerastream mit OpenCV DNN/NanoDet aus.
  Optionales Modell und OpenCV fehlen im Demo-Grundsetup bewusst. Kein Download
  im Server; geprüfte Modellmetadaten in `nanodet-model.json`.
- Nur neue, zeitlich gültige Frames auswerten. Hintergrundinferenz hält keine
  UI-/Zustandssperre; separater Watchdog sperrt aktivierte Automatik nach zwei
  Sekunden ohne gültiges Ergebnis. Fehler verlangen bewusstes Rücksetzen.
- Linienüberquerung nutzt bestätigte flüchtige Tracks und Fußpunkte, Richtung,
  endliches Segment und 3-%-Hysterese. Gruppen verlangen freien Bereich und
  Sperrzeit; Konfigurations-/Controllerwechsel verwerfen alte Beobachtungen.
- `/api/detection` liefert synchrones Bild und Rahmen; `/api/detection/config`
  speichert normierte Geometrie und Aktivierung unter `data/`. Erste Aktivierung
  ist bewusst, nach Neustart immer neue Bereichsfreigabe. UI zeichnet/editiert
  mit Canvas; keine Tracking-ID als Besucherprofil verwenden.
- Automatische Ereignisse tragen `person_line_crossing`, ohne Profilzuordnung.
  Die vorhandene Steuerung bleibt ausschließlich simuliert.

## Bewegungs-Test

- `motion.py` bietet OpenCV-Optical-Flow im gewählten Bereich ohne Personenmodell.
  Zwei aufeinanderfolgende gerichtete Bewegungen entlang der Pfeilnormalen
  bestätigen einen Trigger; die Linie muss dabei nicht überquert werden.
- `method=motion_test` ausdrücklich als Test kennzeichnen; `person_line` bleibt
  der Default und die Migration für alte gespeicherte Konfigurationen/Clients.
  Beide Methoden speichern Geometrie/Aktivierung unter data/detection.json.
- Beim Test bedeutet Bereichsfreigabe zwei Sekunden Bildruhe, KEINE bestätigte
  Personenfreiheit. Zehn Sekunden Sperrzeit, Stopp, bewusster Reset und Watchdog
  beibehalten. Nach Konfigurations-/Controllerwechsel neue Bildbasis verlangen;
  veraltete Inferenzfehler und Resultate dürfen den neuen Modus nicht beeinflussen.
- Ereignisse getrennt als motion_direction_test, ohne Profile; mit Auslösebild
  gemäß den folgenden Bildregeln.
  Aktoren bleiben simuliert; keine Zusage für Außenbetrieb, Licht oder Kostüme.

- Kleine Nahbereichbewegung nicht durch einen prozentual großen Mindestanteil
  am gesamten Rechteck verwerfen; Schwellen mit kleinem/langsamem synthetischem
  Stimulus regressionsprüfen, Gegenrichtung/Lichtwechsel weiter ablehnen.
- Bewegungswerte enthalten flüchtige Bildänderung, Hinweis und bestätigte
  Frames. UI zeigt diese zur Diagnose und verwendet bei aktivierter Automatik
  deren Freigabe für die Bereitschaftsanzeige. Manuelles Bereich-frei ersetzt
  diese nicht; Sequenz, Stopp und Sperrzeit behalten ihren Vorrang.

## Auslösebilder

- Automatische akzeptierte Trigger speichern den grünen Bereich des auslösenden
  Frames als JPEG unter data/event-images/, ohne EXIF/Originalbild außerhalb
  des Rechtecks. Konfiguration beim Trigger kopieren; keine neuere Kameraaufnahme
  oder später geänderte Geometrie verwenden. Manuelle Tests speichern kein Bild.
- SQLite migriert image_filename; öffentlicher Abruf nur über Ereignis-ID und
  geprüfte generierte Dateinamen. Keine statische Freigabe des data/-Ordners.
  Ordner 0700, Dateien 0600; Bilder nicht cachen. Bildspeicherung/SQLite außerhalb
  des Detection-Locks, Fehler nutzen die bestehende Fehlersperre.
- Nutzerwahl: bis manuelle Löschung behalten. UI bietet Vorschau, Ansehen und
  bestätigtes Bildlöschen; Ereignis/Profilzuordnung bleiben bestehen. Löschen
  betrifft den aktiven Bestand, keine Upload-Sicherungen. Keine automatische
  Alterslöschung von Bildern und keine Änderung der Auto-Profil-Frist.