SilhouetteMatch¶

Einführung¶

Das SilhouetteMatch-Modul ist ein optional erhältliches Modul, welches intern auf dem rc_cube läuft. Das SilhouetteMatch-Modul erkennt Objekte, indem eine vordefinierte Silhouette („Template“) mit Kanten im Bild verglichen wird.

Bemerkung

Das SilhouetteMatch-Modul ist optional und benötigt eine eigene Lizenz, welche erworben werden muss.

Für jedes Objekt, das mit dem SilhouetteMatch-Modul erkannt werden soll, wird ein Template benötigt. Roboception bietet hierfür einen Template-Generierungsservice auf ihrer Website an, auf der der Benutzer CAD-Daten oder mit dem System aufgenommene Daten hochladen kann, um Templates generieren zu lassen.

Templates bestehen aus den prägnanten Kanten eines Objekts. Die Kanten des Templates werden mit den erkannten Kanten im linken und rechten Kamerabild abgeglichen, wobei die Größe der Objekte und deren Abstand zur Kamera mit einbezogen wird. Die Posen der erkannten Objekte werden zurückgegeben und können beispielsweise benutzt werden, um die Objekte zu greifen.

Das SilhouetteMatch-Modul bietet:

eine intuitiv gestaltete Bedienoberfläche für Inbetriebnahme, Konfiguration und Test auf der rc_cube Web GUI
eine REST-API-Schnittstelle und eine KUKA Ethernet KRL Schnittstelle
die Möglichkeit, sogenannte Regions of Interest (ROIs) zu definieren, um relevante Teilbereiche des Kamerabilds auszuwählen (siehe Setzen einer Region of Interest)
eine integrierte Behältererkennung (siehe Load Carrier Funktionalität), um in Bin-Picking-Anwendungen („Griff in die Kiste“) Greifpunkte nur für Objekte in dem erkannten Behälter zu berechnen
die Definition von Greifpunkten für jedes Template über eine interaktive Visualisierung in der Web GUI
die Unterstützung von sowohl statisch montierten als auch robotergeführten Kameras. Optional kann es mit der Hand-Auge-Kalibrierung kombiniert werden, um Greifposen in einem benutzerdefinierten externen Koordinatensystem zu liefern
eine Sortierung der Greifpunkte nach ihrer Erreichbarkeit, sodass die Greifpunkte, die entlang der z-Achse des TCP am dichtesten an der Kamera liegen, zuerst zurückgeliefert werden

Taugliche Objekte¶

Das SilhouetteMatch-Modul ist für Objekte ausgelegt, die prägnante Kanten auf einer Ebene besitzen, welche parallel zu der Basisebene ist, auf der die Objekte liegen. Das trifft beispielsweise auf flache, nicht-transparente Objekte zu, wie gefräste, lasergeschnittene oder wasserstrahlgeschnittene Teile. Komplexere Objekte können auch erkannt werden, solange sie prägnante Kanten auf einer Ebene besitzen, z.B. ein gedrucktes Muster auf einer ebenen Fläche.

Das SilhouetteMatch-Modul funktioniert am besten für Objekte, die auf einer texturlosen Basisebene liegen. Die Farbe der Basisebene sollte so gewählt werden, dass im Intensitätsbild ein klarer Kontrast zwischen den Objekten und der Basisebene sichtbar ist.

Taugliche Szene¶

Eine für das SilhouetteMatch-Modul taugliche Szene muss folgende Bedingungen erfüllen:

Die zu erkennenden Objekte müssen, wie oben beschrieben, tauglich für das SilhouetteMatch-Modul sein.
Nur Objekte, die zum selben Template gehören, dürfen gleichzeitig sichtbar sein (sortenrein). Falls auch andere Objekte sichtbar sind, muss eine passende Region of Interest (ROI) festgelegt werden.
Alle sichtbaren Objekte befinden sich auf einer gemeinsamen Basisebene, welche kalibriert werden muss.
Die Verkippung der Basisebene zur Blickrichtung der Kamera darf 10 Grad nicht übersteigen.
Die Objekte sind weder teilweise noch komplett verdeckt.
Alle sichtbaren Objekte liegen richtig herum.
Die Objektkanten, welche abgeglichen werden sollen, sind sowohl im linken als auch im rechten Kamerabild zu sehen.

Kalibrierung der Basisebene¶

Bevor Objekte erkannt werden können, muss die Basisebene kalibriert werden. Hierbei wird die Distanz und der Winkel der Ebene, auf welcher die Objekte liegen, gemessen und persistent auf dem rc_cube gespeichert.

Durch die Trennung der Kalibrierung der Basisebene von der eigentlichen Objekterkennung werden beispielsweise Szenarien ermöglicht, in denen die Basisebene zeitweise verdeckt ist. Darüber hinaus wird die Berechnungszeit der Objekterkennung für Szenarien verringert, in denen die Basisebene für eine gewisse Zeit fixiert ist – die Basisebene muss in diesem Fall nicht fortlaufend neu detektiert werden.

Die Kalibrierung der Basisebene kann mit drei unterschiedlichen Verfahren durchgeführt werden, auf die im Folgenden näher eingegangen wird:

AprilTag-basiert
Stereo-basiert
Manuell

Die Kalibrierung ist erfolgreich, solange der Normalenvektor der Basisebene höchstens 10 Grad gegen die Blickrichtung der Kamera verkippt ist. Eine erfolgreiche Kalibrierung wird persistent auf dem rc_cube gespeichert, bis sie entweder gelöscht wird oder eine neue Kalibrierung durchgeführt wird.

Bemerkung

Um Datenschutzproblemen entgegenzuwirken, wird die Visualisierung der Kalibrierung der Basisebene nach einem Neustart des rc_cube verschwommen dargestellt.

In Szenarien, in denen die Basisebene nicht direkt kalibriert werden kann, ist es auch möglich, zu einer zur Basisebene parallel liegenden Ebene zu kalibrieren. In diesem Fall kann der Parameter offset benutzt werden, um die geschätzte Ebene auf die eigentliche Basisebene zu verschieben. Der Parameter offset gibt die Distanz in Metern an, um welche die geschätzte Ebene in Richtung der Kamera verschoben wird.

In der REST-API ist eine Ebene durch eine Normale (normal) und einen Abstand (distance) definiert. normal ist ein normalisierter 3-Vektor, welcher die Normale der Ebene spezifiziert. Die Normale zeigt immer von der Kamera weg. distance repräsentiert den Abstand der Ebene von der Kamera in Richtung der Normale. normal und distance können auch als \(a\), \(b\), \(c\), bzw. \(d\) der Ebenengleichung interpretiert werden:

\[ax + by + cz + d = 0\]

AprilTag-basierte Kalibrierung der Basisebene¶

