Multipoint Schritt 3

doc/Homing_5_Pose_MultiPoint_Weighted.md

@@ -1,11 +1,16 @@
 # Homing 5 – Verbesserungspfade: Mehrpunkt-Residuen & Gewichtung
 
-> Reine Wegbeschreibung — **nichts davon ist umgesetzt**. Ergänzt
-> [`Homing_5_Pose.md`](Homing_5_Pose.md) um drei mögliche Verbesserungen, die
-> alle an derselben Stelle ansetzen: *was* ein Marker als Messung beiträgt und
-> *wie stark* sie zählt. Stand: 2026-06-16, basiert auf Code-Durchsicht
-> (`scripts/1_detect_aruco_observations.py`, `3b_corner_marker_poses.py`,
-> `5_pose_estimation.py`), keine Code-Änderung.
+> Ergänzt [`Homing_5_Pose.md`](Homing_5_Pose.md) um drei mögliche
+> Verbesserungen, die alle an derselben Stelle ansetzen: *was* ein Marker als
+> Messung beiträgt und *wie stark* sie zählt.
+>
+> **Status (2026-06-25):** **Qualitäts-Gewichtung** (Doc-Punkt 3 / Schritte 1+2)
+> umgesetzt. **Mehrpunkt-Eckresiduen** (Doc-Punkt 1 / Schritte 3+4) umgesetzt
+> als Opt-in-Modus `marker_observation="corner_points"` — 12 Eck-Residuen für
+> Roboter-Links, 1 Center-Residuum für die (spin-unkalibrierten) Board/Rail-
+> Marker auf dem Root-Link. Endgültiges Tuning/Validierung gegen Simulation
+> steht aus (siehe Notiz unten). **Einzelkamera-Einbindung** (Doc-Punkt 2 /
+> Schritte 5+6) weiterhin **offen** — siehe Status-Spalte unten.
 
 ---
 
@@ -216,15 +221,21 @@ Reihenfolge folgt der Risiko-Einschätzung oben: erst risikoarmes Durchreichen,
 dann die beiden strukturellen Erweiterungen. Jeder Schritt ist einzeln
 umsetzbar und (wo möglich) einzeln testbar, bevor der nächste beginnt.
 
