Hand-Auge-Kalibrierung

Für Anwendungen, bei denen die Kamera in eines oder mehrere Robotersysteme integriert wird, muss sie zum jeweiligen Roboter-Koordinatensystem kalibriert werden. Zu diesem Zweck wird der rc_cube mit einer internen Kalibrierroutine, dem Modul zur Hand-Auge-Kalibrierung, ausgeliefert. Dieses Modul ist ein Basismodul, welches auf jedem rc_cube verfügbar ist.

Bemerkung

Für die Hand-Auge-Kalibrierung ist es völlig unerheblich, in Bezug auf welches benutzerdefinierte Roboter-Koordinatensystem die Kamera kalibriert wird. Hierbei kann es sich um einen Endeffektor des Roboters (z.B. Flansch oder Tool Center Point (Werkzeugmittelpunkt)) oder um einen beliebigen anderen Punkt in der Roboterstruktur handeln. Einzige Voraussetzung für die Hand-Auge-Kalibrierung ist, dass die Pose (d.h. Positions- und Rotationswerte) dieses Roboter-Koordinatensystems in Bezug auf ein benutzerdefiniertes externes Koordinatensystem (z.B. Welt oder Roboter-Montagepunkt) direkt von der Robotersteuerung erfasst und an das Kalibriermodul übertragen werden kann.

Die Kalibrierroutine ist ein benutzerfreundliches dreistufiges Verfahren, für das mit einem Kalibriermuster gearbeitet wird. Entsprechende Kalibriermuster können von Roboception bezogen werden.

Kalibrierschnittstellen

Für die Durchführung der Hand-Auge-Kalibrierung stehen die folgenden beiden Schnittstellen zur Verfügung:

  1. Alle Services und Parameter dieses Moduls, die für eine programmgesteuerte Durchführung der Hand-Auge-Kalibrierung benötigt werden, sind in der REST-API-Schnittstelle des rc_cube enthalten. Der REST-API-Name dieses Moduls lautet rc_hand_eye_calibration und seine Services werden in Services erläutert.

    Bemerkung

    Für den beschriebenen Ansatz wird eine Netzwerkverbindung zwischen dem rc_cube und der Robotersteuerung benötigt, damit die Steuerung die Roboterposen an das Kalibriermodul des rc_cube übertragen kann.

  2. Für Anwendungsfälle, bei denen sich die Roboterposen nicht programmgesteuert an das Modul zur Hand-Auge-Kalibrierung des rc_cube übertragen lassen, sieht die Seite Hand-Auge-Kalibrierung unter dem Menüpunkt Konfiguration der Web GUI einen geführten Prozess vor, mit dem sich die Kalibrierroutine manuell durchführen lässt.

    Bemerkung

    Während der Kalibrierung muss der Benutzer die Roboterposen, auf die über das jeweilige Teach-in- oder Handheld-Gerät zugegriffen werden muss, manuell in die Web GUI eingeben.

Kameramontage

Wie in Abb. 24 und Abb. 26 dargestellt, ist für die Montage der Kamera zwischen zwei unterschiedlichen Anwendungsfällen zu unterscheiden:

  1. Die Kamera wird am Roboter montiert, d.h. sie ist mechanisch mit einem Roboterpunkt (d.h. Flansch oder flanschmontiertes Werkzeug) verbunden und bewegt sich demnach mit dem Roboter.
  2. Die Kamera ist nicht am Roboter montiert, sondern an einem Tisch oder anderen Ort in der Nähe des Roboters befestigt und verbleibt daher verglichen mit dem Roboter in einer statischen Position.

Die allgemeine Kalibrierroutine ist in beiden Anwendungsfällen sehr ähnlich. Sie unterscheidet sich jedoch hinsichtlich der semantischen Auslegung der Ausgabedaten, d.h. der erhaltenen Kalibriertransformation, und hinsichtlich der Befestigung des Kalibriermusters.

Kalibrierung einer robotergeführten Kamera

Soll eine robotergeführte Kamera zum Roboter kalibriert werden, so muss das Kalibriermuster in einer statischen Position zum Roboter, z.B. auf einem Tisch oder festen Sockel, befestigt werden (siehe Abb. 24).

Warnung