Die AprilTag-Erkennung (siehe TagDetect) wird benutzt, um AprilTags in der Szene zu finden und eine Ebene durch diese zu legen. Mindestens drei AprilTags müssen so auf der Basisebene platziert werden, dass sie im linken und rechten Kamerabild zu sehen sind. Die AprilTags sollten ein möglichst großes Dreieck aufspannen. Je größer das Dreieck ist, desto höher wird die Genauigkeit der Schätzung der Basisebene. Diese Methode sollte benutzt werden, wenn die Basisebene untexturiert und kein externer Projektor mit Zufallsmuster angeschlossen ist. Diese Kalibriermethode ist sowohl über die REST-API-Schnittstelle als auch über die rc_cube Web GUI verfügbar.

Stereo-basierte Kalibrierung der Basisebene¶

Die 3D-Punktwolke, welche vom Stereo-Matching-Modul berechnet wird, wird benutzt um eine Ebene in den 3D-Punkten zu finden. Die Region of Interest (ROI) sollte für diese Methode deshalb so gewählt werden, dass nur die relevante Basisebene eingeschlossen wird. Der Parameter plane_preference erlaubt es auszuwählen, ob die zur Kamera am nächsten gelegene oder die von der Kamera am weitesten entfernte Ebene als Basisebene benutzt wird. Die am nächsten gelegene Ebene kann in Szenarien ausgewählt werden, in denen die Basisebene vollständig von Objekten verdeckt wird oder für die Kalibrierung nicht erreichbar ist. Diese Methode sollte benutzt werden, wenn die Basisebene texturiert ist oder ein Projektor mit Zufallsmuster angeschlossen ist. Diese Kalibriermethode ist sowohl über die REST-API-Schnittstelle als auch über die rc_cube Web GUI verfügbar.

Manuelle Kalibrierung der Basisebene¶

Die Basisebene kann manuell gesetzt werden, falls die Parameter bekannt sind – beispielsweise von einer vorangegangenen Kalibrierung. Diese Kalibriermethode ist nur über die REST-API-Schnittstelle und nicht über die rc_cube Web GUI verfügbar.

Setzen einer Region of Interest¶

Falls Objekte nur in einem Teil des Sichtfelds der Kamera erkannt werden sollen, kann eine Region of Interest (ROI) gesetzt werden. Eine ROI ist als rechteckiger Teil des linken Kamerabilds definiert und kann sowohl über die REST-API-Schnittstelle als auch über die rc_cube Web GUI gesetzt werden. Die Web GUI bietet hierfür ein einfach zu benutzendes Werkzeug an. Es können bis zu 50 ROIs angelegt und persistent auf dem rc_cube gespeichert werden. Jeder ROI muss ein eindeutiger Name zugewiesen werden, um diese später während der Kalibrierung der Basisebene oder der Objekterkennung verwenden zu können.

In der REST-API ist eine 2D-ROI über folgende Werte spezifiziert:

id: Eindeutiger Name der ROI
offset_x, offset_y: Abstand in Pixeln von der oberen rechten Bildecke entlang der x- bzw. y-Achse
width, height: Breite und Höhe in Pixeln

Setzen von Greifpunkten¶

Um das SilhouetteMatch-Modul direkt in einer Roboteranwendung zu nutzen, können für jedes Template Greifpunkte definiert werden. Ein Greifpunkt repräsentiert die gewünschte Position und Orientierung des Roboter-TCPs (Tool Center Point), mit der das Objekt gegriffen werden kann (siehe Abb. 29).

Abb. 29 Definition von Greifpunkten bezogen auf den Roboter-TCP

Jeder Greifpunkt enthält eine id, die eindeutig über alle Greifpunkte eines Objekt-Templates sein muss, die ID des Templates (template_id), zu dem der Greifpunkt hinzugefügt wird, und die Greifpose (pose) im Koordinatensystem des Templates. Greifpunkte können über die REST-API-Schnittstelle, oder über die interaktive Visualisierung in der Web GUI definiert werden. Der rc_cube kann bis zu 50 Greifpunkte pro Template speichern.

Setzen von Greifpunken in der Web GUI¶

Die rc_cube Web GUI bietet eine interaktive und intuitive Möglichkeit, Greifpunkte für Objekt-Templates zu setzen. Im ersten Schritt muss das Objekt-Template auf den rc_cube hochgeladen werden. Das kann über die SilhouetteMatch-Seite (unter der Seite Module) in der Web GUI erfolgen, indem im Abschnitt Templates und Greifpunkte auf neues Template hinzufügen geklickt wird. Wenn der Upload abgeschlossen ist, erscheint ein Fenster mit einer 3D-Visualisierung des Templates, in dem Greifpunkte hinzugefügt oder existierende Greifpunkte bearbeitet werden können. Dasselbe Fenster erscheint, wenn ein vorhandenes Template bearbeitet wird.

Dieses Fenster bietet zwei Möglichkeiten, um Greifpunkte zu setzen:

Greifpunkte manuell hinzufügen: Durch Klicken auf das + Symbol wird ein neuer Greifpunkt im Ursprung des Templates angelegt. Diesem Greifpunkt kann ein eindeutiger Name gegeben werden, der seiner ID entspricht. Die gewünschte Pose des Greifpunkts im Koordinatensystem des Templates kann in den Feldern für Position und Roll/Pitch/Yaw eingegeben werden. Die Greifpunkte können frei platziert werden, auch außerhalb oder innerhalb des Templates, und werden mit ihrer Orientierung zur Überprüfung in der Visualisierung veranschaulicht.
Greifpunkte interaktiv hinzufügen: Greifpunkte können interaktiv zu einem Template hinzugefügt werden, indem zuerst auf den Button Greifpunkt hinzufügen oben links in der Visualisierung und anschließend auf den gewünschten Punkt auf dem Template geklickt wird. Der Greifpunkt wird an die Oberfläche angeheftet und seine Orientierung entspricht einem rechtshändigen Koordinatensystem, sodass die z-Achse senkrecht auf der Template-Oberfläche steht und in das Template hineingerichtet ist. Die Position und Orientierung des Greifpunkts im Koordinatensystem des Templates ist auf der rechten Seite angezeigt. Die Position und Orientierung des Greifpunkts kann auch interaktiv verändert werden. Für den Fall, dass An Oberfläche anheften in der Visualisierung aktiv ist (das ist der Standardwert), kann der Greifpunkt durch Klicken auf Verschieben und anschließendes Klicken auf den Greifpunkt über die Oberfläche des Templates zur gewünschten Position bewegt werden. Die Orientierung des Greifpunkts um die Oberflächennormale kann ebenfalls interaktiv verändert werden, in dem auf Rotieren geklickt wird und anschließend der Greifpunkt mit der Maus rotiert wird. Wenn An Oberfläche anheften nicht aktiv ist, kann der Greifpunkt mit der Maus frei in allen drei Raumrichtungen verschoben und rotiert werden.

