8.0 KiB
robot.json — Entwurf und Schema
Entwurfsprinzip: Eine Datei pro Roboter
robot.json ist die zentrale Identitätsdatei des Roboters. Sie beschreibt
alles, was zum Roboter gehört — Kinematik, Marker, Kamera-Setup, Rendering-Parameter
und Algorithmus-Tuning. Es gibt genau eine Datei pro Roboter.
robot.json → Pipeline-Service (liest: links, vision_config, pose_estimation, ...)
→ Blender-Renderer (liest: links, renderingInfo, robot_test_poses, ...)
→ Benchmark-Tools (liest: robot_test_poses, test_camera_positions, ...)
Jeder Konsument liest nur seine Abschnitte und ignoriert alle anderen stillschweigend.
Das macht robot.json additiv erweiterbar: neue Tools fügen neue Abschnitte hinzu,
ohne bestehende zu berühren.
Roboter wechseln = robot.json austauschen.
Alle Werkzeuge der Umgebung stellen sich damit automatisch auf den neuen Roboter ein.
Abschnitts-Übersicht
| Abschnitt | Pipeline | Renderer | Benchmark | Beschreibung |
|---|---|---|---|---|
units |
✅ | ✅ | ✅ | Maßeinheiten (mm, deg) |
coordinateSystem |
✅ | ✅ | — | Basis-Koordinatensystem |
links |
✅ | ✅ | — | Kinematische Kette + ArUco-Marker |
movements |
✅ | ✅ | ✅ | Gelenkachsen-Definition, Ausgabeformat |
vision_config |
✅ | — | — | ArUco-Dictionary, Markergröße |
pose_estimation |
✅ | — | — | Algorithmus-Parameter |
constraint_rules |
✅ | — | — | Gelenkwinkel-Grenzen |
observation_weighting |
✅ | — | — | Gewichtung pro Gelenk/Beobachtungstyp |
multiview_calculation |
✅ | — | — | Bundle-Adjustment-Einstellungen |
renderingInfo |
— | ✅ | — | Blender-Szene, Kamera-Rig, Materialien |
robot_test_poses |
— | ✅ | ✅ | Teststellungen für Rendering / Evaluierung |
test_camera_positions |
— | ✅ | ✅ | Kamera-Aufstellungen für Tests |
test_camera_targets |
— | ✅ | — | Blickziele der Test-Kameras |
state_pose_params |
✅ | ✅ | — | Parameterraum-Definition (R⁷) |
defaultPosition |
✅ | ✅ | — | Referenz-Nullstellung |
Pflichtabschnitte
units
"units": {
"length": "mm",
"angle": "deg"
}
Definiert die Einheiten für alle Längen- und Winkelangaben in der gesamten Datei.
links
Kinematische Kette des Roboters, von der Basis zum Endeffektor. Jedes Glied kennt sein Gelenk, seine Transformation in Nullstellung und die auf ihm montierten ArUco-Marker.
"links": [
{
"name": "Base",
"joint": "x",
"joint_type": "prismatic",
"axis": [0, 0, 1],
"T_parent_link_home": [
[1, 0, 0, 0],
[0, 1, 0, 0],
[0, 0, 1, 100],
[0, 0, 0, 1]
],
"markers": [
{
"id": 0,
"size_mm": 60.0,
"T_link_marker": [
[1, 0, 0, 0],
[0, 1, 0, 50],
[0, 0, 1, 0],
[0, 0, 0, 1]
]
}
]
}
]
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
name |
string | ✅ | Name des Glieds |
joint |
string | ✅ | Gelenkvariable: x, y, z, a, b, c, e |
joint_type |
string | ✅ | "prismatic" oder "revolute" |
axis |
[x,y,z] | ✅ | Gelenkachse im Eltern-KS |
T_parent_link_home |
4×4 | ✅ | Transformation Eltern→Glied in Nullstellung |
markers |
Array | — | ArUco-Marker auf diesem Glied (kann leer sein) |
markers[].id |
int | ✅ | ArUco-Marker-ID |
markers[].size_mm |
float | ✅ | Kantenlänge in mm |
markers[].T_link_marker |
4×4 | ✅ | Transformation Glied→Marker-Mittelpunkt |
movements
Definiert die sieben Gelenkachsen des Roboters, ihre physikalischen Grenzen
und wie sie im Output (robot_state.json) benannt und geordnet werden.
"movements": {
"x": { "type": "prismatic", "min_mm": 0, "max_mm": 800 },
"y": { "type": "prismatic", "min_mm": -400, "max_mm": 400 },
"z": { "type": "prismatic", "min_mm": 0, "max_mm": 1200 },
"a": { "type": "revolute", "min_deg": -180,"max_deg": 180 },
"b": { "type": "revolute", "min_deg": -90, "max_deg": 90 },
"c": { "type": "revolute", "min_deg": -90, "max_deg": 90 },
"e": { "type": "revolute", "min_deg": 0, "max_deg": 90 }
}
Pipeline-Abschnitte
vision_config
"vision_config": {
"aruco_dict": "DICT_4X4_250",
"marker_size_mm": 20.0
}
| Feld | Default | Beschreibung |
|---|---|---|
aruco_dict |
"DICT_4X4_250" |
OpenCV-ArUco-Dictionary |
marker_size_mm |
aus links[].markers[].size_mm |
Globale Fallback-Markergröße |
pose_estimation
Algorithmus-Parameter für die Gelenkwinkelschätzung. Alle Felder haben Defaults — fehlende Felder werden still ignoriert.
"pose_estimation": {
"method": "hybrid",
"marker_observation": "corner_pose",
"use_normals": true,
"normal_weight": 100.0,
"robust_loss": "huber",
"huber_delta_mm": 8.0,
"max_iterations": 200,
"min_cameras_per_marker": 2,
"per_link_method": {}
}
| Feld | Default | Beschreibung |
|---|---|---|
method |
"hybrid" |
sequential_fk / global_ba / hybrid |
marker_observation |
"corner_pose" |
"corner_pose" (pos+normal) oder "center_point" (pos only) |
use_normals |
true |
Marker-Flächennormalen als Zusatz-Constraint |
normal_weight |
100.0 |
Gewicht Normal-Residuen vs. Positions-Residuen |
robust_loss |
"huber" |
"none" / "huber" / "cauchy" |
huber_delta_mm |
8.0 |
Huber-Schwelle in mm |
max_iterations |
200 |
Bundle-Adjustment-Iterationslimit |
min_cameras_per_marker |
2 |
Mindestanzahl Kameras für Triangulation |
per_link_method |
{} |
Override pro Gelenk, z.B. {"e": "sequential_fk"} |
observation_weighting
Gewichtung der einzelnen Marker-Beobachtungen in der Schätzung, z.B. um bekannte schwache Geometrien zu dämpfen.
"observation_weighting": {
"default": 1.0,
"per_link": { "Hand": 0.5 }
}
multiview_calculation
Einstellungen für Schritt 3 (Bundle Adjustment über alle Kameras).
"multiview_calculation": {
"lambda_weight": 100.0,
"min_views": 2
}
constraint_rules
Gelenkwinkel-Abhängigkeiten und -Grenzen, die in der Schätzung als Hard- oder Soft-Constraints wirken.
"constraint_rules": [
{ "joint": "b", "min_deg": 0, "max_deg": 180 }
]
Renderer-Abschnitte
renderingInfo
Blender-spezifische Szenenparameter: Pfad zur .blend-Datei, Materialien,
Beleuchtungssetup, Auflösung und Kamera-Rig-Konfiguration.
Wird von der Pipeline vollständig ignoriert.
robot_test_poses
Liste von Roboterstellungen, die im Renderer gerendert und in der Evaluierung als Ground-Truth verwendet werden. Jeder Eintrag ist ein vollständiger R⁷-Zustand.
"robot_test_poses": [
{ "x": 50, "y": 0, "z": 600, "a": 30, "b": 45, "c": 0, "e": 20 },
{ "x": 200, "y": -100, "z": 700, "a": -15, "b": 60, "c": 10, "e": 0 }
]
test_camera_positions
Kamera-Aufstellungen für den Renderer, als Liste von 3D-Positionen und Ausrichtungen.
Extensibilität
Neue Tools oder Features fügen neue Abschnitte hinzu, ohne bestehende zu ändern:
{
"units": { ... }, // alle Tools
"links": [ ... ], // alle Tools
"pose_estimation": { ... },// Pipeline
"renderingInfo": { ... }, // Renderer
"my_new_tool": { ... } // neues Tool — alle anderen ignorieren es
}
Versionsregel: Neue Felder innerhalb bestehender Abschnitte haben immer Defaults.
Felder werden nie entfernt, nur als veraltet markiert. Eine ältere robot.json
läuft damit auf einer neueren Pipeline-Version unverändert.
Roboter wechseln
Um auf einen anderen Roboter umzustellen, wird ausschließlich robot.json ausgetauscht:
robot_A.json → robot.json # Roboter A aktiv
robot_B.json → robot.json # Roboter B aktiv
Pipeline, Renderer, Benchmark-Tools und Portainer-Stack lesen denselben
Volume-Mount /config/robot.json — kein weiterer Eingriff nötig.