-| # | Schritt | Testbar an | Bricht Bestehendes? |
-|---|---|---|---|
-| 1 | **(Punkt 3)** `quality`/`confidence` aus `{cam}_aruco_detection.json` bis nach `aruco_marker_poses.json` durchreichen (3b liest es, schreibt ein neues `weight`-Feld pro Marker) | Diff der Ausgabedatei: nur das neue Feld ist zusätzlich da, alles andere (Position, Normale, …) identisch zu vorher — reiner Additivitätstest | **Nein.** Rein additives Feld, kein Pflichtfeld, alte Leser ignorieren es |
-| 2 | **(Punkt 3)** `residual_vector()` nutzt das neue Gewicht, hinter einem Schalter (`pose_estimation.use_marker_weight`, Default `false`) | A/B-Vergleich auf den appRobotRendering-Simulationsszenen (mit/ohne Schalter) gegen bekannte Grundwahrheit — genau der Test, der laut Nutzer beim ersten Versuch wenig brachte, jetzt wiederholbar | **Nein bei Default aus.** Mit `true`: Ergebnisse ändern sich gewollt — muss vor Produktiv-Default separat validiert werden |
-| 3 | **(Punkt 1)** `robot_fk.py`: neue Methode liefert die 4 lokalen Eckpunkte eines Markers im Weltsystem (Baustein, noch ohne Anbindung) | Isoliert testbar, ganz ohne `5_pose_estimation.py`: gegen die wahren Eckpositionen aus `render_*.json` (Simulation liefert das schon) | **Nein.** Neue, bisher von niemandem aufgerufene Methode |
-| 4 | **(Punkt 1)** Neuer `marker_observation`-Modus (z. B. `"corner_points"`) nutzt die 12 Eck-Residuen statt 6 Center/Normal-Residuen | Direkter Vorher/Nachher-Vergleich gegen dieselbe Validierungstabelle wie in `Homing_5_Pose.md` (10 Simulationsposen, bekannte GT) | **Nein als Opt-in** (Default bleibt `"corner_pose"`). Tuning-Punkt: `huber_delta_mm` ist auf die heutige Residuumsgröße kalibriert — mit 12 statt 6 Werten/Marker verschiebt sich die RMS-Größenordnung, müsste neu eingeordnet werden |
-| 5 | **(Punkt 2)** 3b nimmt 1-Kamera-Beobachtungen mit auf (rohe 2D-Ecken + Kamera-Referenz), statt sie zu verwerfen | Output-Diff: nur neue Einträge für vorher fehlende Marker, bestehende ≥2-Kamera-Einträge unverändert | **Ja, konkret** — siehe Konsumenten-Recherche direkt unter der Tabelle. Mehrere Stellen brauchen einen Guard, **bevor** dieser Schritt scharf geschaltet wird |
-| 6 | **(Punkt 2)** `residual_vector()` um Reprojektions-Residuen erweitert; `load_observations()`/`estimate_pose()` lesen zusätzlich Kamerakalibrierung | Zuerst an Simulationsszenen, bei denen gut beobachtete Marker künstlich auf „nur 1 Kamera" reduziert werden (GT bekannt) — saubere Kontrolle, ob das Residuum tatsächlich hilft, bevor reale Finger-Marker überhaupt existieren | **Nein strukturell** (additiver Residuumstyp), aber Regressionsrisiko durch falsche mm/px-Gewichtung — vor Produktiv-Default gegen die bestehende Validierungstabelle gegenprüfen (wie Schritt 4) |
-| 7 | Zusammenführen: ein gemeinsames Gewichtsschema (Quality × Kamera-Anzahl × Residuumstyp) statt drei separater Schalter | End-to-End gegen Simulationsbenchmark **und** die drei realen Fixtures aus `Homing_5_Pose.md` | **Nein**, wenn alle Vorstufen additive Defaults hatten |
+> **Status-Legende:** ✅ erledigt · ⬜ **offen**
+>
+> **Punkt-Zuordnung** (Doc-Abschnitt ↔ Chat-Nummerierung): Doc-Punkt 1 „Vier
+> Eckpunkte" = Schritte 3+4 · Doc-Punkt 2 „Einzelkamera" = Schritte 5+6 ·
+> Doc-Punkt 3 „Qualitäts-Gewichtung" = Schritte 1+2 (erledigt).
+
+| # | Status | Schritt | Testbar an | Bricht Bestehendes? |
+|---|---|---|---|---|
+| 1 | ✅ erledigt (2026-06-17) | **(Doc-Punkt 3)** `quality`/`confidence` aus `{cam}_aruco_detection.json` bis nach `aruco_marker_poses.json` durchreichen (3b liest es, schreibt ein neues `weight`-Feld pro Marker) | Diff der Ausgabedatei: nur das neue Feld ist zusätzlich da, alles andere (Position, Normale, …) identisch zu vorher — reiner Additivitätstest | **Nein.** Rein additives Feld, kein Pflichtfeld, alte Leser ignorieren es |
+| 2 | ✅ erledigt (2026-06-17) | **(Doc-Punkt 3)** `residual_vector()` nutzt das neue Gewicht, hinter einem Schalter (`pose_estimation.use_marker_weight`, Default `false`) | A/B-Vergleich auf den appRobotRendering-Simulationsszenen (mit/ohne Schalter) gegen bekannte Grundwahrheit — genau der Test, der laut Nutzer beim ersten Versuch wenig brachte, jetzt wiederholbar | **Nein bei Default aus.** Mit `true`: Ergebnisse ändern sich gewollt — muss vor Produktiv-Default separat validiert werden |
+| 3 | ✅ erledigt (2026-06-25) | **(Doc-Punkt 1)** `robot_fk.py`: neue Methode liefert die 4 lokalen Eckpunkte eines Markers im Weltsystem (Baustein, noch ohne Anbindung) | Isoliert testbar, ganz ohne `5_pose_estimation.py`: gegen die wahren Eckpositionen aus `render_*.json` (Simulation liefert das schon) | **Nein.** Neue, bisher von niemandem aufgerufene Methode |
+| 4 | 🟡 Code erledigt (2026-06-25), Tuning offen | **(Doc-Punkt 1)** Neuer `marker_observation`-Modus (z. B. `"corner_points"`) nutzt die 12 Eck-Residuen statt 6 Center/Normal-Residuen | Direkter Vorher/Nachher-Vergleich gegen dieselbe Validierungstabelle wie in `Homing_5_Pose.md` (10 Simulationsposen, bekannte GT) | **Nein als Opt-in** (Default bleibt `"corner_pose"`). Tuning-Punkt: `huber_delta_mm` ist auf die heutige Residuumsgröße kalibriert — mit 12 statt 6 Werten/Marker verschiebt sich die RMS-Größenordnung, müsste neu eingeordnet werden |
+| 5 | ⬜ **offen** (Vorarbeit/Guards ✅) | **(Doc-Punkt 2)** 3b nimmt 1-Kamera-Beobachtungen mit auf (rohe 2D-Ecken + Kamera-Referenz), statt sie zu verwerfen | Output-Diff: nur neue Einträge für vorher fehlende Marker, bestehende ≥2-Kamera-Einträge unverändert | **Ja, konkret** — siehe Konsumenten-Recherche direkt unter der Tabelle. Mehrere Stellen brauchen einen Guard, **bevor** dieser Schritt scharf geschaltet wird |
+| 6 | ⬜ **offen** | **(Doc-Punkt 2)** `residual_vector()` um Reprojektions-Residuen erweitert; `load_observations()`/`estimate_pose()` lesen zusätzlich Kamerakalibrierung | Zuerst an Simulationsszenen, bei denen gut beobachtete Marker künstlich auf „nur 1 Kamera" reduziert werden (GT bekannt) — saubere Kontrolle, ob das Residuum tatsächlich hilft, bevor reale Finger-Marker überhaupt existieren | **Nein strukturell** (additiver Residuumstyp), aber Regressionsrisiko durch falsche mm/px-Gewichtung — vor Produktiv-Default gegen die bestehende Validierungstabelle gegenprüfen (wie Schritt 4) |
+| 7 | ⬜ **offen** | Zusammenführen: ein gemeinsames Gewichtsschema (Quality × Kamera-Anzahl × Residuumstyp) statt drei separater Schalter | End-to-End gegen Simulationsbenchmark **und** die drei realen Fixtures aus `Homing_5_Pose.md` | **Nein**, wenn alle Vorstufen additive Defaults hatten |
 
 ### Recherche zu Schritt 5: wer liest `aruco_marker_poses.json`? (2026-06-16)
 
