# Kamera-Anzahl-Studie

Untersucht, wie sich die Pose-Schätzgenauigkeit verändert, wenn weniger Kameras
verwendet werden. Ergebnis ist eine Kurve **k Kameras → mittlerer Gelenkwinkelfehler (°)**.

Hintergrundfrage und Entscheidungslogik: [`doc/camera_number_roadmap.md`](../../doc/camera_number_roadmap.md)

---

## Voraussetzungen

Pro Szene müssen vorhanden sein:

| Datei | Woher |
|---|---|
| `data/simulation/SceneX/render_*.png` | Blender-Renderer |
| `data/simulation/SceneX/render_*.npz` | Kamera-Intrinsik |
| `data/simulation/SceneX/pose.json` | Ground-Truth-Pose |
| `data/robot/robot.json` | Robotermodell |

Neue Szenen werden **automatisch erkannt** — kein Skript anpassen nötig.

---

## Schritt 1 — Studie laufen lassen

```bat
run\run_camera_study.bat
```

Das wertet alle verfügbaren Szenen aus, k = 3 bis (alle verfügbaren Kameras),
10 zufällige Subsets pro k.

**Optionen:**

```bat
REM Nur bestimmte Szenen
run\run_camera_study.bat --scenes Scene7 Scene9

REM Kamerabereich einschränken
run\run_camera_study.bat --k-min 3 --k-max 5

REM Weniger Samples — schneller, weniger repräsentativ
run\run_camera_study.bat --samples 3

REM Existierende Ergebnisse überschreiben
run\run_camera_study.bat --force

REM Alles kombinierbar
run\run_camera_study.bat --scenes Scene7 --k-min 3 --k-max 5 --samples 5 --force
```

Oder direkt über Python (z. B. in einer Linux-Umgebung / Docker):

```bash
python benchmark/camera_count/run_camera_study.py --samples 10
```

**Laufzeit:** Pro Kamera-Subset läuft die volle Pipeline (Schritt 1–4).
Bei 3 Szenen × 5 k-Werte × 10 Samples = 150 Läufe — je nach Hardware mehrere Minuten.

Bereits gerechnete Subsets werden **übersprungen** (kein `--force` nötig für Fortsetzung).

---

## Schritt 2 — Auswertung

```bash
python benchmark/camera_count/analyze.py
```

Ausgabe auf der Konsole:

```
Kamera-Anzahl vs. mean_abs_deg
   k |     n |   Mittel |   Median |      Std |      Min |      Max
-----------------------------------------------------------------
   3 |    30 |    0.842 |    0.731 |    0.312 |    0.251 |    1.843
   4 |    30 |    0.563 |    0.521 |    0.198 |    0.252 |    1.102
   ...

Beste / schlechteste Subsets je k:
  k=3:  best  [Scene7] ace (0.251°)   worst [Scene9] bdf (1.843°)
  ...
```

Zusätzlich wird ein Boxplot gespeichert:
`benchmark/camera_count/results/camera_count_vs_error.png`

**Andere Metrik:**

```bash
python benchmark/camera_count/analyze.py --metric max_abs_deg
```

Verfügbare Metriken: `mean_abs_deg`, `max_abs_deg`, `mean_abs_mm`, `max_abs_mm`

---

## Ausgabedateien

| Pfad | Inhalt |
|---|---|
| `benchmark/camera_count/results/camera_study.json` | Alle Einzelergebnisse (Szene, k, Subset, Fehler) |
| `benchmark/camera_count/results/camera_study.csv` | Dasselbe als CSV (Excel, Pandas) |
| `benchmark/camera_count/results/camera_count_vs_error.png` | Boxplot |
| `data/camera_study/SceneX/k3_abc/` | Pipeline-Zwischenergebnisse pro Subset |

Die Zwischenergebnisse in `data/camera_study/` sind groß — nicht committen.

---

## Ergebnis interpretieren

Die Studie beantwortet drei Fragen:

1. **Ab welchem k wird der Fehler stabil?**
   → Knick in der Kurve zeigt den Sättigungspunkt.

2. **Welche Kamera-Kombination ist bei k=3 am besten?**
   → `analyze.py` gibt beste und schlechteste Subsets aus.

3. **Gibt es Szenen / Posen, bei denen wenige Kameras systematisch scheitern?**
   → CSV öffnen, nach `scene` gruppieren.

Eine praktische Entscheidungsregel: 3 Kameras gelten als ausreichend, wenn
`mean_abs_deg` bei k=3 nicht mehr als ~20 % schlechter ist als beim Maximum,
und `max_abs_deg` keine kritischen Ausreißer zeigt.
(Schwellwert je nach Anwendung anpassen.)