appRobotRender/doc/lens_errors_roadmap.md

Roadmap: Kamera-/Linsenfehler simulieren (billige WebCams)

Status: ✅ umgesetzt (A–D) in setup/generateSets/render_robot.py, Parameter in robot.json → renderingInfo. A ist isoliert getestet (deterministisches npz-Rauschen). B–D sind Compositor-Effekte und müssen einmal in Blender 4.5 visuell geprüft werden — jeder Effekt ist in try/except gekapselt: ein API-Problem überspringt nur den betroffenen Effekt mit Log-Warnung [render][WARN] <effekt> skipped: ..., der Render läuft weiter.

Parameter (robot.json → renderingInfo)

Effekt	Parameter	Beispiel
A Brennweiten-Restfehler	focalErrorPct	0.5 (±%)
A Hauptpunkt-Versatz	principalErrorPx	3.0 (±px)
A Rest-Verzeichnung	residualDistortion	[0.02, -0.01] (k1,k2)
B Linsenstaub	lensDirt / lensDirtStrength	true / 0.08
C Vignette	vignette / vignetteStrength	true / 0.08
C Rand-Unschärfe	localizedBlur / localizedBlurStrength	false / 0.15
D Sensor-Rauschen	sensorNoise / sensorNoiseStrength	true / 0.01
D chromat. Aberration	lensDistortion / lensDistortionStrength	true / 0.002

Wichtig: A verfälscht nur die npz-Kalibrierung (Bild bleibt ideal) → echter geometrischer Härtetest gegen unvollständige Kalibrierung; deterministisch pro Kamera (Seed aus cameraPosition), damit über alle Posen konsistent. B–D ändern nur das Bild (Detektion erschwert), nicht die Ground-Truth.

---

(Ursprüngliche Detailplanung als Referenz:)

Ziel: Realistische WebCam-Fehler in den Blender-Renderer (setup/generateSets/render_robot.py) einbauen, um die Pose-Pipeline gegen reale Kamera-Imperfektionen zu härten — analog zu den bereits umgesetzten Marker-Störungen (markerOffsetMaxMm, motionBlur, arucoDust).

Kernkonzept (wichtig!)

Es gibt zwei Fehlerklassen:

1. Geometrische Fehler (Brennweite, Hauptpunkt, Verzeichnung): verschieben die Marker-Pixel. Entscheidend: Kennt die Kalibrierung (render_*.npz) den Fehler exakt, korrigiert die undistort-Kette ihn vollständig → kein Pose-Fehler. Den Fehler erzeugt nur die unvollständige Kalibrierung. Daher: nicht „Bild verzeichnen", sondern die npz-Intrinsik leicht von der Wahrheit abweichen lassen (Kalibrier-Restfehler).
2. Photometrische Fehler (Staub, Vignette, Rand-Unschärfe, Rauschen): ändern die npz nicht, erschweren nur die Detektion (verrauschte Ecken, fehlende Marker).

Hinweis: tote Parameter

In robot.json → renderingInfo existieren bereits, werden aber von render_robot.py nicht angewandt: lensDirt, lensDirtStrength, vignette, vignetteStrength, sensorNoise, sensorNoiseStrength, lensDistortion, lensDistortionStrength, localizedBlur, localizedBlurStrength. Diese zum Leben erwecken.

A — Kalibrier-Restfehler (geometrisch) ⭐ zuerst

Höchster Testwert, deckt eine Lücke der bisherigen Störungen ab. Modell-konsistent (kein Blender↔OpenCV-Mismatch), weil das Bild ideal bleibt und nur die angenommene Kalibrierung in der npz falsch ist.

Implementierung: im npz-Schreibblock von render_robot.py (~Zeile 460–510, wo camera_matrix/dist_coeffs gebaut werden) die Werte gezielt verrauschen — deterministisch pro Kamera (Seed aus Kameraposition/-id), damit über alle Posen konsistent.

Neue robot.json-Parameter (Vorschlag):

• focalErrorPct (z. B. 0.5) → fx,fy *= 1 ± rnd·focalErrorPct/100
• principalErrorPx (z. B. 3) → cx,cy += rnd·principalErrorPx
• residualDistortion (z. B. [0.02, -0.01]) → kleine k1,k2 in dist_coeffs, die die Pipeline „korrigiert", obwohl das Bild ideal ist (Rest-Verzeichnung)

B — Staub auf der Linse (photometrisch)

Halbtransparentes Schmutz-Overlay über dem ganzen Bild (Compositor), verdeckt zufällig Marker teilweise. Parameter: lensDirt, lensDirtStrength.

Implementierung: Compositor — RenderLayers → Mix (über eine prozedurale Fleckentextur, Voronoi/Noise mit hoher Schwelle) → Composite. Wenige, weiche, leicht abdunkelnde Flecken.

C — Vignette + Rand-Unschärfe (Feldkrümmung)

Randabdunklung und radial nach außen zunehmende Unschärfe (billige Linsen sind am Rand schlechter). Parameter: vignette/vignetteStrength, localizedBlur/localizedBlurStrength.

Implementierung: Compositor — Vignette via Ellipse-Maske × Bild; Rand-Unschärfe via CompositorNodeBlur gemischt über eine radiale Maske (Lens Distortion „Distort" auf einer Maske oder Ellipse-Maske als Mix-Faktor zwischen scharf und Blur).

D — Sensor-Rauschen + chromatische Aberration

Leichtes Pixelrauschen und Farbsäume an Kanten. Parameter: sensorNoise/sensorNoiseStrength, lensDistortion/lensDistortionStrength (Dispersion).

Implementierung: Compositor — additives Noise (klein) auf das Bild; chromatische Aberration via CompositorNodeLensdist mit kleinem dispersion-Wert.

Reihenfolge & Test

1. A (geometrisch, einfach, konsistent) — danach Benchmark mit vs. ohne laufen lassen.
2. B + C (Detektions-Robustheit).
3. D (Feinschliff).

Wichtig: Compositor-Node-API variiert leicht je Blender-Version — Code im echten Blender (4.5) gegenchecken. Determinismus pro Kamera nur bei A nötig (geometrische Konsistenz); B–D dürfen pro Aufnahme zufällig sein.