TagDetect

Einführung

Die TagDetect-Module sind optionale Module, die intern auf dem rc_visard laufen, und benötigen gesonderte Lizenzen, die erworben werden müssen. Diese Lizenzen sind auf jedem rc_visard, der nach dem 01.07.2020 gekauft wurde, vorhanden.

Die TagDetect-Module laufen intern auf dem rc_visard und ermöglichen es, 2D-Barcodes und Marker zu erkennen. Derzeit gibt es TagDetect-Module für QR-Codes und AprilTags. Neben der Erkennung berechnen die Module die Position und Orientierung jedes Markers im 3D-Kamerakoordinatensystem, um diesen beispielsweise mit einem Roboter zu manipulieren oder die Pose der Kamera in Bezug auf den Marker zu berechnen.

Die Markererkennung besteht aus drei Schritten:

  1. Markererkennung auf dem 2D-Bildpaar (siehe Markererkennung).
  2. Schätzung der Pose jedes Markers (siehe Posenschätzung).
  3. Wiedererkennung von bisher gesehenen Markern (siehe Marker-Wiedererkennung).

Im Folgenden werden die zwei unterstützten Markertypen näher beschrieben, gefolgt von einem Vergleich.

QR-Code

_images/example_qr_code.png

Abb. 28 Beispiel eines QR-Codes

QR-Codes sind zweidimensionale Barcodes, welche beliebige, benutzerspezifizierte Daten enthalten können. Viele Alltagsgeräte, wie beispielsweise Smartphones, unterstützen die Erkennung von QR-Codes. Zusätzlich stehen Online- und Offlinetools zur Verfügung, um QR-Codes zu generieren.

Die „Pixel“ eines QR-Codes werden Module genannt. Das Aussehen und die Auflösung von QR-Codes ändert sich mit der Menge der in ihnen gespeicherten Daten. Während die speziellen Muster in den drei Ecken immer 7 Module breit sind, erhöht sich die Anzahl der Module dazwischen, je mehr Daten gespeichert sind. Der am niedrigsten aufgelöste QR-Code besitzt eine Größe von 21x21 Modulen und kann bis zu 152 Bits speichern.

Auch wenn viele QR-Code-Generatoren speziell designte QR-Codes erzeugen können (bspw. mit einem Logo, mit runden Ecken oder mit Punkten als Module), wird eine zuverlässige Erkennung solcher Marker mit dem TagDetect-Modul nicht garantiert. Gleiches gilt für QR-Codes, welche Zeichen außerhalb des ASCII-Zeichensatzes beinhalten.

AprilTag

_images/apriltag_dim_vis.png

Abb. 29 Ein 16h5 Marker (links) und ein 36h11 Marker (rechts). AprilTags bestehen aus einem obligatorischen weißen (a) und schwarzen (b) Rahmen und einer variablen Menge an Datenmodulen (c).

AprilTags sind ähnlich zu QR-Codes. Sie wurden allerdings speziell zur robusten Identifikation auf weite Entfernungen entwickelt. Wie bei QR-Codes werden die „Pixel“ Module genannt. Abb. 29 veranschaulicht den Aufbau von AprilTags. Sie sind von einem obligatorischen weißen und schwarzen Rahmen umschlossen, welcher jeweils ein Modul breit ist. Innen enthalten sie eine variable Menge an Datenmodulen. Anders als QR-Codes speichern sie keine benutzerdefinierten Informationen, sondern werden durch eine vordefinierte Familie und ID identifiziert. Die Tags in Abb. 29 sind zum Beispiel aus Familie 16h5 bzw. 35h11 und besitzen ID 0 bzw. 11. Alle unterstützten Familien werden in Tab. 23 aufgelistet.

Tab. 23 AprilTag-Familien
Familie Anzahl IDs Empfohlen
16h5 30 -
25h7 242 -
25h9 35 o
36h10 2320 o
36h11 587 +

Die Zahl vor dem „h“ jeder Familie bezeichnet die Anzahl der Datenmodule, welche im Marker enthalten sind: Während ein 16h5 Marker 16 (4x4) Datenmodule enthält ((c) in Abb. 29), besteht ein 36h11 Marker aus 36 (6x6) Datenmodulen. Die Zahl hinter dem „h“ bezeichnet den Hamming-Abstand zwischen zwei Markern der Familie. Je höher, desto höher ist die Robustheit, aber desto weniger IDs stehen bei gleicher Anzahl an Datenmodulen zur Verfügung (siehe Tab. 23).