Wenn das Template Symmetrien hat, können die Greifpunkte, die symmetrisch zum definierten Greifpunkt sind, durch Klick auf Symmetrische Greifpunkte anzeigen angezeigt werden.

Setzen von Greifpunkten über die REST-API¶

Greifpunkte können über die REST-API-Schnittstelle mithilfe des set_grasp oder set_all_grasps Services gesetzt werden (siehe Services). Im SilhouetteMatch-Modul besteht ein Greifpunkt aus der id, die eindeutig über alle Greifpunkte eines Objekt-Templates sein muss, der ID des Templates (template_id), zu dem der Greifpunkt hinzugefügt wird, und der Greifpose (pose). Die Pose ist im Koordinatensystem des Templates angegeben und besteht aus einer Position (position) in Metern und einer Orientierung (orientation) als Quaternion.

Setzen der bevorzugten TCP-Orientierung¶

Das SilhouetteMatch-Modul berechnet die Erreichbarkeit von Greifpunkten basierend auf der bevorzugten Orientierung des Greifers oder TCPs. Die bevorzugte Orientierung kann über den Service set_preferred_orientation oder über die SilhouetteMatch-Seite in der Web GUI gesetzt werden. Die resultierende Richtung der z-Achse des TCP wird genutzt, um Greifpunkte zu verwerfen, die der Greifer nicht erreichen kann. Weiterhin wird die bevorzugte Orientierung genutzt, um die erreichbaren Greifpunkte so zu sortieren, dass diejenigen, die entlang der z-Achse der bevorzugten TCP-Orientierung am dichtesten an der Kamera liegen, zuerst zurückgeliefert werden.

Die bevorzugte TCP-Orientierung kann im Kamerakoordinatensystem oder im externen Koordinatensystem gesetzt werden, wenn eine Hand-Auge-Kalibrierung verfügbar ist. Wenn die bevorzugte TCP-Orientierung im externen Koordinatensystem definiert ist, und der Sensor am Roboter montiert ist, muss bei jedem Aufruf der Objekterkennung die aktuelle Roboterpose angegeben werden, damit die bevorzugte Orientierung zur Filterung und Sortierung der Greifpunkte auf den erkannten Objekten genutzt werden kann. Wenn keine bevorzugte TCP-Orientierung gesetzt wird, wird die z-Achse der linken Kamera als die bevorzugte TCP-Orientierung genutzt.

Objekterkennung¶

Objekte können erst nach einer erfolgreichen Kalibrierung der Basisebene erkannt werden. Es muss sichergestellt werden, dass sich Position und Orientierung der Basisebene zwischen Kalibrierung und Objekterkennung nicht ändern. Anderenfalls muss die Kalibrierung erneuert werden.

Um eine Objekterkennung durchzuführen, müssen im Allgemeinen die folgenden Serviceargumente an das SilhouetteMatch-Modul übergeben werden:

das Template des Objekts, welches in der Szene erkannt werden soll
das Koordinatensystem, in dem die Posen der detektierten Objekte zurückgegeben werden sollen (siehe Hand-Auge-Kalibrierung)

Optional können auch folgende Serviceargumente an das SilhouetteMatch-Modul übergeben werden:

ein Versatz, falls Objekte nicht direkt auf der Basisebene liegen, sondern auf einer zu dieser parallelen Ebene. Der Versatz bezeichnet die Distanz beider Ebenen in Richtung der Kamera. Wenn dieser Wert nicht gesetzt wird, wird ein Versatz von 0 angenommen.
die ID des Load Carriers, der die zu detektierenden Objekte enthält
die ID der Region of Interest, innerhalb der nach dem Load Carrier gesucht wird, oder – falls kein Load Carrier angegeben ist – die Region of Interest, innerhalb der Objekte erkannt werden sollen. Wenn keine ROI gesetzt wird, werden Objekte im gesamten Kamerabild gesucht.
die aktuelle Roboterpose, wenn die Kamera am Roboter montiert ist und als Koordinatensystem external gewählt wurde, oder die bevorzugte TCP-Orientierung im externen Koordinatensystem angegeben ist
Informationen für die Kollisionsprüfung: Die ID des Greifers, um die Kollisionsprüfung zu aktivieren, und optional ein Greif-Offset, der die Vorgreifposition definiert. Details zur Kollisionsprüfung sind in CollisionCheck gegeben.

Im Ausprobieren-Abschnitt der Seite SilhouetteMatch der Web GUI kann die Objektdetektion ausprobiert werden. Das Ergebnis wird, wie in Abb. 30 dargestellt, visualisiert.

_images/silhouetteMatchResults_cube_de.png

Abb. 30 Ergebnisbild des SilhouetteMatch-Moduls, wie über die Web GUI dargestellt

Das linke Bild zeigt die kalibrierte Basisebene in blau und das zu erkennende Template in rot mit den Greifpunkten (siehe Setzen von Greifpunkten) in grün. Das Template wird passend zu Abstand und Verkippung der Basisebene verformt dargestellt.

Das rechte Bild zeigt das Detektionsergebnis. Die blauschattierte Fläche auf der linken Seite markiert den Teil des linken Kamerabilds, welcher nicht mit dem rechten Kamerabild überlappt. In diesem Bereich können keine Objekte erkannt werden. Die gewählte Region of Interest wird als petrolfarbenes Rechteck dargestellt. Erkannte Kanten im Bild werden in hellem Blau und erkannte Objekte (instances) in rot visualisiert. Blaue Punkte markieren jeweils den Ursprung der detektierten Objekte, wie im Template festgelegt. Erreichbare Greifpunkte sind als grüne Punkte dargestellt. Nicht erreichbare Greifpunkte werden als rote Punkte visualisiert (nicht im Bild dargestellt).

Die Posen der Objektursprünge werden im gewählten Koordinatensystem zurückgegeben. Wenn das ausgewählte Template auch Greifpunkte hat, dann wird zusätzlich zu den erkannten Objekten auch eine Liste von Greifpunkten (grasps) für alle erkannten Objekte zurückgegeben. Die Greifpunkte in dieser Liste sind nach ihrer Erreichbarkeit sortiert (siehe Setzen der bevorzugten TCP-Orientierung). Die Posen der Greifpunkte sind im gewünschten Koordinatensystem angegeben. Die erkannten Objekte und die Greifpunkte können einander über ihre UUIDs zugeordnet werden. Falls das Template eine kontinuierliche Rotationssymmetrie aufweist, besitzen alle Ergebnisposen die gleiche Orientierung. Für nicht-rotationssymmetrische Objekte richtet sich die Orientierung nach der Normalen der Basisebene.

