🪙 Euro Münzen Scanner Pro

KI-gestützte Erkennung und Verwaltung von 2-Euro-Gedenkmünzen.
Scanne deine Münzen mit dem Handy oder PC — die KI identifiziert Motiv, Land, Jahr und erkennt seltene Prägefehler.

---

✨ Features

• KI-Erkennung via OpenRouter (Gemini 2.5 Flash/Pro) — 8 Winkel, CLAHE + Unsharp Masking
• Katalog mit allen 2-Euro-Gedenkmünzen der EU (EZB + Wikidata)
• Passmarken-Matte für präzise, reproduzierbare Aufnahmen
• Prägefehler-Erkennung (Spiegelei, Dezentrierungen)
• Cross-Device Sync — Handy scannen, am PC sofort sehen
• Sammlung mit SQLite-Datenbank und Duplikat-Erkennung
• Vergleichsansicht — Dein Scan neben dem Katalog-Referenzbild

---

🏗️ Systemvoraussetzungen

Komponente	Version
Proxmox VE	8.x
Docker	24+
Python	3.11
RAM (Container)	≥ 2 GB empfohlen
OpenRouter API-Key	Erforderlich für KI-Erkennung

---

🚀 Deployment (Proxmox + Docker)

1. Projektdateien auf den Server kopieren

# Auf deinem Windows-PC (PowerShell)
scp -r C:\Users\<user>\.gemini\antigravity\scratch\euro-coin-scanner\ root@10.10.10.163:/opt/euro-coin-scanner/

2. Docker Container starten

# Auf dem Proxmox-Host (CT 107 via SSH oder Shell)
cd /opt/euro-coin-scanner

# Bauen und starten
docker compose up -d --build

# Oder: direkter Start (ohne Compose)
docker run -d \
  --name euro_coin_scanner \
  -p 8088:8000 \
  -v /opt/euro-coin-scanner/backend/storage:/app/backend/storage \
  euro-coin-scanner:latest

3. App aufrufen

http://10.10.10.163:8088

---

🔑 OpenRouter einrichten

1. Account erstellen auf openrouter.ai
2. API-Key generieren unter Keys
3. In der App: ⚙️ → KI-Einstellungen
   • API-Key einfügen
   • Modell wählen: google/gemini-2.5-flash (empfohlen) oder google/gemini-2.5-pro
   • KI aktivieren ✅

Der Key wird nur im Browser-LocalStorage gespeichert und nie an den Server gesendet.

---

📱 Cross-Device Sync (Handy → PC)

1. Öffne die App auf dem Handy: http://10.10.10.163:8088
2. Scanne eine Münze
3. Auf dem PC erscheint der Scan automatisch nach ≤ 3 Sekunden
   (Live-Sync-Button 📲 muss aktiv/grün sein)

---

📸 Scan-Tipps

Passmarken-Matte verwenden

Die Vorlage (PDFs im Ordner docs/) enthält 4 Passmarken-Quadrate:

• Einzelne Münze: für Nahaufnahmen und optimale Erkennung
• 10 Münzen: für Batch-Scans bei guten Lichtverhältnissen

Beste Ergebnisse

✅ Gut	❌ Vermeiden
Diffuses Tageslicht	Direktes Sonnenlicht / starke Schatten
Makro-Modus aktivieren	Digitaler Zoom
Münze reinigen	Fettige/verschmutzte Münzen
Kamera senkrecht über Münze	Schräger Winkel
Gleichmäßige Beleuchtung von vorn	Seitenlicht (Schattenrelief)
Helle, matte Unterlage	Glänzende/gemusterte Unterlage

Warum einzeln fotografieren?

Bei Gruppenaufnahmen können:

• Schatten benachbarter Münzen das Relief verdecken
• Lichtverhältnisse auf mehrere Münzen ungleichmäßig wirken
• Die Passmarken-Erkennung Münzen überspringen

→ Für zuverlässige KI-Erkennung: eine Münze pro Aufnahme

---

🔧 Troubleshooting

KI erkennt Münze nicht

1. Prüfe ob OpenRouter API-Key konfiguriert ist (⚙️ → KI-Einstellungen)
2. Probiere google/gemini-2.5-pro statt Flash
3. Verbessere die Aufnahme (Licht, Makro, senkrecht)
4. Drehe die Münze um 90° und scanne erneut

Scan schlägt fehl (JSON-Fehler)

Scan fehlgeschlagen: Unexpected token 'I'...

→ OpenRouter-Modell gibt kein JSON zurück. Wechsle das Modell in den Einstellungen.

Passmarken werden nicht erkannt

• Vorlage nicht verknittert oder falsch beleuchtet (Reflexionen auf glänzendem Papier)
• Vorlage auf mattem Papier drucken
• Mindestens A4, besser A3

Container startet nicht

docker logs euro_coin_scanner
# oder
docker compose logs -f

Dateien im Container aktualisieren

# Einzelne Datei
docker cp /opt/euro-coin-scanner/backend/api/main.py euro_coin_scanner:/app/backend/api/main.py
docker restart euro_coin_scanner

# Alle Backend-Dateien
docker cp /opt/euro-coin-scanner/backend/. euro_coin_scanner:/app/backend/
docker restart euro_coin_scanner

---

📁 Projektstruktur

euro-coin-scanner/
├── backend/
│   ├── api/
│   │   └── main.py              # FastAPI Hauptanwendung
│   ├── ai/
│   │   └── openrouter_matcher.py # KI-Erkennung (8 Winkel, CLAHE)
│   ├── cv/
│   │   ├── coin_detector.py     # Passmarken + Münz-Cropping
│   │   ├── coin_aligner.py      # DINOv2 Feature-Matching
│   │   └── error_detector.py    # Prägefehler-Erkennung
│   ├── catalog/
│   │   └── catalog_updater.py   # EZB/Wikidata Sync
│   ├── database/
│   │   ├── models.py            # SQLAlchemy Modelle
│   │   └── db.py                # Datenbankverbindung
│   └── storage/                 # Bilder, DB, Cache (persistent)
├── frontend/
│   └── index.html               # Single-Page App (Tailwind CSS)
├── docs/
│   ├── 2_Euro_Scanunterlage.pdf        # 10-Münzen Matte
│   └── 2_Euro_Scanunterlage_1.pdf      # 1-Münze Matte
├── Dockerfile
├── docker-compose.yml
└── README.md

---

🧠 KI-Erkennung (Technische Details)

Die Münzerkennung nutzt einen mehrstufigen Ansatz:

1. Passmarken-Erkennung (coin_detector.py) — 4 schwarze Quadrate lokalisieren den Münzbereich
2. Bildvorverarbeitung — CLAHE (Kontrastverstärkung) + Unsharp Masking für metallische Reliefs
3. 8-Winkel-Kollage — 0°, 45°, 90°, 135°, 180°, 225°, 270°, 315° werden zu einem Grid kombiniert
4. Vision-KI (OpenRouter Gemini) — analysiert das Grid und extrahiert Motiv, Inschriften, Land, Jahr
5. Katalog-Matching — Motiv-Token-Abgleich gegen 525+ Katalogeinträge
6. Prägefehler (error_detector.py) — Spiegelei-Erkennung via Kreisflächen-Analyse

---

📜 Lizenz

MIT License — freie Nutzung und Weiterentwicklung.