Initial commit
This commit is contained in:
chk
280
doc/robot_json.md
Normal file
280
doc/robot_json.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user