Die Detektionsergebnisse und Berechnungszeiten werden durch Laufzeitparameter beeinflusst, welche weiter unten aufgezählt und beschrieben werden. Unsachgemäße Parameterwerte können zu Zeitüberschreitungen im Detektionsprozess des SilhouetteMatch-Moduls führen.

Wechselwirkung mit anderen Modulen¶

Die folgenden auf dem rc_cube laufenden Module liefern Daten für das SilhouetteMatch-Modul oder haben Einfluss auf die Datenverarbeitung.

Bemerkung

Jede Konfigurationsänderung dieser Module kann direkte Auswirkungen auf die Qualität oder das Leistungsverhalten des SilhouetteMatch-Moduls haben.

Stereokamera und Stereo-Matching¶

Das SilhouetteMatch-Modul verarbeitet intern die rektifizierten Bilder des Stereokamera-Moduls (rc_stereocamera). Es sollte deshalb auf eine passende Belichtungszeit geachtet werden, um optimale Ergebnisse zu erhalten.

Für die Kalibrierung der Basisebene mit der Stereo-Methode wird das Disparitätsbild des Stereo-Matching-Moduls (rc_stereomatching) verarbeitet. Abgesehen davon sollte das Stereo-Matching-Modul nicht parallel zum SilhouetteMatch-Modul ausgeführt werden, da die Laufzeit der Objekterkennung sonst negativ beeinflusst wird.

Für beste Ergebnisse wird empfohlen, Glättung für Stereo-Matching zu aktivieren.

IOControl und Projektor-Kontrolle¶

Wenn der rc_cube in Verbindung mit einem externen Musterprojektor und dem Modul IOControl und Projektor-Kontrolle (rc_iocontrol) betrieben wird, sollte der Projektor für die stereobasierte Kalibrierung der Basisebene benutzt werden.

Das projizierte Muster darf während der Objektdetektion nicht im linken oder rechten Kamerabild sichtbar sein, da es den Detektionsvorgang behindert. Der Projektor sollte deshalb entweder ausgeschaltet sein oder im Modus ExposureAlternateActive betrieben werden.

Hand-Auge-Kalibrierung¶

Wenn die Kamera zu einem Roboter kalibriert ist, kann das SilhouetteMatch-Modul die Ergebnisposen automatisch im Roboterkoordinatensystem liefern. Für die Services des SilhouetteMatch-Moduls kann das Referenzkoordinatensystem aller Posen über das Argument pose_frame angegeben werden.

Es kann zwischen den folgenden zwei Werten für pose_frame gewählt werden:

Kamera-Koordinatensystem (camera): Alle Posen und Ebenenparameter werden im Kamera-Koordinatensystem angegeben.
Benutzerdefiniertes externes Koordinatensystem (external): Alle Posen und Ebenenparameter sind im sogenannten externen Koordinatensystem angegeben, welches vom Nutzer während der Hand-Auge-Kalibrierung gewählt wurde. In diesem Fall bezieht das SilhouetteMatch-Modul alle notwendigen Informationen über die Kameramontage und die kalibrierte Hand-Auge-Transformation automatisch vom internen 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.

Bemerkung

Wurde keine Hand-Auge-Kalibrierung durchgeführt, muss als Referenzkoordinatensystem pose_frame immer camera angegeben werden.

Bemerkung

Wird die Hand-Auge-Kalibrierung nach einer Kalibrierung der Basisebene verändert, wird die Kalibrierung der Basisebene als ungültig markiert und muss erneuert werden.

Für den Fall einer robotergeführten Kamera ist es abhängig von pose_frame und der bevorzugten TCP-Orientierung nötig, zusätzlich die aktuelle Roboterpose (robot_pose) zur Verfügung zu stellen:

Wenn external als pose_frame ausgewählt ist, ist die Angabe der Roboterpose obligatorisch.
Wenn die bevorzugte TCP-Orientierung in external definiert ist, ist die Angabe der Roboterpose obligatorisch.
Wenn camera als pose_frame ausgewählt ist und die bevorzugte TCP-Orientierung in external definiert ist, ist die Angabe der Roboterpose optional.

Wenn die aktuelle Roboterpose während der Kalibrierung der Basisebene angegeben wird, wird sie persistent auf dem rc_cube gespeichert. Falls für die Services get_base_plane_calibration oder detect_objects die dann aktuelle Roboterpose ebenfalls angegeben wird, wird die Basisebene automatisch zu der neuen Roboterpose transformiert. Das erlaubt dem Benutzer, die Roboterpose (und damit die Pose der Kamera) zwischen Kalibrierung der Basisebene und Objekterkennung zu verändern.

Bemerkung

Eine Objekterkennung kann nur durchgeführt werden, wenn die Verkippung der Basisebene zur Sichtachse der Kamera ein 10-Grad-Limit nicht übersteigt.

CollisionCheck¶

Die Kollisionsprüfung kann für die Greifpunktberechnung des SilhouetteMatch-Moduls aktiviert werden, indem die ID des benutzten Greifers und optional ein Greif-Offset an den detect_object Service übergeben werden. Der Greifer muss im CollisionCheck-Modul definiert werden (siehe Erstellen eines Greifers) und Details über die Kollisionsprüfung werden in Integrierte Kollisionsprüfung in anderen Modulen gegeben. Zusätzlich wird auf Kollisionen zwischen dem Greifer und der kalibrierten Basisebene geprüft. Wenn das ausgewählte Template eine Kollisionsgeometrie enthält, wird außerdem auch auf Kollisionen zwischen dem Greifer und den detektierten Objekten geprüft, wobei das Objekt, auf dem sich der jeweilige Greifpunkt befindet, von der Prüfung ausgenommen ist.

Wenn die Kollisionsprüfung aktiviert ist, werden nur kollisionsfreie Greifpunkte zurückgeliefert. Jedoch werden in der Ergebnis-Visualisierung oben auf der SilhouetteMatch-Seite der Web GUI kollidierende Greifpunkte als rote Punkte dargestellt.

Die Laufzeitparameter des CollisionCheck-Moduls beeinflussen die Kollisionserkennung wie in CollisionCheck-Parameter beschrieben.

Parameter¶

Das SilhouetteMatch-Modul wird in der REST-API als rc_silhouettematch bezeichnet und in der Web GUI auf der Seite SilhouetteMatch (unter der Seite Module) dargestellt. Der Benutzer kann die Parameter entweder dort oder über die REST-API-Schnittstelle ändern.

Übersicht über die Parameter¶

Dieses Softwaremodul bietet folgende Laufzeitparameter:

Tab. 28 Laufzeitparameter des `rc_silhouettematch`-Moduls¶
Name	Typ	Min.	Max.	Default	Beschreibung
`edge_sensitivity`	float64	0.1	1.0	0.6	Empfindlichkeit der Kantenerkennung
`load_carrier_crop_distance`	float64	0.0	0.05	0.005	Sicherheitsspielraum um den das Load Carrier Innenmaß verringert wird, um eine Region of Interest für die Erkennung zu definieren
`load_carrier_model_tolerance`	float64	0.003	0.025	0.008	Gibt an, wie weit die Abmessungen des Load Carriers von den Werten im Modell abweichen dürfen
`match_max_distance`	float64	0.0	10.0	2.5	Der maximale tolerierte Abstand zwischen dem Template und den detektierten Kanten im Bild in Pixeln
`match_percentile`	float64	0.7	1.0	0.85	Der Anteil der Template-Pixel, die innerhalb der maximalen Matchingdistanz liegen müssen, um ein Objekt erfolgreich zu detektieren
`max_number_of_detected_objects`	int32	1	20	10	Maximale Anzahl der zu detektierenden Objekte
`quality`	string	-	-	High	High, Medium, oder Low

Beschreibung der Laufzeitparameter¶

Die Laufzeitparameter werden zeilenweise auf der SilhouetteMatch-Seite in der Web GUI dargestellt. Im folgenden wird der Name des Parameters in der Web GUI in Klammern hinter dem eigentlichen Parameternamen angegeben. Die Parameter sind in derselben Reihenfolge wie in der Web GUI aufgelistet:

`max_number_of_detected_objects` (Maximale Objektanzahl)¶

Dieser Parameter gibt an, wie viele Objekte maximal in der Szene erkannt werden sollen. Falls mehr als die angegebene Zahl an Objekten gefunden wurden, werden nur die besten Ergebnisse zurückgeliefert.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/parameters?max_number_of_detected_objects=<value>

`load_carrier_model_tolerance` (Modelltoleranz)¶

siehe Parameter der Load Carrier Funktionalität.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/parameters?load_carrier_model_tolerance=<value>

`load_carrier_crop_distance` (Cropping)¶

siehe Parameter der Load Carrier Funktionalität.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/parameters?load_carrier_crop_distance=<value>

`quality` (Qualität)¶

Die Objekterkennung kann auf Bildern mit unterschiedlicher Auflösung durchgeführt werden: High (Hoch, 1280 x 960), Medium (Mittel, 640 x 480) oder Low (Niedrig, 320 x 240). Je niedriger die Auflösung ist, desto niedriger ist die Berechnungszeit der Objekterkennung, aber desto weniger Objektdetails sind erkennbar.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/parameters?quality=<value>

`match_max_distance` (Maximale Matchingdistanz)¶

Dieser Parameter gibt den maximal tolerierten Abstand zwischen dem Template und den detektierten Kanten im Bild in Pixeln an. Falls das Objekt durch das Template nicht exakt genug beschrieben wird, wird es möglicherweise nicht erkannt, wenn dieser Wert zu klein ist. Höhere Werte können jedoch im Fall von komplexen Szenen und bei ähnlichen Objekten zu Fehldetektionen führen, und auch die Berechnungszeit erhöhen.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/parameters?match_max_distance=<value>

`match_percentile` (Matching Perzentil)¶

Dieser Parameter kontrolliert, wie strikt der Detektionsprozess sein soll. Das Matching Perzentil gibt den Anteil der Template-Pixel an, die innerhalb der maximalen Matchingdistanz liegen müssen, um ein Objekt erfolgreich zu detektieren. Je höher der Wert, desto exakter muss ein Match sein, um als gültig angesehen zu werden.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/parameters?match_percentile=<value>

`edge_sensitivity` (Kantenempfindlichkeit)¶

Der Parameter beeinflusst, wie viele Kanten in den Kamerabildern gefunden werden. Umso größer dieser Parameter gewählt wird, umso mehr Kanten werden für die Erkennung benutzt. Eine große Anzahl von Kanten im Bild kann die Erkennung verlangsamen.

Über die REST-API kann dieser Parameter wie folgt gesetzt werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/parameters?edge_sensitivity=<value>

Statuswerte¶

Dieses Modul meldet folgende Statuswerte.

Tab. 29 Statuswerte des `rc_silhouettematch`-Moduls¶
Name	Beschreibung
`calibrate_service_time`	Berechnungszeit für die Kalibrierung der Basisebene, einschließlich der Datenaufnahmezeit
`data_acquisition_time`	Zeit in Sekunden, für die beim letzten Aufruf auf Bilddaten gewartet werden musste
`load_carrier_detection_time`	Berechnungszeit für die letzte Load Carrier Detektion in Sekunden
`detect_service_time`	Berechnungszeit für die Objekterkennung, einschließlich der Datenaufnahmezeit
`last_timestamp_processed`	Zeitstempel des letzten verarbeiteten Bilddatensatzes

Services¶

Die angebotenen Services des rc_silhouettematch-Moduls können mithilfe der REST-API-Schnittstelle oder der rc_cube Web GUI ausprobiert und getestet werden.

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.

Tab. 30 Fehlercodes und Warnung der Services des SilhouetteMatch-Moduls¶
Code	Beschreibung
0	Erfolgreich
-1	Ungültige(s) Argument(e)
-3	Ein interner Timeout ist aufgetreten, beispielsweise während der Objekterkennung.
-4	Die maximal erlaubte Zeitspanne von 5.0 Sekunden für die interne Akquise der Bilddaten wurde überschritten.
-7	Daten konnten nicht in den persistenten Speicher geschrieben oder vom persistenten Speicher gelesen werden.
-8	Das Modul befindet sich in einem Zustand, in welchem dieser Service nicht aufgerufen werden kann. Beispielsweise kann `detect_object` nicht aufgerufen werden, solange keine Kalibrierung der Basisebene durchgeführt wurde.
-10	Das neue Element konnte nicht hinzugefügt werden, da die maximal speicherbare Anzahl an ROIs oder Templates überschritten wurde.
-100	Ein interner Fehler ist aufgetreten.
-101	Die Erkennung der Basisebene schlug fehl.
-102	Die Hand-Auge-Kalibrierung hat sich seit der letzten Kalibrierung der Basisebene verändert.
-104	Die Verkippung zwischen der Basisebene und der Sichtachse der Kamera überschreitet das 10-Grad-Limit.
10	Die maximale Anzahl an ROIs oder Templates wurde erreicht.
11	Ein bestehendes Element wurde überschrieben.
100	Die angefragten Load Carrier wurden in der Szene nicht gefunden.
101	Keiner der Greifpunkte ist erreichbar.
102	Der detektierte Load Carrier ist leer.
103	Alle berechneten Greifpunkte sind in Kollision.
107	Die Basisebene wurde nicht zur aktuellen Kamerapose transformiert, z.B. weil keine Roboterpose während der Kalibrierung der Basisebene angegeben wurde.
108	Das Template ist überholt.
151	Das Objekt-Template hat eine kontinuierliche Symmetrie.
999	Zusätzliche Hinweise für die Anwendungsentwicklung

