# 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.