Es ist äußerst wichtig, dass sich das Kalibriermuster in Schritt 2 der Kalibrierroutine nicht bewegt. Daher wird dringend empfohlen, das Muster in seiner Position sicher zu fixieren, um unbeabsichtigte Bewegungen, wie sie durch Vibrationen, Kabelbewegungen oder Ähnliches ausgelöst werden, zu verhindern.

Das Ergebnis der Kalibrierung (Schritt 3 der Kalibrierroutine) ist eine Pose \(\mathbf{T}^{\text{robot}}_{\text{camera}}\), die die (zuvor unbekannte) relative Transformation zwischen dem Kamera-Koordinatensystem und dem benutzerdefinierten Roboter-Koordinatensystem beschreibt, sodass Folgendes gilt:

(3)\[\mathbf{p}_{\text{robot}} = \mathbf{R}^{\text{robot}}_{\text{camera}} \cdot \mathbf{p}_{\text{camera}} + \mathbf{t}^{\text{robot}}_{\text{camera}} \:,\]

wobei \(\mathbf{p}_{\text{robot}} = (x,y,z)^T\) ein 3D-Punkt ist, dessen Koordinaten im Roboter-Koordinatensystem angegeben werden, \(\mathbf{p}_{\text{camera}}\) denselben Punkt im Kamera-Koordinatensystem darstellt, und \(\mathbf{R}^{\text{robot}}_{\text{camera}}\) sowie \(\mathbf{t}^{\text{robot}}_{\text{camera}}\) die \(3\times 3\) Drehmatrix und den \(3\times 1\) Translationsvektor für eine Pose \(\mathbf{T}^{\text{robot}}_{\text{camera}}\) angeben. In der Praxis wird die Rotation für das Kalibrierergebnis und die Roboterposen als Eulerwinkel oder Quaternion anstatt einer Rotationsmatrix definiert (siehe Formate für Posendaten).

_images/sketch_handeye_calib_robotmounted_cube_de.svg

Abb. 24 Wichtige Koordinatensysteme und Transformationen für die Kalibrierung einer robotergeführten Kamera: Sie wird mit einer festen relativen Position zu einem benutzerdefinierten Roboter-Koordinatensystem (z.B. Flansch oder Werkzeugmittelpunkt) montiert. Es ist wichtig, dass die Pose \(\mathbf{T}^{\text{ext}}_{\text{robot}}\) des Roboter-Koordinatensystems in Bezug auf ein benutzerdefiniertes externes Referenzkoordinatensystem (ext) während der Kalibrierroutine gemessen werden kann. Das Ergebnis des Kalibriervorgangs ist die gewünschte Kalibriertransformation \(\mathbf{T}^{\text{robot}}_{\text{camera}}\), d.h. die Pose des Kamera-Koordinatensystems im benutzerdefinierten Roboter-Koordinatensystem.

Zusätzliche Benutzereingaben werden benötigt, falls die Bewegung des Roboters so beschränkt ist, dass der Tool Center Point (TCP) nur um eine Achse rotieren kann. Das ist üblicherweise für Roboter mit vier Freiheitsgraden (4DOF) der Fall, welche häufig zur Palettierung eingesetzt werden. In diesem Fall muss der Benutzer angeben, welche Achse des Roboterkoordinatensystems der Rotationsachse des TCP entspricht. Außerdem muss der vorzeichenbehaftete Offset vom TCP zum Kamerakoordinatensystem entlang der TCP-Rotationsachse angegeben werden. Abb. 25 zeigt die Situation.

Für den rc_visard befindet sich der Ursprung des Kamerakoordinatensystems im optischen Zentrum der linken Kamera. Die ungefähre Position wird im Abschnitt Coordinate Frames angegeben.

_images/sketch_handeye_calib_robotmounted_4dof_cube_de.svg

Abb. 25 Im Fall eines 4DOF-Roboters müssen die TCP-Rotationsachse und der Offset vom TCP zum Kamerakoordinatensystem entlang der TCP-Rotationsachse angegeben werden. Im dargestellten Fall ist der Offset negativ.

Kalibrierung einer statisch montierten Kamera

In Anwendungsfällen, bei denen die Kamera statisch verglichen zum Roboter montiert wird, muss das Kalibriermuster, wie im Beispiel in Abb. 26 und Abb. 27 angegeben, angebracht werden.

Bemerkung