Der Vorteil von Familien mit weniger Datenmodulen (bspw. 16h5 im Vergleich zu 36h11) ist die niedrigere Auflösung der Marker. Jedes Modul ist somit größer, weshalb der Marker auf eine größere Distanz erkannt werden kann. Dies hat allerdings auch Nachteile: Zum einen stehen bei niedrigerer Zahl an Datenmodulen auch weniger IDs zur Verfügung. Wichtiger aber ist, dass die Robustheit der Markererkennung signifikant reduziert wird, da es zu einer höheren Falsch-Positiv-Rate kommt. Dies bedeutet, dass Marker verwechselt werden oder nicht existierende Marker in zufälliger Bildtextur oder im Bildrauschen erkannt werden.

Aus diesen Gründen empfehlen wir die Verwendung der 36h11-Familie und raten ausdrücklich von den Familien 16h5 und 25h7 ab. Letztgenannte Familien sollten nur benutzt werden, wenn eine große Erkennungsdistanz für die Anwendung unbedingt erforderlich ist. Jedoch ist die maximale Erkennungsdistanz nur ca. 25% größer, wenn anstelle der 36h11-Familie die 16h5-Familie verwendet wird.

Vorgenerierte AprilTags können von der AprilTag-Projektwebseite (https://april.eecs.umich.edu/software/apriltag.html) heruntergeladen werden. Jede Familie besteht aus mehreren PNGs, welche jeweils einen AprilTag enthalten, und einem PDF, welches jeden AprilTag auf einer eigenen Seite enthält. Jedes Pixel im PNG entspricht dabei einem Modul des AprilTags. Beim Drucken der Marker sollte darauf geachtet werden, den weißen Rand um den AprilTag mit einzuschließen – dieser ist sowohl in den PNGs also auch in den PDFs enthalten (siehe (a) in Abb. 29). Die Marker müssen außerdem ohne Interpolation auf die Druckgröße skaliert werden, sodass die scharfen Kanten erhalten bleiben.

Vergleich

Sowohl QR-Codes als auch AprilTags haben ihre Vor- und Nachteile. Während QR-Codes die Speicherung von benutzerdefinierten Daten erlauben, sind die Marker bei AprilTags vordefiniert und in ihrer Anzahl limitiert. Andererseits haben AprilTags eine niedrigere Auflösung und können daher auf eine größere Distanz erkannt werden. Zusätzlich hilft die jeden Apriltag nach außen hin begrenzende, durchgängige weiß-zu-schwarz-Kante bei einer präziseren Posenschätzung.

Bemerkung

Falls die Speicherung von benutzerdefinierten Daten nicht benötigt wird, sollten AprilTags QR-Codes vorgezogen werden.

Markererkennung

Der erste Schritt der Markererkennung ist die Detektion der Marker auf dem Stereo-Bildpaar. Dieser Schritt benötigt die meiste Zeit und seine Präzision ist entscheidend für die Präzision der finalen Markerpose. Um die Dauer dieses Schritts zu kontrollieren, kann der Parameter quality vom Benutzer konfiguriert werden. Er hat ein Herunterskalieren des Stereo-Bildpaares vor der Markererkennung zur Folge. Hoch (High) ergibt die höchste maximale Erkennungssdistanz und Präzision, aber auch die längste Dauer der Erkennung. Niedrig (Low) führt zur kleinsten maximalen Erkennungsdistanz und Präzision, aber benötigt auch nur weniger als die halbe Zeit. Mittel (Medium) liegt dazwischen. Es sollte beachtet werden, dass dieser quality-Parameter keine Verbindung zum quality-Parameter des Stereo-Matching hat.

_images/tag_sizes_vis.png

Abb. 30 Visualisierung der Modulgröße \(s\), der Größe eines Markers in Modulen \(r\) und der Größe eines Markers in Metern \(t\) für QR-Codes (links) und AprilTags (rechts)

Die maximale Erkennungsdistanz \(z\) für Qualität Hoch (High) kann mit folgenden Formeln angenähert werden:

\[z = \frac{f s}{p},\]
\[s = \frac{t}{r},\]

wobei \(f\) die Brennweite in Pixeln und \(s\) die Größe jedes Moduls in Metern bezeichnet. \(s\) kann leicht mit letztgenannter Formel berechnet werden, in welcher \(t\) der Markergröße in Metern und \(r\) der Breite des Markers in Modulen entspricht (bei AprilTags ohne den weißen Rahmen). Abb. 30 veranschaulicht diese Variablen. \(p\) bezeichnet die Zahl der Bildpixel pro Modul, welche für eine Erkennung erforderlich sind. Sie unterscheidet sich zwischen QR-Codes und AprilTags. Auch der Winkel des Markers zur Kamera und die Beleuchtung spielen eine Rolle. Ungefähre Werte für eine robuste Erkennung sind:

  • AprilTag: \(p=5\) Pixel/Modul
  • QR-Code: \(p=6\) Pixel/Modul

Die folgenden Tabellen enthalten Beispiele für die maximale Erkennungsdistanz in unterschiedlichen Situationen. Die Brennweite des rc_visard wird dafür mit 1075 Pixeln, die Qualität mit High angenommen.

Tab. 24 Beispiele zur maximalen Erkennungsdistanz für AprilTags mit einer Breite von \(t=4\) cm
AprilTag-Familie Markerbreite Maximale Distanz
36h11 (empfohlen) 8 Module 1.1 m
16h5 6 Module 1.4 m
Tab. 25 Beispiele zur maximalen Erkennungsdistanz für QR-Codes mit einer Breite von \(t=8\) cm
Markerbreite Maximale Distanz
29 Module 0.49 m
21 Module 0.70 m

Posenschätzung

Für jeden erkannten Marker wird dessen Pose im Kamerakoordinatensystem geschätzt. Eine Bedingung dafür ist, dass der Marker vollständig im linken und rechten Bild zu sehen ist. Das Koordinatensystem ist wie unten gezeigt am Marker ausgerichtet.

_images/tag_coord_frames.png

Abb. 31 Koordinatensysteme für AprilTags (links) bzw. QR-Codes (rechts)

Die z-Achse zeigt „in“ den Marker. Es ist zu beachten, dass, auch wenn AprilTags den weißen Rand in ihrer Definition enthalten, der Ursprung des Koordinatensystems trotzdem am Übergang des weißen zum schwarzen Rand liegt. Da AprilTags keine offensichtliche Orientierung haben, liegt der Ursprung in der oberen linken Ecke des vorgenerierten AprilTags.

Während der Posenschätzung wird auch die Größe des Markers geschätzt unter der Annahme, dass der Marker quadratisch ist. Bei QR-Codes bezieht sich die Größe auf den gesamten Marker, bei AprilTags dagegen nur auf den schwarzen Rand und nicht auf den äußeren weißen.

Der Benutzer kann auch die ungefähre Größe (\(\pm 10\%\)) eines Markers angeben. Alle Marker, die dieser Einschränkung nicht entsprechen, werden automatisch herausgefiltert. Weiter hilft diese Information in bestimmten Situationen, Mehrdeutigkeiten in der Posenschätzung aufzulösen, die entstehen können, wenn mehrere Marker mit derselben ID im linken und rechten Bild sichtbar und diese Marker parallel zu den Bildzeilen ausgerichtet sind.

Bemerkung

Für beste Ergebnisse der Posenschätzung sollte der Marker sorgfältig gedruckt und auf einem steifen und möglichst ebenen Untergrund angebracht werden. Jegliche Verzerrung des Markers oder Unebenheit der Oberfläche verschlechtert die geschätzte Pose.

Warnung

Wir empfehlen, die ungefähre Größe der Marker anzugeben. Ansonsten, falls mehrere Marker mit derselben ID im linken oder rechten Bild sichtbar sind, kann es zu einer fehlerhaften Posenschätzung kommen, wenn die Marker gleich orientiert sind und sie ungefähr parallel zu den Bildzeilen angeordnet sind. Auch wenn die Größe nicht angegeben sein sollte, versuchen die TagDetect-Module jedoch, solche Situationen zu erkennen und verwerfen betroffene Marker.

Unten stehende Tabellen enthalten grobe Angaben zur Präzision der geschätzten Posen von AprilTags und QR-Codes. Wir unterscheiden zwischen lateraler Präzision (also in x- und y-Richtung) und Präzision in z-Richtung. Es wird angenommen, dass quality auf High gesetzt ist, und dass die Blickrichtung der Kamera parallel zur Normalen des Markers ist. Die Größe eines Markers hat keinen signifikanten Einfluss auf die Präzision in lateraler und z-Richtung. Im Allgemeinen verbessert ein größerer Marker allerdings die Präzision. Im Bezug auf die Präzision der Rotation, im speziellen um die x- und y-Achsen, übertreffen große Marker kleinere deutlich.

Tab. 26 Ungefähre Präzision der Pose von AprilTags
Distanz rc_visard 65 - lateral rc_visard 65 - z rc_visard 160 - lateral rc_visard 160 - z
0.3 m 0.4 mm 0.9 mm 0.4 mm 0.8 mm
1.0 m 0.7 mm 3.3 mm 0.7 mm 3.3 mm
Tab. 27 Ungefähre Präzision der Pose von QR-Codes
Distanz rc_visard 65 - lateral rc_visard 65 - z rc_visard 160 - lateral rc_visard 160 - z
0.3 m 0.6 mm 2.0 mm 0.6 mm 1.3 mm
1.0 m 2.6 mm 15 mm 2.6 mm 7.9 mm

Marker-Wiedererkennung

Jeder Marker besitzt eine ID: bei AprilTags ist dies die Familie zusammen mit der AprilTag-ID, bei QR-Codes die enthaltenen Daten. Diese IDs sind jedoch nicht einzigartig, da mehrere Marker mit derselben ID in einer Szene vorkommen können.

Zur Unterscheidung dieser Marker weisen die TagDetect-Module jedem Marker einen eindeutigen Identifikator zu. Um den Benutzer dabei zu unterstützen, denselben Marker über mehrere Markererkennungsläufe hinweg zu identifizieren, versucht das TagDetect-Modul Marker wiederzuerkennen. Falls erfolgreich, wird einem Marker derselbe Identifikator zugewiesen.

Die Marker-Wiedererkennung vergleicht die Positionen der Ecken der Marker in einem statischen Koordinatensystem, um identische Marker wiederzufinden. Marker werden als identisch angenommen, falls sie sich nicht oder nur geringfügig in diesem statischen Koordinatensystem bewegt haben. Damit das statische Koordinatensystem verfügbar ist, muss das Dynamik-Modul angeschaltet sein. Falls dies nicht der Fall ist, wird der Sensor als statisch angenommen. Die Marker-Wiedererkennung funktioniert in diesem Fall nicht über Bewegungen des Sensors hinweg.

Über den max_corner_distance-Parameter kann der Benutzer festlegen, wie weit ein Marker sich zwischen zwei Erkennungsläufen bewegen darf, um als identisch zu gelten. Der Parameter definiert die maximale Distanz zwischen den Ecken zweier Marker, was in Abb. 32 dargestellt ist. Die euklidischen Abstände der vier zusammengehörenden Markerecken in 3D werden berechnet. Falls keiner dieser Abstände den Grenzwert überschreitet, gilt der Marker als wiedererkannt.

_images/tag-re-identification.png

Abb. 32 Vereinfachte Darstellung der Marker-Wiedererkennung. Die euklidischen Abstände zwischen zusammengehörigen Markerecken in 3D werden berechnet (rote Pfeile).

Nach einer bestimmten Anzahl von Markererkennungsläufen werden vorher gesehene Marker verworfen, falls diese in der Zwischenzeit nicht mehr erkannt wurden. Dies kann über den Parameter forget_after_n_detections festgelegt werden.

Hand-Auge-Kalibrierung

Falls die Kamera zu einem Roboter kalibriert wurde, kann das TagDetect-Modul automatisch Posen im Roboterkoordinatensystem ausgeben. Für die Services kann das Koordinatensystem der berechneten Posen mit dem Argument pose_frame spezifiziert werden.

Zwei verschiedene pose_frame-Werte können gewählt werden:

  1. Kamera-Koordinatensystem (camera): Alle Posen sind im Kamera-Koordinatensystem angegeben.
  2. Benutzerdefiniertes externes Koordinatensystem (external): Alle Posen sind im sogenannten externen Koordinatensystem angegeben, welches vom Nutzer während der Hand-Auge-Kalibrierung gewählt wurde. In diesem Fall bezieht das Modul alle notwendigen Informationen über die Kameramontage und die kalibrierte Hand-Auge-Transformation automatisch vom Modul Hand-Auge-Kalibrierung. Für den Fall einer robotergeführten Kamera ist vom Nutzer zusätzlich die jeweils aktuelle Roboterpose robot_pose anzugeben.

Zulässige Werte zur Angabe des Referenzkoordinatensystems sind camera und external. Andere Werte werden als ungültig zurückgewiesen.

Parameter

Es stehen zwei getrennte Module für die Markererkennung zur Verfügung, eines für AprilTag- und eines für QR-Code-Erkennung: rc_april_tag_detect bzw. rc_qr_code_detect. Abgesehen vom Modulnamen teilen beide die gleiche Schnittstellendefinition.

Neben der REST-API-Schnittstelle stellen die TagDetect-Module außerdem Seiten in der Web GUI unter Module ‣ AprilTag und Module ‣ QR Code bereit, über welche sie manuell ausprobiert und konfiguriert werden können.

Im Folgenden sind die Parameter am Beispiel von rc_qr_code_detect aufgelistet. Sie gleichen denen von rc_april_tag_detect.

Dieses Softwaremodul bietet folgende Laufzeitparameter:

Tab. 28 Laufzeitparameter des rc_qr_code_detect-Moduls
Name Typ Min. Max. Default Beschreibung
detect_inverted_tags bool false true false Erkennt Tags, bei denen Schwarz und Weiß vertauscht sind
forget_after_n_detections int32 1 1000 30 Anzahl an Markererkennungsläufen, nach denen ein vorher gesehener Marker während der Marker-Wiedererkennung verworfen wird
max_corner_distance float64 0.001 0.01 0.005 Maximale Distanz zusammengehöriger Ecken zweier Marker während der Marker-Wiedererkennung
quality string - - High Qualität der Markererkennung: [Low, Medium, High]
use_cached_images bool false true false Benutze das zuletzt empfangene Stereo-Bildpaar, anstatt auf ein neues zu warten

Über die REST-API können diese Parameter wie folgt gesetzt werden.

API Version 2
API Version 1 (veraltet)
PUT http://<host>/api/v2/pipelines/0/nodes/<rc_qr_code_detect|rc_april_tag_detect>/parameters/parameters?<parameter-name>=<value>

PUT http://<host>/api/v1/nodes/<rc_qr_code_detect|rc_april_tag_detect>/parameters?<parameter-name>=<value>

Statuswerte

Die TagDetect-Module melden folgende Statuswerte:

Tab. 29 Statuswerte der rc_qr_code_detect- und rc_april_tag_detect-Module
Name Beschreibung
data_acquisition_time Zeit in Sekunden, für die beim letzten Aufruf auf Bilddaten gewartet werden musste
last_timestamp_processed Zeitstempel des letzten verarbeiteten Bilddatensatzes
state Der aktuelle Zustand des Moduls
tag_detection_time Berechnungszeit für die Markererkennung beim letzten Aufruf in Sekunden

Der Parameter state kann folgende Werte annehmen:

Tab. 30 Mögliche Zustände der TagDetect-Module
Zustandsname Beschreibung
IDLE Das Modul ist inaktiv.
RUNNING Das Modul läuft und ist bereit zur Markererkennung.
FATAL Ein schwerwiegender Fehler ist aufgetreten.

Services

Die TagDetect-Module implementieren einen Zustandsautomaten, welcher zum Starten und Stoppen genutzt werden kann. Die eigentliche Markererkennung kann mit detect ausgelöst werden.

Die angebotenen Services von rc_qr_code_detect bzw. rc_april_tag_detect können mithilfe der REST-API-Schnittstelle oder der rc_visard Web GUI ausprobiert und getestet werden.

detect

löst eine Markererkennung aus.

Details

Abhängig vom use_cached_images-Parameter arbeitet das Modul auf dem zuletzt empfangenen Bildpaar (wenn true) oder wartet auf ein Bildpaar, das nach dem Auslösen des Services aufgenommen wurde (wenn false, dies ist das Standardverhalten). Auch wenn der Parameter auf true steht, arbeitet die Markererkennung niemals mehrmals auf einem Bildpaar.

Es wird empfohlen, detect nur im Zustand RUNNING aufzurufen. Es ist jedoch auch im Zustand IDLE möglich, was zu einem Autostart und -stop des Moduls führt. Dies hat allerdings Nachteile: Erstens dauert der Aufruf deutlich länger, zweitens funktioniert die Marker-Wiedererkennung nicht. Es wird daher ausdrücklich empfohlen, das Modul manuell zu starten, bevor detect aufgerufen wird.

Marker können vom detect-Ergebnis aus mehreren Gründen ausgeschlossen werden, z.B. falls ein Marker nur in einem der Kamerabilder sichtbar war, oder falls die Posenschätzung fehlschlug. Diese herausgefilterten Marker werden im Log aufgelistet, auf welches wie in Download der Logdateien beschrieben zugegriffen werden kann.

Auf den Web GUI-Seiten der TagDetect-Module wird eine Visualisierung der letzten Markererkennung bereitgestellt. Diese Visualisierung wird allerdings erst angezeigt, sobald die Markererkennung mindestens einmal ausgeführt wurde. In der Web GUI kann die Markererkennung außerdem manuell ausprobiert werden, indem die Detektieren-Schaltfläche betätigt wird.

Aufgrund von Änderungen der Systemzeit auf dem rc_visard können Zeitsprünge auftreten, sowohl vorwärts als auch rückwärts (siehe Zeitsynchronisierung). Während Vorwärtssprünge keinen Einfluss auf die TagDetect-Module haben, invalidieren Rücksprünge die bereits empfangenen Bilder. Deshalb wird, wenn ein Rücksprung erkannt wird, Fehler -102 beim nächsten detect-Aufruf zurückgegeben. Dies geschieht auch, um den Benutzer darauf hinzuweisen, dass die Zeitstempel in der detect-Antwort ebenso zurückspringen werden.

API Version 2
API Version 1 (veraltet)
PUT http://<host>/api/v2/pipelines/0/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/detect

PUT http://<host>/api/v1/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/detect
Request
Response

Optionale Serviceargumente:

tags bezeichnet die Liste der Marker-IDs, welche erkannt werden sollen. Bei QR-Codes ist die ID gleich den enthaltenen Daten. Bei AprilTags ist es „<Familie>_<ID>“, also beispielsweise „36h11_5“ für Familie 36h11 und ID 5. Natürlich kann das AprilTag-Modul nur zur Erkennung von AprilTags und das QR-Code-Modul nur zur Erkennung von QR-Codes genutzt werden.

Die tags-Liste kann auch leer gelassen werden. In diesem Fall werden alle erkannten Marker zurückgegeben. Dieses Feature sollte nur während der Entwicklung einer Applikation oder zur Fehlerbehebung benutzt werden. Wann immer möglich sollten die konkreten Marker-IDs aufgelistet werden, zum einen zur Vermeidung von Fehldetektionen, zum anderen auch um die Markererkennung zu beschleunigen, da nicht benötigte Marker aussortiert werden können.

Bei AprilTags kann der Benutzer nicht nur einzelne Marker, sondern auch eine gesamte Familie spezifizieren, indem die ID auf „<family>“ gesetzt wird, bspw. „36h11“. Dadurch werden alle Marker dieser Familie erkannt. Es ist auch möglich, mehrere Familien oder eine Kombination aus Familien und einzelnen Markern anzugeben. Zum Beispiel kann detect mit „36h11“, „25h9_3“ und „36h10“ zur gleichen Zeit aufgerufen werden.

Zusätzlich zur ID kann auch die ungefähre Größe (\(\pm 10\%\)) eines Markers angegeben werden. Wie in Posenschätzung erklärt, verhilft dies Mehrdeutigkeiten aufzulösen, die in bestimmten Situationen auftreten können.

Das Feld pose_frame gibt an, ob die Posen im Kamera- oder im externen Koordinatensystem zurückgegeben werden (siehe Hand-Auge-Kalibrierung. Der Standardwert ist camera.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "args": {
    "pose_frame": "string",
    "robot_pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "tags": [
      {
        "id": "string",
        "size": "float64"
      }
    ]
  }
}