Das SilhouetteMatch-Modul bietet folgende Services.

`calibrate_base_plane`¶

führt die Kalibrierung der Basisebene durch, wie in Kalibrierung der Basisebene beschrieben. Eine erfolgreiche Kalibrierung der Basisebene wird persistent auf dem rc_cube gespeichert und vom Service zurückgegeben. Die Kalibrierung ist dauerhaft – auch über Firmware-Updates und -Wiederherstellungen hinweg – gespeichert.

Das Zeitverhalten dieses Services garantiert, dass nur Bilddaten zur Erkennung benutzt werden, welche nach dem Anfragezeitpunkt generiert wurden.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/calibrate_base_plane
Request:
Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "offset": "float64",
    "plane": {
      "distance": "float64",
      "normal": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "plane_estimation_method": "string",
    "pose_frame": "string",
    "region_of_interest_2d_id": "string",
    "robot_pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "stereo": {
      "plane_preference": "string"
    }
  }
}
Obligatorische Serviceargumente:

plane_estimation_method: Methode der Kalibrierung der Basisebene. Gültige Werte sind STEREO, APRILTAG, MANUAL.

pose_frame: siehe Hand-Auge-Kalibrierung.

Potentiell obligatorische Serviceargumente:

plane wenn für plane_estimation_method MANUAL gewählt ist: Die Ebene, welche als Basisebene gesetzt wird.

robot_pose: siehe Hand-Auge-Kalibrierung.

region_of_interest_2d_id: ID der Region of Interest für die Kalibrierung der Basisebene.

Optionale Serviceargumente:

offset: Versatz in Metern, um welchen die geschätzte Ebene in Richtung der Kamera verschoben wird.

plane_preference in stereo: Ob die der Kamera am nächsten (CLOSEST) gelegene oder die am weitesten entfernte (FARTHEST) Ebene als Basisebene benutzt wird. Diese Option kann nur gesetzt werden, falls plane_estimation_method auf STEREO gesetzt ist. Valide Werte sind CLOSEST und FARTHEST. Falls der Wert nicht gesetzt ist, wird FARTHEST verwendet.
Response:
Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "calibrate_base_plane",
  "response": {
    "plane": {
      "distance": "float64",
      "normal": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "pose_frame": "string"
    },
    "return_code": {
      "message": "string",
      "value": "int16"
    },
    "timestamp": {
      "nsec": "int32",
      "sec": "int32"
    }
  }
}
plane: kalibrierte Basisebene.

timestamp: Zeitstempel des Bildes, das für die Kalibrierung benutzt wurde.

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

`get_base_plane_calibration`¶

gibt die derzeitige Kalibrierung der Basisebene zurück.

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/get_base_plane_calibration

Request:

Die Definition der Request-Argumente 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"
      }
    }
  }
}

Obligatorische Serviceargumente:

pose_frame: siehe Hand-Auge-Kalibrierung.

Potentiell obligatorische Serviceargumente:

robot_pose: siehe Hand-Auge-Kalibrierung.

Response:

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "get_base_plane_calibration",
  "response": {
    "plane": {
      "distance": "float64",
      "normal": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "pose_frame": "string"
    },
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`delete_base_plane_calibration`¶

löscht die derzeitige Kalibrierung der Basisebene.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/delete_base_plane_calibration
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "delete_base_plane_calibration",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`set_region_of_interest_2d`¶

speichert eine 2D-Region of Interest (ROI) auf dem rc_cube. Alle ROIs sind dauerhaft gespeichert, auch über Firmware-Updates und -Wiederherstellungen hinweg.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/set_region_of_interest_2d
Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "region_of_interest_2d": {
      "height": "uint32",
      "id": "string",
      "offset_x": "uint32",
      "offset_y": "uint32",
      "width": "uint32"
    }
  }
}
region_of_interest_2d: siehe Setzen einer Region of Interest.

Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "set_region_of_interest_2d",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`get_regions_of_interest_2d`¶

gibt die konfigurierten 2D-Regions of Interest (ROI) mit den angegebenen region_of_interest_2d_ids zurück. Wenn keine region_of_interest_2d_ids übergeben werden, werden alle ROIs zurückgegeben.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/get_regions_of_interest_2d
Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "region_of_interest_2d_ids": [
      "string"
    ]
  }
}
Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "get_regions_of_interest_2d",
  "response": {
    "regions_of_interest": [
      {
        "height": "uint32",
        "id": "string",
        "offset_x": "uint32",
        "offset_y": "uint32",
        "width": "uint32"
      }
    ],
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`delete_regions_of_interest_2d`¶

löscht die mit region_of_interest_2d_ids spezifizierten, gespeicherten ROIs. Alle zu löschenden ROIs müssen explizit angegeben werden.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/delete_regions_of_interest_2d
Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "region_of_interest_2d_ids": [
      "string"
    ]
  }
}
Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "delete_regions_of_interest_2d",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`set_load_carrier`¶

siehe set_load_carrier.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/set_load_carrier

`get_load_carriers`¶

siehe get_load_carriers.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/get_load_carriers

`delete_load_carriers`¶

siehe delete_load_carriers.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/delete_load_carriers

`detect_load_carriers`¶

siehe detect_load_carriers.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/detect_load_carriers

`detect_filling_level`¶

siehe detect_filling_level.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/detect_filling_level

`set_preferred_orientation`¶

speichert die bevorzugte TCP-Orientierung zum Berechnen der Erreichbarkeit der Greifpunkte, die zur Sortierung und Filterung der vom detect_object Service zurückgelieferten Greifpunkte verwendet wird (siehe Setzen der bevorzugten TCP-Orientierung).

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/set_preferred_orientation
Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "orientation": {
      "w": "float64",
      "x": "float64",
      "y": "float64",
      "z": "float64"
    },
    "pose_frame": "string"
  }
}
Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "set_preferred_orientation",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`get_preferred_orientation`¶