Für das Modul zur Hand-Auge-Kalibrierung spielt es keine Rolle, wie das Kalibriermuster in Bezug auf das benutzerdefinierte Roboter-Koordinatensystem genau angebracht und positioniert wird. Das bedeutet, dass die relative Positionierung des Kalibriermusters zu diesem Koordinatensystem weder bekannt sein muss, noch für die Kalibrierroutine relevant ist (siehe in Abb. 27).

Warnung

Es ist äußerst wichtig, das Kalibriermuster sicher am Roboter anzubringen, damit sich seine relative Position in Bezug auf das in Schritt 2 der Kalibrierroutine vom Benutzer definierte Roboter-Koordinatensystem nicht verändert.

In diesem Anwendungsfall ist das Ergebnis der Kalibrierung (Schritt 3 der Kalibrierroutine) die Pose \(\mathbf{T}^{\text{ext}}_{\text{camera}}\), die die (zuvor unbekannte) relative Transformation zwischen dem Kamera-Koordinatensystem und dem benutzerdefinierten Roboter-Koordinatensystem beschreibt, sodass Folgendes gilt:

(4)\[\mathbf{p}_{\text{ext}} = \mathbf{R}^{\text{ext}}_{\text{camera}} \cdot \mathbf{p}_{\text{camera}} + \mathbf{t}^{\text{ext}}_{\text{camera}} \:,\]

wobei \(\mathbf{p}_{\text{ext}} = (x,y,z)^T\) ein 3D-Punkt im externen Referenzkoordinatensystem ext, \(\mathbf{p}_{\text{camera}}\) derselbe Punkt im Kamerakoordinatemsystem camera und \(\mathbf{R}^{\text{ext}}_{\text{camera}}\) sowie \(\mathbf{t}^{\text{ext}}_{\text{camera}}\) die \(3\times 3\) Rotationsmatrix und \(3\times 1\) Translationsvektor der Pose \(\mathbf{T}^{\text{ext}}_{\text{camera}}\) sind. In der Praxis wird die Rotation für das Kalibrierergebnis und die Roboterposen als Eulerwinkel oder Quaternion anstatt einer Rotationsmatrix definiert (siehe Formate für Posendaten).

_images/sketch_handeye_calib_static_cube_de.svg

Abb. 26 Wichtige Koordinatensysteme und Transformationen für die Kalibrierung einer statisch montierten Kamera: Sie wird mit einer festen Position relativ zu einem benutzerdefinierten externen Referenzkoordinatensystem ext (z.B. Weltkoordinatensystem oder Roboter-Montagepunkt) montiert. Es ist wichtig, dass die Pose \(\mathbf{T}^{\text{ext}}_{\text{robot}}\) des benutzerdefinierten Roboter-Koordinatensystems in Bezug auf dieses Koordinatensystem während der Kalibrierroutine gemessen werden kann. Das Ergebnis des Kalibrierprozesses ist die gewünschte Kalibriertransformation \(\mathbf{T}^{\text{ext}}_{\text{camera}}\), d.h. die Pose des Kamera-Koordinatensystems im benutzerdefinierten externen Koordinatensystem ext.

_images/sketch_handeye_calib_gridmount_cube_de.svg

Abb. 27 Alternative Montageoptionen für die Befestigung des Kalibriermusters am Roboter

Zusätzliche Benutzereingaben werden benötigt, falls die Bewegung des Roboters so beschränkt ist, dass der Tool Center Point (TCP) nur um eine Achse rotieren kann. Das ist üblicherweise für Roboter mit vier Freiheitsgraden (4DOF) der Fall, welche häufig zur Palettierung eingesetzt werden. In diesem Fall muss der Benutzer angeben, welche Achse des Roboterkoordinatensystems der Rotationsachse des TCP entspricht. Außerdem muss der vorzeichenbehaftete Offset vom TCP zur sichtbaren Oberfläche des Kalibriermusters entlang der TCP-Rotationsachse angegeben werden. Das Kalibriermuster muss so angebracht werden, dass die TCP-Rotationsachse orthogonal zum Kalibriermuster verläuft. Abb. 28 zeigt die Situation.

_images/sketch_handeye_calib_static_4dof_cube_de.svg

Abb. 28 Im Fall eines 4DOF-Roboters müssen die TCP-Rotationsachse und der Offset vom TCP zur sichtbaren Oberfläche des Kalibriermusters entlang der TCP-Rotationsachse angegeben werden. Im dargestellten Fall ist der Offset negativ.