timestamp wird auf den Zeitstempel des Bildpaares gesetzt, auf dem die Markererkennung gearbeitet hat.

tags enthält alle erkannten Marker.

id ist die ID des Markers, vergleichbar zur id in der Anfrage.

instance_id ist der zufällige, eindeutige Identifikator eines Markers, welcher von der Marker-Wiedererkennung zugewiesen wird.

pose enthält position und orientation. Die Orientierung ist im Quaternionen-Format angegeben.

pose_frame bezeichnet das Koordinatensystem, auf welches obige Pose bezogen ist, und hat den Wert camera oder external.

size wird auf die geschätzte Markergröße gesetzt. Bei AprilTags ist hier der weiße Rahmen nicht enthalten.

return_code enthält mögliche Warnungen oder Fehlercodes und Nachrichten.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "detect",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    },
    "tags": [
      {
        "id": "string",
        "instance_id": "string",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "size": "float64",
        "timestamp": {
          "nsec": "int32",
          "sec": "int32"
        }
      }
    ],
    "timestamp": {
      "nsec": "int32",
      "sec": "int32"
    }
  }
}

start

startet das Modul durch einen Übergang von IDLE nach RUNNING.

Details

Wenn das Modul läuft, empfängt es die Bilder der Stereokamera und ist bereit, Marker zu erkennen. Um Rechenressourcen zu sparen, sollte das Modul nur laufen, wenn dies nötig ist.

