137 lines
5.4 KiB
Markdown
137 lines
5.4 KiB
Markdown
# Foto-Kurator — Design Spec
|
||
|
||
**Datum:** 2026-04-07
|
||
**Status:** Genehmigt
|
||
|
||
## Überblick
|
||
|
||
Eine lokale Webanwendung, die den manuellen Foto-Culling-Prozess automatisiert. Das Tool analysiert einen Ordner voller Fotos und sortiert unbrauchbare Bilder (unscharf, über-/unterbelichtet, Duplikate) automatisch in einen Unterordner `_aussortiert/` aus.
|
||
|
||
## Architektur
|
||
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ Browser (Frontend) │
|
||
│ HTML/CSS/JS — Single Page App │
|
||
│ - Ordner auswählen │
|
||
│ - Einstellungen / Toggles │
|
||
│ - Fortschrittsanzeige │
|
||
│ - Review-Ansicht │
|
||
└────────────┬────────────────────┘
|
||
│ HTTP (localhost)
|
||
┌────────────▼────────────────────┐
|
||
│ Python FastAPI Backend │
|
||
│ - /analyze → Fotos analysieren│
|
||
│ - /move → Dateien verschieben│
|
||
│ - Pillow + OpenCV │
|
||
│ - optional: Claude Vision API │
|
||
└─────────────────────────────────┘
|
||
│ Dateisystem
|
||
┌────────────▼────────────────────┐
|
||
│ Lokaler Ordner (z.B. /Fotos/) │
|
||
│ ├── foto001.jpg │
|
||
│ ├── foto002.jpg │
|
||
│ └── _aussortiert/ │
|
||
│ └── foto003.jpg │
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
## Stack
|
||
|
||
- **Backend:** Python 3.10+, FastAPI, Pillow, OpenCV, imagehash, anthropic SDK (optional)
|
||
- **Frontend:** Vanilla HTML/CSS/JS (eine einzelne `index.html`)
|
||
- **Start:** `python server.py` → öffnet automatisch den Browser
|
||
|
||
## Projektstruktur
|
||
|
||
```
|
||
foto-kurator/
|
||
├── server.py # FastAPI Backend + Startup
|
||
├── analyzer.py # Bildanalyse-Logik (lokal + KI)
|
||
├── index.html # Frontend (Single Page App)
|
||
├── requirements.txt
|
||
└── .env # ANTHROPIC_API_KEY (optional)
|
||
```
|
||
|
||
## Analysekriterien
|
||
|
||
### Lokale Analyse (immer verfügbar)
|
||
|
||
| Kriterium | Methode | Standardschwellenwert |
|
||
|-----------|---------|----------------------|
|
||
| Unschärfe | Laplacian Variance (OpenCV) | < 100 |
|
||
| Überbelichtung | Durchschnittliche Helligkeit > Schwellenwert (Pillow) | > 240 |
|
||
| Unterbelichtung | Durchschnittliche Helligkeit < Schwellenwert (Pillow) | < 30 |
|
||
| Duplikate | Perceptual Hash (pHash, imagehash) | Hamming-Distanz ≤ 8 |
|
||
|
||
Alle Schwellenwerte sind in der UI per Schieberegler einstellbar.
|
||
|
||
### KI-Analyse (optional, Toggle)
|
||
|
||
Sendet Fotos batchartig an die Claude Vision API mit einem Qualitäts-Bewertungsprompt. Erkennt auch subtilere Probleme (schlechter Bildaufbau, störende Elemente, etc.).
|
||
|
||
- **Kosten:** ca. 0,002–0,005 € pro Foto
|
||
- **Anforderung:** Internetverbindung + `ANTHROPIC_API_KEY` in `.env`
|
||
- **Fallback:** Bei API-Fehler wird automatisch auf lokale Analyse zurückgefallen
|
||
|
||
## UI & Workflow
|
||
|
||
### Startseite
|
||
- Ordner-Auswahl: Texteingabe für den lokalen Pfad (z.B. `/Fotos/Shooting-2026-04`) + Button zum Bestätigen. Optional: nativer Ordner-Dialog via `tkinter` im Backend, der den Pfad zurückgibt.
|
||
- **Toggle:** Überprüfung vor dem Verschieben (an/aus)
|
||
- **Toggle:** KI-Analyse (an/aus) + Hinweis zu Kosten & Internetanforderung
|
||
- Schieberegler für alle Schwellenwerte
|
||
- Button: "Analyse starten"
|
||
|
||
### Während der Analyse
|
||
- Fortschrittsbalken mit aktuellem Dateinamen
|
||
- Abbruch-Button
|
||
|
||
### Review-Ansicht (wenn Toggle aktiv)
|
||
- Liste aller vorgeschlagenen Ausschüsse
|
||
- Pro Foto: Vorschaubild + Begründung (z.B. "unterbelichtet", "Duplikat von foto002.jpg")
|
||
- Jedes Foto einzeln bestätigen oder von der Liste entfernen
|
||
- Button: "Alle bestätigen & verschieben"
|
||
|
||
### Ohne Review (Toggle deaktiviert)
|
||
- Direktes Verschieben nach Analyse
|
||
- Kurze Zusammenfassung: "23 Fotos aussortiert"
|
||
|
||
### Ergebnisseite
|
||
- Anzahl analysierter Fotos
|
||
- Anzahl aussortierter Fotos, aufgeteilt nach Grund
|
||
- Hinweis auf `_aussortiert/`-Unterordner
|
||
|
||
## Datenfluss
|
||
|
||
1. Frontend schickt Ordnerpfad an `POST /analyze`
|
||
2. Backend iteriert über alle `.jpg/.jpeg/.png` im Ordner
|
||
3. Pro Foto: Unschärfe + Belichtung berechnen, pHash für Duplikatvergleich
|
||
4. Optional: Fotos batchartig an Claude Vision API senden
|
||
5. Antwort: JSON-Liste `[{ path, reasons: ["unscharf", ...] }]`
|
||
6. Frontend zeigt Review-Ansicht oder schickt direkt `POST /move`
|
||
7. Backend verschiebt Dateien in `_aussortiert/`
|
||
|
||
## Fehlerbehandlung
|
||
|
||
- Korrupte oder nicht lesbare Dateien werden übersprungen und in einem Log festgehalten
|
||
- API-Fehler (Claude Vision) fallen automatisch auf lokale Analyse zurück
|
||
- Kein Foto wird ohne expliziten `/move`-Aufruf verschoben — die Analyse ist immer nicht-destruktiv
|
||
|
||
## Unterstützte Formate
|
||
|
||
- **Primär:** `.jpg`, `.jpeg`, `.png`
|
||
- **Selten:** RAW-Formate (`.CR2`, `.NEF`, `.ARW`) — in Phase 1 nicht unterstützt, für spätere Version vorgesehen
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
python server.py
|
||
# Browser öffnet automatisch http://localhost:8000
|
||
```
|
||
|
||
## Erweiterbarkeit
|
||
|
||
Die Architektur ist so ausgelegt, dass das Tool später als echter Webserver mit mehreren Nutzern betrieben werden kann. Der einzige erforderliche Schritt ist die Umstellung der Ordnerpfad-Logik auf nutzerspezifische Upload-Verzeichnisse.
|