Kalibrierroutine

Die allgemeine Hand-Auge-Kalibrierroutine besteht aus den in Abb. 29 angegebenen drei Schritten. Auch der Hand-Auge-Kalibriervorgang der Web GUI greift diese drei Schritte auf.

_images/sketch_handeye_calib_procedure_cube_de.svg

Abb. 29 Darstellung der drei Schritte der Hand-Auge-Kalibrierroutine

Schritt 1: Einstellung der Parameter

Bevor mit der eigentlichen Kalibrierroutine begonnen werden kann, müssen die Parameter für Kalibriermuster und Montage eingestellt werden. Für die REST-API sind die entsprechenden Parameter aufgelistet.

Web GUI-Beispiel:

Die Web GUI bietet eine Oberfläche, über die sich diese Parameter im ersten Schritt der Kalibrierroutine, wie in Abb. 30 gezeigt, erfassen lassen. Neben den Angaben zur Mustergröße und Kameramontage kann der Benutzer in der Web GUI auch die Kalibrierung von 4DOF-Robotern einstellen. In diesem Fall müssen die Rotationsachse, sowie der Offset vom TCP zum Kamerakoordinatensystem (für Kameras am Roboter) oder zur Oberfläche des Kalibriermusters (für statische Kameras) angegeben werden. Außerdem kann das Format für Posen eingestellt werden. Dieses Format wird im nachfolgenden Schritt 2 des Kalibriervorgangs verwendet, um die Roboterposen zu übertragen. Folgende Formate sind möglich: XYZABC für Positionen und Eulersche Winkel oder XYZ+Quaternion für Positionen samt Quaternionen für die Darstellung von Drehungen. Für die genauen Definitionen siehe Formate für Posendaten.

Bemerkung

Der Parameter Pose in der Web GUI wurde lediglich der Benutzerfreundlichkeit halber hinzugefügt. Für die programmgesteuerte Übertragung von Roboterposen über die REST-API ist die Verwendung des XYZ+Quaternion-Formats zwingend vorgeschrieben.

_images/webgui_hand_eye_calib1_cube_de.png

Abb. 30 Erfassung der Parameter zur Hand-Auge-Kalibrierung in der Web GUI des rc_cube

Schritt 2: Auswahl und Übertragung der Kalibrierpositionen des Roboters

In diesem Schritt (2a.) definiert der Benutzer verschiedene Kalibrierpositionen, die der Roboter anfahren muss. Dabei ist sicherzustellen, dass das Kalibriermuster bei allen Positionen im linken Kamerabild vollständig sichtbar ist. Zudem müssen die Roboterpositionen sorgsam ausgewählt werden, damit das Kalibriermuster aus unterschiedlichen Perspektiven aufgenommen wird. Abb. 31 zeigt eine schematische Darstellung der empfohlenen acht Ansichten.

_images/handeyecalib-alldraw.png

Abb. 31 Empfohlene Ansichten des Kalibriermusters während des Kalibriervorgangs. Im Fall von 4DOF-Robotern müssen andere Ansichten gewählt werden, welche so unterschiedlich wie möglich sein sollten.

Warnung

Die Kalibrierqualität, d.h. die Genauigkeit des berechneten Kalibrierergebnisses, hängt von den Ansichten des Kalibriermusters ab. Je vielfältiger die Perspektiven sind, desto besser gelingt die Kalibrierung. Werden sehr ähnliche Ansichten ausgewählt, d.h. werden die Positionen des Roboters bei den verschiedenen Wiederholungen von Schritt 2a nur leicht variiert, kann dies zu einer ungenauen Schätzung der gewünschten Kalibriertransformation führen.

Nachdem der Roboter die jeweilige Kalibrierposition erreicht hat, muss die entsprechende Pose \(\mathbf{T}^{\text{ext}}_{\text{robot}}\) des benutzerdefinierten Roboter-Koordinatensystems im benutzerdefinierten externen Referenzkoordinatensystem ext an das Modul zur Hand-Auge-Kalibrierung übertragen werden (2b.). Hierfür bietet das Softwaremodul verschiedene Slots, in denen die gemeldeten Posen mit den zugehörigen Bildern der linken Kamera hinterlegt werden können. Alle gefüllten Slots werden dann verwendet, um die gewünschte Kalibriertransformation zwischen dem Kamera-Koordinatensystem und dem benutzerdefinierten Roboter-Koordinatensystem (bei robotergeführten Kameras) bzw. dem benutzerdefinierten externen Referenzkoordinatensystem ext (bei statisch montierten Kameras) zu berechnen.

