OnlyFrames/docs/superpowers/specs/2026-04-07-foto-kurator-design.md

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

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.