Dieser Service kann wie folgt aufgerufen werden.

API Version 2
API Version 1 (veraltet)
PUT http://<host>/api/v2/pipelines/0/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/start

PUT http://<host>/api/v1/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/start
Request
Response
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "start",
  "response": {
    "accepted": "bool",
    "current_state": "string"
  }
}

stop

stoppt das Modul durch einen Übergang zu IDLE.

Details

Dieser Übergang kann auf dem Zustand RUNNING und FATAL durchgeführt werden. Alle Marker-Wiedererkennungs-Informationen werden beim Stoppen gelöscht.

Dieser Service kann wie folgt aufgerufen werden.

API Version 2
API Version 1 (veraltet)
PUT http://<host>/api/v2/pipelines/0/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/stop

PUT http://<host>/api/v1/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/stop
Request
Response
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "stop",
  "response": {
    "accepted": "bool",
    "current_state": "string"
  }
}

restart

startet das Modul neu.

Details

Wenn im Zustand RUNNING oder FATAL, wird das Modul erst gestoppt und dann wieder gestartet. In IDLE wird das Modul nur gestartet.

Dieser Service kann wie folgt aufgerufen werden.

API Version 2
API Version 1 (veraltet)
PUT http://<host>/api/v2/pipelines/0/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/restart

PUT http://<host>/api/v1/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/restart
Request
Response
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "restart",
  "response": {
    "accepted": "bool",
    "current_state": "string"
  }
}