Bemerkung

Um die Transformation für die Hand-Auge-Kalibrierung erfolgreich zu berechnen, müssen mindestens drei verschiedenen Roboter-Kalibrierposen übertragen und in Slots hinterlegt werden. Um Kalibrierfehler zu verhindern, die durch ungenaue Messungen entstehen können, sind mindestens acht Kalibrierposen empfohlen.

Um diese Posen programmgesteuert zu übertragen, bietet die REST-API den Service set_pose (siehe Services).

Web GUI-Beispiel:

Nachdem die Kalibriereinstellungen in Schritt 1 abgeschlossen und die Schaltfläche Weiter betätigt wurde, bietet die Web GUI acht verschiedene Slots (Erste Ansicht, Zweite Ansicht, usw.), in die der Benutzer die Posen manuell eintragen kann. Ganz oben wird ein Live-Stream der Kamera angezeigt, um nachverfolgen zu können, ob das Kalibriermuster aktuell erkannt wird oder nicht. Neben jedem Slot wird eine Empfehlung für die Ansicht des Kalibriermusters angezeigt. Der Roboter sollte für jeden Slot so bewegt werden, dass die empfohlene Ansicht erreicht wird.

_images/webgui_hand_eye_calib2_cube_de.png

Abb. 32 Erstes Beispielbild für den Hand-Auge-Kalibriervorgang einer statisch montierten Kamera

Sobald das tatsächliche Bild der empfohlenen Ansicht entspricht, sind die Posen des benutzerdefinierten Roboter-Koordinatensystems manuell in den entsprechenden Textfeldern zu erfassen und das Kamerabild mit der Schaltfläche Bild aufnehmen aufzunehmen.

Bemerkung

Der Zugriff auf die Posendaten des Roboters hängt vom Modell des Roboters und seinem Hersteller ab. Möglicherweise lässt sich dies über ein im Lieferumfang des Roboters enthaltenes Teach-in- oder Handheld-Gerät vornehmen.

Warnung

Es ist sorgsam darauf zu achten, dass genaue und korrekte Werte eingegeben werden. Selbst kleinste Ungenauigkeiten oder Tippfehler können dazu führen, dass die Kalibrierung fehlschlägt.

Dieser Vorgang ist insgesamt achtmal zu wiederholen. Vorausgesetzt, die in Abb. 31 dargestellten Empfehlungen zur Aufnahme des Kalibriermusters aus verschiedenen Blickwinkeln jeweils aus der Nähe und aus der Ferne wurden eingehalten, werden die folgenden Kamerabilder mit den jeweiligen Roboterposen an das Softwaremodul zur Hand-Auge-Kalibrierung übertragen:

_images/handeyecalib-allpics.png

Abb. 33 Beispiel-Kamerabilder für die Hand-Auge-Kalibrierung

Schritt 3: Berechnen und Speichern der Kalibriertransformation

Der letzte Schritt in der Hand-Auge-Kalibrierroutine besteht darin, die gewünschte Kalibriertransformation auf Grundlage der erfassten Posen und Kamerabilder zu berechnen. Die REST-API bietet hierfür den Service calibrate (siehe Services). Je nachdem, wie die Kamera montiert ist, wird dabei die Transformation (d.h. die Pose) zwischen dem Kamera-Koordinatensystem und entweder dem benutzerdefinierten Roboter-Koordinatensystem (bei robotergeführten Kameras) oder dem benutzerdefinierten externen Referenzkoordinatensystem ext (bei statisch montierten Kameras) berechnet und ausgegeben (siehe Kameramontage).

Damit der Benutzer die Qualität der resultierenden Kalibriertransformation beurteilen kann, gibt das Modul die translatorischen und rotatorischen Kalibrierfehler an. Diese Werte werden aus der Varianz des Kalibrierergebnisses berechnet.

Web GUI-Beispiel:

Nachdem die letzte der acht Aufnahmen getätigt wurde, löst die Web GUI automatisch die Berechnung des Kalibrierergebnisses aus. Der Benutzer muss nur auf die Schaltfläche Weiter klicken, um zum Ergebnis zu gelangen. Der Benutzer hat die Möglichkeit die Einstellungen für 4DOF-Roboter anzugeben oder zu korrigieren. Nach jeder Änderung muss die Schaltfläche Neu berechnen angeklickt werden.

Im Beispiel in Abb. 34 ist 4DOF ausgeschaltet und die Kamera statisch montiert. Die resultierende Ausgabe ist die Pose der linken Kamera im externen Koordinatensystem des Roboters. Der angegebene translatorische Fehler ist 0.67 mm, der rotatorische Fehler ist 0.83 Grad.

_images/webgui_hand_eye_calib3_cube_de.png

Abb. 34 Ergebnis der Hand-Auge-Kalibrierung, dargestellt in der Web GUI

Parameter

Das Modul zur Hand-Auge-Kalibrierung wird in der REST-API als rc_hand_eye_calibration bezeichnet und in der Web GUI auf der Seite Hand-Auge-Kalibrierung unter dem Menüpunkt Konfiguration dargestellt. Der Benutzer kann die Kalibrierparameter entweder dort oder über die REST-API-Schnittstelle ändern.

Übersicht über die Parameter

Dieses Softwaremodul bietet folgende Laufzeitparameter:

Tab. 30 Laufzeitparameter des rc_hand_eye_calibration-Moduls
Name Typ Min. Max. Default Beschreibung
grid_height float64 0.0 10.0 0.0 Höhe des Kalibriermusters in Metern
grid_width float64 0.0 10.0 0.0 Breite des Kalibriermusters in Metern
robot_mounted bool false true true Angabe, ob der rc_visard auf einem Roboter montiert ist
tcp_offset float64 -10.0 10.0 0.0 Offset vom TCP entlang tcp_rotation_axis
tcp_rotation_axis int32 -1 2 -1 -1 für aus, 0 für x, 1 für y, 2 für z

Beschreibung der Laufzeitparameter

Für die Beschreibungen der Parameter sind die in der Web GUI gewählten Namen der Parameter in Klammern angegeben.

grid_width (Breite des Musters (m))

Breite des Kalibriermusters in Metern. Die Breite sollte mit sehr hoher Genauigkeit, vorzugsweise im Submillimeterbereich, angegeben werden.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/parameters?grid_width=<value>

grid_height (Höhe des Musters (m))

Höhe des Kalibriermusters in Metern. Die Höhe sollte mit sehr hoher Genauigkeit, vorzugsweise im Submillimeterbereich, angegeben werden.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/parameters?grid_height=<value>

robot_mounted (Kamera Montageart)

Ist dieser Parameter auf true gesetzt, dann ist die Kamera an einem Roboter montiert. Ist er auf false gesetzt, ist sie statisch montiert und das Kalibriermuster ist am Roboter angebracht.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/parameters?robot_mounted=<value>

tcp_offset (TCP Offset)

Der vorzeichenbehaftete Offset vom TCP zum Kamerakoordinatensystem (für Kameras auf dem Roboter) oder der sichtbaren Oberfläche des Kalibriermusters (für statische Kameras) entlang der TCP-Rotationsachse in Metern. Dies wird benötigt, falls die Roboterbewegung eingeschränkt ist, sodass der TCP nur um eine Achse gedreht werden kann (z.B. bei 4DOF-Robotern).

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/parameters?tcp_offset=<value>

tcp_rotation_axis (TCP-Rotationsachse)

Die Achse des Roboterkoordinatensystems, um die der Roboter seinen TCP drehen kann. 0 für X-, 1 für Y- und 2 für Z-Achse. Dies wird benötigt falls, die Roboterbewegung eingeschränkt ist, sodass der TCP nur um eine Achse gedreht werden kann (z.B. bei 4DOF-Robotern). -1 bedeutet, dass der Roboter seinen TCP um zwei unabhängige Achsen drehen kann. tcp_offset wird in diesem Fall ignoriert.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/parameters?tcp_rotation_axis=<value>

(Pose)