@@ -259,6 +270,34 @@ Homing-Seite selbst (`editRobot.js`, `homing.js`) ist bereits robust.
 
 Alle anderen Konsumenten (`homing.js`, `editRobot.js` → `assignByZRange`/`alignSetToMeasured`, `scripts/9_evaluateMarker.py`) waren schon robust oder sind Offline-Benchmark-Code ohne Produktionsrelevanz.
 
+### Umsetzung Schritt 3+4 (Doc-Punkt 1) — Befunde (2026-06-25)
+
+- **Schritt 3** (`robot_fk.py`): `marker_corners_local/_world` + `all_markers_world`
+  liefern jetzt `corners_world` (4×3, in `corners_m`-Reihenfolge). Orientierung =
+  Spin um die Normale ∘ Minimal-Rotation [0,0,1]→Normale (exakt wie
+  boardViewer.html). Verifiziert in `test/test_robot_fk_corners.py`:
+  Selbst-Konsistenz (Center/Kanten/planar/Normalen-Rückgewinnung) **und** gegen
+  echte triangulierte Roboter-Ecken am Seed-Pose (~1 mm RMS, Identitäts-Paarung
+  schlägt jede Umordnung). Eckreihenfolge = `(+h,+h),(+h,-h),(-h,-h),(-h,+h)`
+  (= boardViewer-Zeiger (1,1,0)).
+- **Wichtiger Konventions-Befund:** Die `spin`-Werte sind nur für die
+  **Roboter-Marker** kalibriert/visuell verifiziert, **nicht** für die Board/
+  Rail-Marker (Set A0/rail, alle auf dem Root-Link `Board`). Deren Eckreihenfolge
+  liegt ~90° daneben. Lösung: `corner_points` nutzt 12 Eck-Residuen nur für
+  Roboter-Links (`corner_point_links`, Default = alle Nicht-Root-Links) und 1
+  Center-Residuum für die Board/Rail-Marker. Da `Board` Root ist (Residuum
+  konstant bzgl. der Gelenke), kostet das nichts an Information.
+- **Datenbefund (nicht Code):** 6 Marker des Board-Sets **A0 sind auf `Arm1`
+  fehlzugeordnet** (`[55,56,57,77,78,99]`), ~230 mm neben dem Modell. Sie
+  destabilisieren `corner_points` (12 statt 3 Residuen → falsches Minimum) und
+  ziehen auch `corner_pose` leicht. Auf bereinigten Markern konvergiert
+  `corner_points` ≈ `corner_pose`. → Marker-Zuordnung korrigieren (separate
+  Kalibrier-Aufgabe).
+- **Offen (Schritt 4 Tuning):** `huber_delta_mm` ist auf 6 Residuen/Marker
+  kalibriert; mit 12 verschiebt sich die RMS-Größenordnung. Sauberes A/B + Tuning
+  gegen appRobotRendering-Simulations-GT (klare Daten) steht aus, bevor der Modus
+  produktiv als Default taugt. CLI: `--marker-observation corner_points`.
+
 ## Offene Punkte
 
 - [ ] Keiner der drei Punkte/Schritte ist priorisiert/entschieden — reine Optionen.