Halloween/README.md

# Halloween: interaktives atmendes Grab

Raspberry-Pi-Projekt für eine Halloween-Grabattrappe mit Kamera,
Weboberfläche und geplantem Effektablauf.

## Konzeptvideo

[![Vorschauvideo öffnen: simuliertes Scanner-Gruppenfoto](preview/v4/scanner_group_photo_end.png)](preview/v4/halloween_scanner_group_photo.mp4)

**▶ Auf das Vorschaubild klicken, um die Videoseite zu öffnen.**

[**Vorschauvideo mit Scanner und Gruppenfoto ansehen / herunterladen**](preview/v4/halloween_scanner_group_photo.mp4)

23 Sekunden · MP4 mit Ton · ca. 3,5 MB. Die Blender-Vorschau und die
Scan-Einblendungen sind Simulationen; sie zeigen keine echte Personenerkennung
oder geprüfte Mechanik. Das Video liegt im privaten Repository und erfordert
entsprechende Zugriffsrechte.

## Aufbau in Bildern

Die Bilder geben einen kompakten Überblick über den Aufbau.
**Zum Vergrößern auf das jeweilige Foto klicken.**

| Raspberry Pi 5 | PCA9685 · Servosteuerung | Servo- und Steueranschlüsse |
| :---: | :---: | :---: |
| [![Raspberry Pi 5 mit vier Steuerleitungen](RASPI_VERKABELT_DOKU.png)](RASPI_VERKABELT_DOKU.png) | [![PCA9685-Servosteuerung](PCA9685_DOKU.png)](PCA9685_DOKU.png) | [![Servo- und Steuerstecker am PCA9685](PCA9685_VERKABELT_DOKU.png)](PCA9685_VERKABELT_DOKU.png) |
| Ansicht mit vier Steuerleitungen. Pi-Pins und Kabelfarben stehen in der [Anschlussanleitung](VERDRAHTUNG.md). | Überblick über das Steuerungsmodul. Versorgung und Anschlussentwurf stehen in der [Verdrahtungsdokumentation](VERDRAHTUNG.md). | Detailansicht der Stecker. Erstprüfung und offene Hardwareprüfungen stehen in der [Aufbauanleitung](VERDRAHTUNG.md). |

**Bildhinweis:** Hintergrund und Darstellung sind KI-bearbeitet.
Die unveränderten Originale sind in der
**[bebilderten Aufbau- und Anschlussanleitung für Kamera und Schwenkarm](VERDRAHTUNG.md)**
verlinkt. Sie enthält außerdem Bauteile, Kabelfarben, Pi-Pins,
Servoversorgung und die Schritte zur Erstprüfung. Sie dokumentiert den
aktuellen Anschlussentwurf; offene Hardwareprüfungen sind dort gekennzeichnet.

## Software und aktueller Stand