Der Benutzerfreundlichkeit halber kann der Benutzer die Kalibrierungsdaten in der Web GUI entweder im Format XYZABC oder im Format XYZ+Quaternion angeben (siehe Formate für Posendaten). Wird die Kalibrierung über die REST-API vorgenommen, dann wird das Kalibrierergebnis immer im Format XYZ+Quaternion angegeben.

Services

Auf die Services, die die REST-API für die programmgesteuerte Durchführung der Hand-Auge-Kalibrierung und für die Speicherung oder Wiederherstellung der Modulparameter bietet, wird im Folgenden näher eingegangen.

set_pose

Dieser Service setzt die Roboterpose als Kalibrierpose für die Hand-Auge-Kalibrierroutine.

Details

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/set_pose
Request
Response

Das slot-Argument wird verwendet, um den verschiedenen Kalibrierpositionen Ziffern zuzuordnen. Wann immer der Service set_pose aufgerufen wird, wird ein Kamerabild aufgezeichnet. Dieser Service schlägt fehl, wenn das Kalibriermuster im aktuellen Bild nicht erkannt werden kann.

Die Definition der Request-Argumente mit jeweiligen Datentypen ist:

{
  "args": {
    "pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "slot": "int32"
  }
}
Tab. 31 Rückgabewerte des set_pose-Services
status success Beschreibung
1 true Pose erfolgreich gespeichert
3 true Pose erfolgreich gespeichert. Es wurden genügend Posen für die Kalibrierung gespeichert, d.h. die Kalibrierung kann durchgeführt werden
4 false das Kalibriermuster wurde nicht erkannt, z.B. weil es im Kamerabild nicht vollständig sichtbar ist
8 false keine Bilddaten verfügbar
12 false die angegebenen Orientierungswerte sind ungültig

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "set_pose",
  "response": {
    "message": "string",
    "status": "int32",
    "success": "bool"
  }
}

calibrate

Dieser Service dient dazu, das Ergebnis der Hand-Auge-Kalibrierung auf Grundlage der über den Service set_pose konfigurierten Roboterposen zu berechnen und auszugeben.

Details

Damit die Kalibrierung für andere Module mit get_calibration verfügbar ist und persistent gespeichert wird, muss save_calibration aufgerufen werden.

Bemerkung

Zur Berechnung der Transformation der Hand-Auge-Kalibrierung werden mindestens drei Roboterposen benötigt (siehe set_pose). Empfohlen wird jedoch die Verwendung von acht Kalibrierposen.

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/calibrate
Request
Response
Dieser Service hat keine Argumente.

Das Feld error gibt den Kalibrierfehler in Pixeln an, der aus dem translatorischen Fehler translation_error_meter und dem rotatorischen Fehler rotation_error_degree berechnet wird. Dieser Wert wird nur aus Kompatibilitätsgründen mit älteren Versionen angegeben. Die translatorischen und rotatorischen Fehler sollten bevorzugt werden.

Tab. 32 Rückgabewerte des calibrate-Services
status success Beschreibung
0 true Kalibrierung erfolgreich, das Kalibrierergebnis wurde zurückgegeben.
1 false Nicht genügend Posen gespeichert, um die Kalibrierung durchzuführen
2 false Das berechnete Ergebnis ist ungültig, bitte prüfen Sie die Eingabewerte.
3 false Die angegebenen Abmessungen des Kalibriermusters sind ungültig.
4 false Ungenügende Rotation, tcp_offset and tcp_rotation_axis müssen angegeben werden
5 false Genügend Rotation verfügbar, tcp_rotation_axis muss auf -1 gesetzt werden
6 false Die Posen sind nicht unterschiedlich genug.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "calibrate",
  "response": {
    "error": "float64",
    "message": "string",
    "pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "robot_mounted": "bool",
    "rotation_error_degree": "float64",
    "status": "int32",
    "success": "bool",
    "translation_error_meter": "float64"
  }
}

save_calibration

Hiermit wird das Ergebnis der Hand-Auge-Kalibrierung persistent auf dem rc_cube gespeichert und das vorherige Ergebnis überschrieben. Das gespeicherte Ergebnis lässt sich jederzeit über den Service get_calibration abrufen.

Details

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/save_calibration
Request
Response
Dieser Service hat keine Argumente.
Tab. 33 Rückgabewerte des save_calibration-Services
status success Beschreibung
0 true die Kalibrierung wurde erfolgreich gespeichert
1 false die Kalibrierung konnte nicht im Dateisystem gespeichert werden
2 false die Kalibrierung ist nicht verfügbar

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "save_calibration",
  "response": {
    "message": "string",
    "status": "int32",
    "success": "bool"
  }
}

