vogelalbum/README.md

Vogelalbum

Eine Kamera am Vogelhaus, ein Rechner der erkennt wer da war — und eine Sammlung, die sich von allein füllt.

→ Live ansehen: vogelalbum.gaertner.onl

In English: Vogelalbum identifies garden birds from a camera stream and turns the sightings into a collectible album that fills itself. It runs entirely on your own hardware — no cloud, no third-party services. The interface speaks German and English; the source code and its comments are German.

---

Was es macht

Eine Kamera schaut aufs Futterhaus. Alles andere passiert von selbst:

• 🔍 Erkennt die Art — zwei neuronale Netze, eines findet den Vogel im Bild, eines bestimmt ihn. Gemessen: 43 von 44 Arten richtig, keine falsch bestimmt.
• 🎴 Sammelt — jede neue Art ist ein Erstfang. 148 Arten, 15 Abzeichen, XP und Level. Das ist der Teil, für den Kinder wiederkommen.
• 🏠 Bleibt zu Hause — kein Cloud-Dienst, keine Telemetrie, kein Konto. Die Erkennung läuft auf deiner Hardware, die Bilder verlassen dein Netz nicht.
• 🔌 Nimmt jede Kamera — MJPEG, RTSP, Einzelbilder oder ein Ordner. Ein Raspberry Pi Zero genügt, ein ESP32-S3 für 17 € auch.
• 🥔 Läuft auf kleiner Hardware — gemessen auf einem Raspberry Pi 4: 42 ms je bestimmtem Vogel, 1,1 GB Arbeitsspeicher. Zahlen für beide getesteten Geräte in docs/installation.md.
• 📱 Auch ohne Kamera — Handyfotos lassen sich hochladen und werden genauso bestimmt.
• 🏡 Spricht mit Home Assistant — über MQTT, mit Autodiscovery.

Schnellstart

Sammlung und Erkennung auf einer Maschine, ohne venv und ohne Modelle von Hand:

git clone https://gitea.gaertner.onl/christian/vogelalbum.git && cd vogelalbum
cp .env.beispiel .env          # VOGELALBUM_SOURCE und ein Token eintragen
docker compose -f docker-compose.heim.yml up -d

Die Sammlung läuft danach auf http://localhost:8000. Zwei Zeilen in der .env müssen stimmen:

Variable	was rein muss
VOGELALBUM_SOURCE	Stream-URL der Kamera, z.B. http://vogelkamera.local:8080/stream
VOGELALBUM_INGEST_TOKEN	ein selbst ausgedachtes Geheimnis, openssl rand -base64 32

Noch keine Kamera? Es geht auch ohne — manage.py demo_data füllt die Sammlung mit 21 Tagen Beispieldaten. Der Aufbau einer Kameraseite steht in pi/README.md (Raspberry Pi) oder esp32cam/README.md (ESP32-S3, billiger).

Ohne Docker, Schritt für Schritt: docs/installation.md.

Wie es aufgebaut ist

Zwei Teile, die unabhängig voneinander laufen und getrennt deploybar sind:

Heimnetz                                    │  Internet
                                            │
Kamera 1 ──MJPEG──▶ ┌──────────┐            │
Kamera 2 ──MJPEG──▶ │ detector │ ──POST────────▶ Django ──▶ Browser
Kamera n ──MJPEG──▶ │          │  Bearer    │
                    └────┬─────┘            │
                         └──▶ Rohbilder     │
                             (Training)     │

Die Verbindung geht nur in eine Richtung. Der Detector meldet ausgehend an /api/sightings/; die Web-App muss weder Kamera noch Erkennungs-Host jemals erreichen. Damit muss im Heimnetz kein einziger Port nach außen offen sein — kein Portforwarding, kein Tunnel, keine dynamische DNS. Genau deshalb kann die Sammlung öffentlich stehen, während die Kameras es nicht sind.

Warum überhaupt getrennt? Ein Raspberry Pi Zero kann streamen, aber nicht rechnen. Umgekehrt kennt die Web-App weder numpy noch LiteRT, was ihren Container klein hält.

Dokumentation

Kapitel	worum es geht
Installation	mit und ohne Docker, Schritt für Schritt
Die Kamera anschließen	Stream-Formate, Schwellwerte — und wie groß ein Vogel im Bild sein muss
Wie die Erkennung funktioniert	drei Stufen, der Artenfilter, was das Modell nicht kann
Wie gut ist das wirklich	gemessene Zahlen, und was im Feld tatsächlich passiert ist
Einstellungen	alle Variablen, und was stattdessen im Admin geht
Betrieb	mehrere Kameras, Live-Bild, Deployment
Entwicklung	Tests, Übersetzungen, Artenkatalog erweitern
Datenquellen und Lizenzen	woher Modelle und Fotos kommen

Die Kameraseiten haben eigene Anleitungen: pi/ und esp32cam/.

Was es (noch) nicht kann

Ehrlicher als eine Merkmalsliste:

• ⚠️ Der Katalog ist mitteleuropäisch. 148 in Deutschland vorkommende Arten; der Klassifikator rechnet seine Wahrscheinlichkeiten auf genau diese Liste um. Das Modell selbst kennt rund 965 Arten weltweit — die Begrenzung ist der Katalog, nicht die Erkennung. Die Region ist umschaltbar (VOGELALBUM_REGION), es fehlen nur die Artenlisten anderer Regionen. Das ist reine Datenarbeit und ein guter erster Beitrag.
• Acht heimische Arten kennt das Modell nicht und ordnet sie Verwandten zu (Sumpf-, Weiden-, Haubenmeise, Gartenbaumläufer, Kleinspecht, Bluthänfling, Kernbeißer, Waldkauz). Details in docs/erkennung.md.
• Der Aufbau entscheidet mehr als die Software. Ein Vogel braucht 5–8 % der Bildfläche, sonst findet ihn niemand. python -m detector karte misst das vorher, statt es hinterher zu lernen — siehe docs/kamera.md.

Mitmachen

Fehler, Ideen und Code sind willkommen. Die Spielregeln — und die Rechteeinräumung, die für die Doppellizenzierung nötig ist — stehen in CONTRIBUTING.md. Eine Sicherheitslücke bitte nicht als Issue, sondern nach SECURITY.md.

Was sich wann geändert hat: CHANGELOG.md.

Lizenz

GNU Affero General Public License 3.0 (LICENSE). Benutzen, verändern und weitergeben ist erlaubt; wer eine veränderte Fassung als Dienst über ein Netz anbietet, muss deren Quelltext zugänglich machen. Für den Betrieb im eigenen Garten ändert das nichts. Kommerzielle Nutzung ohne Offenlegung ist über eine gesonderte Lizenz möglich: webmaster@gaertner.onl.

Modelle (Apache 2.0) und Referenzfotos aus Wikimedia Commons (meist CC BY-SA) behalten ihre eigenen Lizenzen — Einzelheiten in docs/datenquellen.md.

---

_{Kein Bild dieses Projekts verlässt das eigene Netz, außer man deployt die Web-App selbst irgendwohin. Es gibt keine Telemetrie und keine Aufrufe an Dritte außer den ausdrücklich angestoßenen Downloads von Modellen und Referenzfotos.}