appRobotRender/benchmark/camera_count

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

---

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

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:

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):

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

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:

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

Verfügbare Metriken: finger_error_mm (Standard), 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 — Spalten inkl. finger_error_mm
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.)