appRobotBodyTrack

3D-Body-Tracking für Roboter aus Mehrkamera-ArUco-Bildern.

Input

• Bilder: render_*.png
• Intrinsics: render_*.npz
• Konfiguration: robot.json

Output

• Gelenke R⁷ → {x, y, z, a, b, c, e} (mm / Grad)

---

Interfaces

Eine Logik, drei Zugänge:

• Python
• CLI
• REST (FastAPI)

---

Quickstart

Python

from scripts import estimate_from_dir

result = estimate_from_dir("data/Scene8", robot_json="robot.json")

print(result.joints)
print(result.confidence)

---

CLI

pip install -e .

python -m scripts data/Scene8 --robot robot.json
python -m scripts data/Scene8 --robot robot.json --cameras a,b,d

---

REST API

docker compose up

Request:

import requests

resp = requests.post(
    "http://localhost:8446/v1/estimate",
    files=[
        ("images", ("render_a.png", open("render_a.png", "rb"))),
        ("intrinsics", ("render_a.npz", open("render_a.npz", "rb"))),
    ],
)

print(resp.json()["joints"])

---

API

Endpoint	Methode	Zweck
/v1/estimate	POST	Bilder → Gelenke
/v1/health	GET	Status
/v1/config	GET	aktive Konfiguration

Maschinenlesbares Schema / interaktive Doku (automatisch von FastAPI):

URL	Zweck
/openapi.json	OpenAPI-Spezifikation (für Client-Generatoren)
/docs	Swagger-UI (interaktiv ausprobieren)
/redoc	ReDoc-Ansicht

Response:

{
  "joints": {"x": 50.2, "y": -2.1, "z": 94.8, "a": 20.1},
  "confidence": {"x": "high", "b": "low"},
  "residual_rms": 1.45,
  "n_markers": 56,
  "processing_ms": 1240
}

---

Struktur

.
├── scripts/
├── config/robot.json
├── tests/
└── docker-compose.yaml

---

Deployment (Docker / Portainer)

Die config/robot.json wird beim Build mit ins Image gebacken (COPY . .) und liegt dort fest unter /app/config/robot.json. Damit läuft der Container out-of-the-box — kein Bind-Mount nötig, auch nicht als Portainer-Stack.

Voraussetzung: config/robot.json muss zum Build-Zeitpunkt als Datei vorhanden sein. Falls nicht: cp config/robot.json.example config/robot.json und mit der echten Konfiguration füllen.

Start & Healthcheck:

docker compose up -d
curl http://<host>:8446/v1/health     # {"status":"ok","version":"1.0.0"}

Eigene robot.json ohne Rebuild (optional): die eingebackene Kopie per Mount überlagern — siehe auskommentierter volumes-Block in docker-compose.yaml.

⚠️ Portainer-Falle: Ein Bind-Mount auf einen Host-Pfad, der nicht existiert, lässt Docker dort ein leeres Verzeichnis anlegen. Die Pipeline liest es dann als Datei → IsADirectoryError → jeder /v1/estimate und /v1/config antwortet mit 500. Deshalb ist der Mount jetzt optional; aktiviere ihn nur, wenn die Datei am Host-Pfad wirklich liegt.

---

Konfiguration

Zentrale Datei: robot.json

Verwendete Bereiche:

• links
• pose_estimation
• vision_config
• movements
• units

---

Stack (minimal)

• numpy
• scipy
• opencv (aruco)
• fastapi + uvicorn

---

Naming

• BodyTrack → Tracking (dynamisch) ✅
• BodyMap → Modell / Repräsentation
• BodySense → Wahrnehmung (low-level)