Die erste Softwareversion bietet ein Picamera2-Livebild, einen Demo-Feed,
gespeicherte Moduswahl, einen simulierten Effektablauf sowie eine lokale
SQLite-Datenbank für Ereignisse und manuell zugeordnete Profile. Optional
erkennt NanoDet lokal Personen und löst beim Überqueren einer einstellbaren
Linie zum Grab hin automatisch den simulierten Effekt aus. Einrichtung und
Aktivierung stehen in [SOFTWARE.md](SOFTWARE.md#personenerkennung-und-linienauslösung).
Das echte Kamera-Livebild ist vom Nutzer bestätigt. Personenerkennung am Pi,
GPIO-Steuerung der Grabaktoren, Besucher-Wiedererkennung und Clip-Aufnahmen bleiben offen.
Der separate [Farbpunkt-Test](SOFTWARE.md#kamera-folgt-einem-farbpunkt) kann nach
bewusstem Start die beiden Kameraservos am PCA9685 bewegen; echte Hardwareprüfung steht aus.

Stand der Dokumentation: **16. Oktober 2026**. Die neue Grenzeneinstellung ist
lokal einschließlich Browserdemo geprüft; Upload und Prüfung dieser Version
an der echten Halterung stehen noch aus.

Die WebUI hat zwei Seiten: **Grab** (`/grab`, auch Startseite `/`) und
**Kamera / Finger** (`/kamera`), mit eigener Bedienung und gemeinsamem Livebild.
Die Oberfläche nutzt Schwarz/Blau mit dezenten statischen Leuchteffekten.
Auf breiten Bildschirmen stehen Bild und Steuerung nebeneinander. Detailwerte
sind aufklappbar; Endpunkte und Mittelstellung findest du unter
**Endpunkte & manuelle Einrichtung**. Auf kleinen Bildschirmen wird einspaltig angezeigt.
Grab-Stopp und Kamerastopp wirken auf ihren jeweiligen Bereich; **Alles stoppen**
beendet beide. Farbvorschau und Grabautomatik können parallel laufen; echte
Kamerabewegung erfordert ausgeschaltete Grabautomatik.

Auf **Kamera / Finger** lässt sich ein Farbpunkt im Beispielfoto auswählen.
Der Name bezeichnet keine automatische Erkennung eines unmarkierten Fingers.
Für die Servoeinrichtung ist kein Farbpunkt nötig: Richtungstaste halten,
vor dem Anschlag loslassen und die Position als Links/Rechts/Oben/Unten speichern.
**In Mittelstellung fahren** bringt beide Achsen im Einrichtmodus langsam zurück
zur gespeicherten Mitte; **Bewegung anhalten** bricht die Fahrt ab.
**Nachführtempo** ist separat einstellbar (40–800 µs/s). Als ersten schnelleren
Test 400 bei gestoppten Servos speichern; alte Konfigurationen behalten zunächst
80. Neue Kamera-Zielrate: 15 Bilder/s, tatsächliche Bild-/Auswertungsrate steht
über der Vorschau. Die Pi-API meldet am 16. Oktober 15 Bilder/s ohne aktive Nachführung.
Die optionale **Suche bei Punktverlust** ist lokal ergänzt: nach erster
Erkennung nur innerhalb der gespeicherten Bewegungsgrenzen suchen, bei Fund
weiter folgen; ohne Fund nach einem Durchlauf/spätestens 60 Sekunden anhalten
und auf denselben Punkt warten. Die gewählte Farbe bleibt dauerhaft gespeichert.
Unter **Farbe, Drehrichtung, Tempo und Suche einstellen** ausdrücklich aktivieren
und speichern. Upload und echter Suchtest stehen noch aus.

Die [Grenzeneinstellung](SOFTWARE.md#eindeutige-speicherung-der-endpositionen)
bietet zwei Bereiche pro Achse:

- **Bewegungsgrenzen** begrenzen die spätere Farbnachführung.
- **Einrichtbereich** begrenzt die Richtungstasten beim Ermitteln der Endpunkte.
  Er lässt sich bei gestoppten Servos schrittweise erweitern und speichern.

Standard: Nachführung 1400–1600 µs, Einrichtung 1100–1900 µs. Die technische
Eingabehülle 500–2500 µs ist kein bestätigter mechanischer Fahrweg. Beim bewussten Start fährt jede Achse
in die Mitte ihrer gespeicherten Bewegungsgrenzen: (Minimum + Maximum) / 2. Bestehende Einstellungen bleiben beim Update
erhalten; eine Kamerasitzung startet immer bewusst.

## Lokal ohne Hardware starten

```bash
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python run.py --demo
```

Danach `http://127.0.0.1:8000` öffnen. Das Bild ist synthetisch und als
Demo gekennzeichnet. `run.py` bindet ausschließlich an `127.0.0.1`.
Für den Zugriff auf einen Pi ist ein SSH-Tunnel vorgesehen; der alternative
manuelle Start für direkten Heimnetzzugriff steht in [SOFTWARE.md](SOFTWARE.md).

## Dokumentation

- [Verdrahtung von Kamera und Schwenkarm](VERDRAHTUNG.md) · [Anschlusszeichnung](VERDRAHTUNG.svg) · [Große Pi-Pinübersicht](RASPI_PINS.svg)
- [Software, Pi-Einrichtung und lokale Prüfungen](SOFTWARE.md)
- [Projektdateien auf den Pi übertragen](UPLOAD.md)
- [Arbeitsplan, Hardwarestand und offene Entscheidungen](PLAN.md)
- [Blender-Konzeptvorschau](preview/README.md)
- [Projektregeln](AGENTS.md)
- Modulanweisungen: [Software](halloween/instructions.md), [Tests](tests/instructions.md), [Werkzeuge](tools/instructions.md), [Vorschau](preview/instructions.md)

Code, Planung und bearbeitbare Blender-Szenen werden versioniert.
Laufzeitdaten unter `data/`, `.venv`, Referenzclips und gerenderte
Bilder/Videos bleiben lokal; ausgenommen ist das oben verlinkte Konzeptvideo.
Die Blender-Vorschau ist eine Simulation;
einige Schnittprojekte benötigen zusätzlich die lokal erzeugten Bildsequenzen.