gibt die bevorzugte TCP-Orientierung zurück, die für die Sortierung und Filterung der vom detect_object Service zurückgelieferten Greifpunkte verwendet wird (siehe Setzen der bevorzugten TCP-Orientierung).

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/get_preferred_orientation
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "get_preferred_orientation",
  "response": {
    "orientation": {
      "w": "float64",
      "x": "float64",
      "y": "float64",
      "z": "float64"
    },
    "pose_frame": "string",
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`set_grasp`¶

speichert einen Greifpunkt für das angegebene Template auf dem rc_cube. Alle Greifpunkte sind dauerhaft gespeichert, auch über Firmware-Updates und -Wiederherstellungen hinweg.

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/set_grasp

Die Definition der Request-Argumente mit jeweiligen Datentypen ist:

{
  "args": {
    "grasp": {
      "id": "string",
      "pose": {
        "orientation": {
          "w": "float64",
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "position": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        }
      },
      "template_id": "string"
    }
  }
}

Die Definition der Response mit jeweiligen Datentypen ist:

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

Die Definition des Typs grasp wird in Setzen von Greifpunkten beschrieben.

`set_all_grasps`¶

Ersetzt die gesamte Liste von Greifpunkten auf dem rc_cube für das angegebene Template.

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/set_all_grasps

Die Definition der Request-Argumente mit jeweiligen Datentypen ist:

{
  "args": {
    "grasps": [
      {
        "id": "string",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "template_id": "string"
      }
    ],
    "template_id": "string"
  }
}

Die Definition der Response mit jeweiligen Datentypen ist:

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

Die Definition des Typs grasp wird in Setzen von Greifpunkten beschrieben.

`get_grasps`¶

gibt alle definierten Greifpunkte mit den angegebenen IDs (grasp_ids) zurück, die zu den Templates mit den angegebenen template_ids gehören. Wenn keine grasp_ids angegeben werden, werden alle Greifpunkte zu den angegebenen template_ids zurückgeliefert. Wenn keine template_ids angegeben werden, werden alle Greifpunkte mit den geforderten grasp_ids zurückgeliefert. Wenn gar keine IDs angegeben werden, werden alle gespeicherten Greifpunkte zurückgeliefert.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/get_grasps
Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "grasp_ids": [
      "string"
    ],
    "template_ids": [
      "string"
    ]
  }
}
Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "get_grasps",
  "response": {
    "grasps": [
      {
        "id": "string",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "template_id": "string"
      }
    ],
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`delete_grasps`¶

löscht alle Greifpunkte mit den angegebenen grasp_ids, die zu den Templates mit den angegebenen template_ids gehören. Wenn keine grasp_ids angegeben werden, werden alle Greifpunkte gelöscht, die zu den Templates mit den angegebenen template_ids gehören. Die Liste template_ids darf nicht leer sein.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/delete_grasps
Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "grasp_ids": [
      "string"
    ],
    "template_ids": [
      "string"
    ]
  }
}
Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "delete_grasps",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

`get_symmetric_grasps`¶

gibt alle Greifpunkte zurück, die symmetrisch zum angegebenen Greifpunkt sind. Der erste Greifpunkt in der Rückgabeliste ist derselbe, der dem Service übergeben wurde. Wenn das Template keine exakte Symmetrie hat, wird nur der übergebene Greifpunkt zurückgeliefert. Wenn das Template eine kontinuierliche Symmetrie hat (z.B. ein zylindrisches Objekt), werden nur 12 gleichverteilte Greifpunkte zurückgeliefert.

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/get_symmetric_grasps

Die Definition der Request-Argumente mit jeweiligen Datentypen ist:

{
  "args": {
    "grasp": {
      "id": "string",
      "pose": {
        "orientation": {
          "w": "float64",
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "position": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        }
      },
      "template_id": "string"
    }
  }
}

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "get_symmetric_grasps",
  "response": {
    "grasps": [
      {
        "id": "string",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "template_id": "string"
      }
    ],
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

Die Definition des Typs grasp wird in Setzen von Greifpunkten beschrieben.

`detect_object`¶

führt eine Objekterkennung durch, wie in Objekterkennung beschrieben. Der Service gibt die Posen aller gefundenen Objektinstanzen zurück. Die maximale Anzahl der zurückgegebenen Instanzen kann über den max_number_of_detected_objects-Parameter kontrolliert werden.

Das Zeitverhalten dieses Services garantiert, dass nur Bilddaten zur Erkennung benutzt werden, welche nach dem Anfragezeitpunkt generiert wurden.

Dieser Service kann wie folgt aufgerufen werden.

PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/detect_object

Request:

Die Definition der Request-Argumente mit jeweiligen Datentypen ist:
{
  "args": {
    "collision_detection": {
      "gripper_id": "string",
      "pre_grasp_offset": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "load_carrier_id": "string",
    "object_to_detect": {
      "object_id": "string",
      "region_of_interest_2d_id": "string"
    },
    "offset": "float64",
    "pose_frame": "string",
    "robot_pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    }
  }
}
Obligatorische Serviceargumente:

object_id in object_to_detect: ID des Templates, welches erkannt werden soll.

pose_frame: siehe Hand-Auge-Kalibrierung.

Potentiell obligatorische Serviceargumente:

robot_pose: siehe Hand-Auge-Kalibrierung.

Optionale Serviceargumente:

offset: Versatz in Metern, um welche die Basisebene in Richtung der Kamera verschoben werden soll.

load_carrier_id: ID des Load Carriers, welcher die zu erkennenden Objekte enthält.

collision_detection: siehe Integrierte Kollisionsprüfung in anderen Modulen

Response:

Die Definition der Response mit jeweiligen Datentypen ist:

{
  "name": "detect_object",
  "response": {
    "grasps": [
      {
        "id": "string",
        "instance_uuid": "string",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "timestamp": {
          "nsec": "int32",
          "sec": "int32"
        },
        "uuid": "string"
      }
    ],
    "instances": [
      {
        "grasp_uuids": [
          "string"
        ],
        "id": "string",
        "object_id": "string",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "timestamp": {
          "nsec": "int32",
          "sec": "int32"
        },
        "uuid": "string"
      }
    ],
    "load_carriers": [
      {
        "id": "string",
        "inner_dimensions": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "outer_dimensions": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "overfilled": "bool",
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "rim_thickness": {
          "x": "float64",
          "y": "float64"
        }
      }
    ],
    "object_id": "string",
    "return_code": {
      "message": "string",
      "value": "int16"
    },
    "timestamp": {
      "nsec": "int32",
      "sec": "int32"
    }
  }
}

object_id: ID des erkannten Templates.

instances: Liste der erkannten Objektinstanzen.

grasps: Liste von Greifpunkten auf den erkannten Objekten. Die Greifpunkte sind nach ihrer Erreichbarkeit sortiert, begonnen mit dem Greifpunkt, der am besten vom Roboter erreicht werden kann. Die instance_uuid gibt eine Referenz auf das detektierte Objekt in instances an, zu dem dieser Greifpunkt gehört.

load_carriers: Liste der erkannten Load Carrier (Behälter).

timestamp: Zeitstempel des Bildes, das für die Erkennung benutzt wurde.

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

`save_parameters`¶

speichert die aktuellen Parametereinstellungen des SilhouetteMatch-Moduls auf dem rc_cube. Das bedeutet, dass diese Werte selbst nach einem Neustart angewandt werden. Bei Firmware-Updates oder -Wiederherstellungen werden sie jedoch wieder auf den Standardwert gesetzt.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/save_parameters
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`¶

stellt die Werkseinstellungen der Parameter dieses Moduls wieder her und wendet sie an („factory reset“). Dies betrifft nicht die konfigurierten ROIs und die Kalibrierung der Basisebene.

Dieser Service kann wie folgt aufgerufen werden.
PUT http://<host>/api/v1/nodes/rc_silhouettematch/services/reset_defaults
Dieser Service hat keine Argumente.

Die Definition der Response mit jeweiligen Datentypen ist:
{
  "name": "reset_defaults",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

Template Upload¶

Für den Upload, Download und das Auflisten von Templates werden spezielle REST-API-Endpunkte zur Verfügung gestellt. Bis zu 50 Templates können gleichzeitig auf dem rc_cube gespeichert werden.

GET /nodes/rc_silhouettematch/templates¶

listet alle rc_silhouettematch-Templates auf.

Musteranfrage

GET /api/v1/nodes/rc_silhouettematch/templates HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "string"
  }
]

Referenzierte Datenmodelle:
Antwort-Header:	Content-Type – application/json
Statuscodes:	200 OK – Erfolgreiche Verarbeitung (Rückgabewert: Array der Templates) 404 Not Found – Modul nicht gefunden
	Template

GET /nodes/rc_silhouettematch/templates/{id}¶

ruft ein rc_silhouettematch-Template ab. Falls der angefragte Content-Typ application/octet-stream ist, wird das Template als Datei zurückgegeben.

Musteranfrage

GET /api/v1/nodes/rc_silhouettematch/templates/<id> HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "string"
}

Referenzierte Datenmodelle:
Parameter:	id (string) – ID des Templates (obligatorisch)
Antwort-Header:	Content-Type – application/json application/octet-stream
Statuscodes:	200 OK – Erfolgreiche Verarbeitung (Rückgabewert: Template) 404 Not Found – Modul oder Template wurden nicht gefunden.
	Template

PUT /nodes/rc_silhouettematch/templates/{id}¶

erstellt oder aktualisiert ein rc_silhouettematch-Template.

Musteranfrage

PUT /api/v1/nodes/rc_silhouettematch/templates/<id> HTTP/1.1
Accept: multipart/form-data application/json

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "string"
}

Formularparameter:
Parameter:	id (string) – ID des Templates (obligatorisch)
	file – Template-Datei (obligatorisch)
Anfrage-Header:	Accept – multipart/form-data application/json
Antwort-Header:	Content-Type – application/json
Statuscodes:	200 OK – Erfolgreiche Verarbeitung (Rückgabewert: Template) 400 Bad Request – Template ist ungültig oder die maximale Zahl an Templates wurde erreicht. 403 Forbidden – Verboten, z.B. weil keine gültige Lizenz für das SilhouetteMatch-Modul vorliegt. 404 Not Found – Modul oder Template wurden nicht gefunden. 413 Request Entity Too Large – Template ist zu groß.
Referenzierte Datenmodelle:
	Template

DELETE /nodes/rc_silhouettematch/templates/{id}¶

entfernt ein rc_silhouettematch-Template.

Musteranfrage

DELETE /api/v1/nodes/rc_silhouettematch/templates/<id> HTTP/1.1
Accept: application/json

Parameter:	id (string) – ID des Templates (obligatorisch)
Anfrage-Header:	Accept – application/json
Antwort-Header:	Content-Type – application/json
Statuscodes:	200 OK – Erfolgreiche Verarbeitung 403 Forbidden – Verboten, z.B. weil keine gültige Lizenz für das SilhouetteMatch-Modul vorliegt. 404 Not Found – Modul oder Template wurden nicht gefunden.

SilhouetteMatch¶

Einführung¶

Taugliche Objekte¶

Taugliche Szene¶

Kalibrierung der Basisebene¶

AprilTag-basierte Kalibrierung der Basisebene¶

Stereo-basierte Kalibrierung der Basisebene¶

Manuelle Kalibrierung der Basisebene¶

Setzen einer Region of Interest¶

Setzen von Greifpunkten¶

Setzen von Greifpunken in der Web GUI¶

Setzen von Greifpunkten über die REST-API¶

Setzen der bevorzugten TCP-Orientierung¶

Objekterkennung¶

Wechselwirkung mit anderen Modulen¶

Stereokamera und Stereo-Matching¶

IOControl und Projektor-Kontrolle¶

Hand-Auge-Kalibrierung¶

CollisionCheck¶

Parameter¶

Übersicht über die Parameter¶

Beschreibung der Laufzeitparameter¶

max_number_of_detected_objects (Maximale Objektanzahl)¶

load_carrier_model_tolerance (Modelltoleranz)¶

load_carrier_crop_distance (Cropping)¶

quality (Qualität)¶

match_max_distance (Maximale Matchingdistanz)¶

match_percentile (Matching Perzentil)¶

edge_sensitivity (Kantenempfindlichkeit)¶

Statuswerte¶

Services¶

calibrate_base_plane¶

get_base_plane_calibration¶

delete_base_plane_calibration¶

set_region_of_interest_2d¶

get_regions_of_interest_2d¶

delete_regions_of_interest_2d¶

set_load_carrier¶

get_load_carriers¶

delete_load_carriers¶

detect_load_carriers¶

detect_filling_level¶

set_preferred_orientation¶

get_preferred_orientation¶

set_grasp¶

set_all_grasps¶

get_grasps¶

delete_grasps¶

get_symmetric_grasps¶

detect_object¶

save_parameters¶

reset_defaults¶

Template Upload¶

`max_number_of_detected_objects` (Maximale Objektanzahl)¶

`load_carrier_model_tolerance` (Modelltoleranz)¶

`load_carrier_crop_distance` (Cropping)¶

`quality` (Qualität)¶

`match_max_distance` (Maximale Matchingdistanz)¶

`match_percentile` (Matching Perzentil)¶

`edge_sensitivity` (Kantenempfindlichkeit)¶

`calibrate_base_plane`¶

`get_base_plane_calibration`¶

`delete_base_plane_calibration`¶

`set_region_of_interest_2d`¶

`get_regions_of_interest_2d`¶

`delete_regions_of_interest_2d`¶

`set_load_carrier`¶

`get_load_carriers`¶

`delete_load_carriers`¶

`detect_load_carriers`¶

`detect_filling_level`¶

`set_preferred_orientation`¶

`get_preferred_orientation`¶

`set_grasp`¶

`set_all_grasps`¶

`get_grasps`¶

`delete_grasps`¶

`get_symmetric_grasps`¶

`detect_object`¶

`save_parameters`¶

`reset_defaults`¶