Vogelalbum 1.0.0

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

Zwei neuronale Netze: eines findet den Vogel im Bild, eines bestimmt die
Art. 148 heimische Arten, auf Deutschland eingeschraenkt und neu normiert —
ohne diese Einschraenkung wird aus einer Kohlmeise eine nordamerikanische
Schwesterart. Daraus entsteht ein Sammelalbum: nummerierte Seiten,
gefundene Arten in Farbe, fehlende als Schatten, dazu Erstfang, Punkte,
Stufen und 15 Abzeichen.

Laeuft vollstaendig auf eigener Hardware. Kein Cloud-Dienst, kein Konto,
keine Telemetrie; die Bilder verlassen das eigene Netz nicht.

Zwei getrennt deploybare Teile: die Sammlung als Django-Anwendung, die
Erkennung als eigener Dienst. Der Erkennungs-Dienst fragt selbst an und
braucht deshalb weder eine erreichbare Adresse noch einen offenen Port —
er laeuft hinter einem gewoehnlichen Router.

Dabei: Firmware fuer Raspberry Pi und ESP32-S3, Anbindung an Home
Assistant ueber MQTT, Oberflaeche auf Deutsch und Englisch, Einstellungen
je Kamera aus dem Browser, und ein Weg fuer Fotos von unterwegs.

AGPL-3.0.

docs/entwicklung.md

@@ -0,0 +1,74 @@
+# Entwicklung
+
+<sub>[← zurück zum Überblick](../README.md) · [alle Kapitel](README.md)</sub>
+
+Tests, Übersetzungen, Layoutprüfung und das Erweitern des Artenkatalogs. Wer
+etwas beitragen will, findet die Spielregeln in
+[CONTRIBUTING.md](../CONTRIBUTING.md).
+
+```bash
+./venv/bin/python -m unittest discover tests      # Detector
+cd web && ../venv/bin/python manage.py test dex   # Web-App
+```
+
+### Übersetzungen
+
+Oberflächentexte laufen über Djangos i18n, Artentexte über eigene Felder am
+Modell (`beschreibung_en` und Geschwister). Abzeichen und Ränge liegen als
+deutscher Text in der Datenbank und werden erst bei der Ausgabe übersetzt —
+sie sind ein fester, im Code definierter Satz, und so braucht ein
+Sprachwechsel keine Migration.
+
+```bash
+cd web && ../venv/bin/python manage.py makemessages -l en --ignore=venv
+cd .. && ./venv/bin/python scripts/update_translations.py
+cd web && ../venv/bin/python manage.py compilemessages -l en
+```
+
+**Die .po-Datei nicht von Hand pflegen.** `makemessages` ruft `msgmerge` auf,
+und das rät: Ein neuer Text, der einem alten ähnelt, erbt dessen Übersetzung
+und wird als `#, fuzzy` markiert. So wurde aus „Sammler" ein „Collection" (von
+„Sammlung"). `msgfmt` wirft Fuzzy-Einträge weg, im Betrieb sieht man also
+deutschen Resttext — und wer dann „ersetze `msgstr`, wenn leer" anwendet,
+greift daneben, weil leer eben nichts ist.
+`scripts/update_translations.py` überschreibt deshalb immer und räumt die
+Marke weg.
+
+### Layout prüfen
+
+**Layoutänderungen gehören in vier Breiten angesehen**, bevor sie rausgehen:
+iPad hochkant (810), iPad quer (1180), iPhone (390), Desktop (1440). Blind
+gebaute Layouts sehen auf genau einer Breite gut aus, und das ist selten die,
+auf der jemand liest.
+
+`color-mix()` gibt es erst ab Safari 16.2, `aspect-ratio` erst ab Safari 15.
+Beides fällt auf älteren Geräten ersatzlos weg: Farben verschwinden, und
+Bildkästen verlieren ihre Höhe, sodass jedes Foto in seiner natürlichen Größe
+rendert. Deshalb werden Typfarben in `web/dex/species_meta.py` vorberechnet
+und Bildverhältnisse über `padding-top` gelöst.
+
+Fehlt Chromium und gibt es kein root, hilft `apt-get download` — das braucht
+keine Rechte:
+
+```bash
+mkdir -p ~/.local/chromium-deps && cd ~/.local/chromium-deps
+for p in libatk1.0-0t64 libatk-bridge2.0-0t64 libatspi2.0-0t64 \
+         libxdamage1 libasound2t64 libasound2-data; do apt-get download "$p"; done
+mkdir -p root && for d in *.deb; do dpkg -x "$d" root/; done
+export LD_LIBRARY_PATH=~/.local/chromium-deps/root/usr/lib/x86_64-linux-gnu
+```
+
+Dasselbe funktioniert für `gettext`, falls `msgfmt` fehlt.
+
+> `runserver --noreload` cached auch Templates. Nach Template-Änderungen neu
+> starten, sonst sieht man weiter die alte Fassung.
+
+### Den Katalog erweitern
+
+`detector/species_de.py` enthält die Kernarten mit Erzähltext,
+`detector/species_extra.py` die übrigen mit Strukturdaten,
+`detector/profiles/` die Steckbriefe.
+
+Jede neue Art muss im Label-File des Modells vorkommen, sonst kann sie
+niemand freischalten — ein Test prüft das. Ebenso, dass jeder benutzte Typ in
+der Web-App eine Farbe und einen englischen Namen hat.