reset_calibration

Hiermit werden alle zuvor aufgenommenen Posen mitsamt der zugehörigen Bilder gelöscht. Das letzte hinterlegte Kalibrierergebnis wird neu geladen. Dieser Service kann verwendet werden, um die Hand-Auge-Kalibrierung (neu) zu starten.

Details

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/reset_calibration
Request
Response
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "reset_calibration",
  "response": {
    "message": "string",
    "status": "int32",
    "success": "bool"
  }
}

set_calibration

Hiermit wird die übergebene Transformation als Hand-Auge-Kalibrierung gesetzt.

Details

Die Kalibrierung wird im gleichen Format erwartet, in dem sie beim calibrate und get_calibration Aufruf zurückgegeben wird. Die gegebene Kalibrierung wird auch persistent gespeichert, indem intern save_calibration aufgerufen wird.

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/set_calibration
Request
Response

Die Definition der Request-Argumente mit jeweiligen Datentypen ist:

{
  "args": {
    "pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "robot_mounted": "bool"
  }
}
Tab. 34 Rückgabewerte des set_calibration-Services
status success Beschreibung
0 true Setzen der Kalibrierung war erfolgreich
12 false die angegebenen Orientierungswerte sind ungültig

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "set_calibration",
  "response": {
    "message": "string",
    "status": "int32",
    "success": "bool"
  }
}

remove_calibration

Dieser Service löscht die persistente Hand-Auge-Kalibrierung auf dem rc_cube. Nach diesem Aufruf gibt der get_calibration Service zurück, dass keine Hand-Auge-Kalibrierung vorliegt.

Details

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/remove_calibration
Request
Response
Dieser Service hat keine Argumente.
Tab. 35 Rückgabewerte des get_calibration-Services
status success Beschreibung
0 true persistente Kalibrierung gelöscht, Gerät nicht mehr kalibriert
1 true keine persistente Kalibrierung gefunden, Gerät nicht kalibriert
2 false die Kalibrierung konnte nicht gelöscht werden

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "remove_calibration",
  "response": {
    "message": "string",
    "status": "int32",
    "success": "bool"
  }
}

get_calibration

Hiermit wird die derzeit auf dem rc_cube gespeicherte Hand-Auge-Kalibrierung abgerufen.

Details

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/get_calibration
Request
Response
Dieser Service hat keine Argumente.

Das Feld error gibt den Kalibrierfehler in Pixeln an, der aus dem translatorischen Fehler translation_error_meter und dem rotatorischen Fehler rotation_error_degree berechnet wird. Dieser Wert wird nur aus Kompatibilitätsgründen mit älteren Versionen angegeben. Die translatorischen und rotatorischen Fehler sollten bevorzugt werden.

Tab. 36 Rückgabewerte des get_calibration-Services
status success Beschreibung
0 true eine gültige Kalibrierung wurde zurückgegeben
2 false die Kalibrierung ist nicht verfügbar

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "get_calibration",
  "response": {
    "error": "float64",
    "message": "string",
    "pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "robot_mounted": "bool",
    "rotation_error_degree": "float64",
    "status": "int32",
    "success": "bool",
    "translation_error_meter": "float64"
  }
}

save_parameters

Mit diesem Service werden die aktuellen Parametereinstellungen zur Hand-Auge-Kalibrierung auf dem rc_cube gespeichert. Das bedeutet, dass diese Werte selbst nach einem Neustart angewandt werden. Sie bleiben auch bei Firmware-Updates oder -Wiederherstellungen bestehen.

Details

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/save_parameters
Request
Response
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "save_parameters",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

reset_defaults

Hiermit werden die Werkseinstellungen der Parameter dieses Moduls wieder hergestellt und angewandt („factory reset“). Dies hat keine Auswirkungen auf das Kalibrierergebnis oder auf die während der Kalibrierung gefüllten Slots. Es werden lediglich Parameter, wie die Maße des Kalibriermusters oder die Montageart des Sensors, zurückgesetzt.

Details

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_hand_eye_calibration/services/reset_defaults
Request
Response
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "reset_defaults",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}