reset_defaults

stellt die Werkseinstellungen der Parameter dieses Moduls wieder her und wendet sie an („factory reset“).

Details

Dieser Service kann wie folgt aufgerufen werden.

API Version 2
API Version 1 (veraltet)
PUT http://<host>/api/v2/pipelines/0/nodes/<rc_qr_code_detect|rc_april_tag_detect>/services/reset_defaults

PUT http://<host>/api/v1/nodes/<rc_qr_code_detect|rc_april_tag_detect>/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"
    }
  }
}

Rückgabecodes

Zusätzlich zur eigentlichen Serviceantwort gibt jeder Service einen sogenannten return_code bestehend aus einem Integer-Wert und einer optionalen Textnachricht zurück. Erfolgreiche Service-Anfragen werden mit einem Wert von 0 quittiert. Positive Werte bedeuten, dass die Service-Anfrage zwar erfolgreich bearbeitet wurde, aber zusätzliche Informationen zur Verfügung stehen. Negative Werte bedeuten, dass Fehler aufgetreten sind. Für den Fall, dass mehrere Rückgabewerte zutreffend wären, wird der kleinste zurückgegeben, und die entsprechenden Textnachrichten werden in return_code.message akkumuliert.

Die folgende Tabelle listet die möglichen Rückgabe-Codes auf:

Code Beschreibung
0 Erfolg
-1 Ein ungültiges Argument wurde übergeben.
-4 Die maximale Wartezeit auf ein Stereo-Bildpaar wurde überschritten.
-9 Die Lizenz ist ungültig.
-11 Sensor nicht verbunden, nicht unterstützt oder nicht bereit
-101 Ein interner Fehler trat während der Markererkennung auf.
-102 Ein Rückwärtssprung der Systemzeit trat auf
-103 Ein interner Fehler trat während der Posenschätzung auf.
-200 Ein schwerwiegender interner Fehler trat auf.
200 Mehrere Warnungen traten auf. Siehe die Auflistung in message.
201 Das Modul war nicht im Zustand RUNNING.