281 lines
8.0 KiB
Markdown
281 lines
8.0 KiB
Markdown
# 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`
|
||
|
||
```json
|
||
"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.
|
||
|
||
```json
|
||
"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.
|
||
|
||
```json
|
||
"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`
|
||
|
||
```json
|
||
"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.
|
||
|
||
```json
|
||
"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.
|
||
|
||
```json
|
||
"observation_weighting": {
|
||
"default": 1.0,
|
||
"per_link": { "Hand": 0.5 }
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `multiview_calculation`
|
||
|
||
Einstellungen für Schritt 3 (Bundle Adjustment über alle Kameras).
|
||
|
||
```json
|
||
"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.
|
||
|
||
```json
|
||
"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.
|
||
|
||
```json
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"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.
|