HalconWrapperTool

Das Tool integriert die HDevelop-Engine aus der Bildverarbeitungs-Bibliothek Halcon der Firma MVTec in VisionPro. Ein HalconWrapperTool implementiert den Aufruf einer Halcon-Prozedur als VisionPro-Tool. Die Schnittstellenparameter der Prozeduren werden als Tool-Terminals eingebunden. Bei Bedarf erfolgt eine semi-automatische Konvertierung zwischen Halcon- und VisionPro-Datentypen: Zwischen Halcon-Tools können Parameter als Halcon-Datentypen ausgetauscht werden, zur Interoperabilität mit Vision-Pro-Tools müssen die Parameter konvertiert werden.

Vorbereiten der Prozedur

Damit Prozedur-Parameter im HalconWrapperTool als Terminals verfügbar werden, müssen in HDevelop die Parameterdokumentation der Prozedur ausreichend befüllt werden: Für alle benötigten Parameter, insbesondere alle Eingabe-Parameter, muss stets mindestens die Semantik des Parameters dokumentiert werden. Soll eine Konvertierung des Parameters zu VisionPro-/System-Datentypen erfolgen, so müssen zusätzliche Angaben erfolgen, die im Anschluss für die einzelnen Parametertypen aufgeführt werden.

1. Öffnen der Prozedur-Schnittstellen-Einstellung im HDevelop Skript-Editor

2. Öffnen der Prozedur-Schnittstellen-Einstellung in der HDevelop Menüleiste

3. Dokumentation der Prozedur-Parameter in den Schnittstellen-Einstellungen

4. Bearbeiten der Dokumentation einzelner Prozedur-Parameter, beispielhaft ein Bild-Parameter

Bilder

Das Wrapper-Tool erzeugt für dokumentierte Ein- und Ausgabe-Bilder Terminals mit dem Präfix InputImage beziehungsweise OutputImage. Dazu muss immer mindestens die Semantik image in der Parameter-Dokumentation eingestellt werden. Bei vollständiger Dokumentation wird ein Konvertierung von und zu Cognex Bildtypen für folgende Typen unterstützt:

Cognex-Typ	Semantik	Pixeltypen	Mehrkanalig	Mehrere Werte
CogImage8Grey	image	byte	Nein	Nein
CogImage16Grey	image	uint2	Nein	Nein
CogImage24GreyColor	image	byte	Ja (3)	Nein

Hinweis

Nutzen mehrere Halcon-Wrapper-Tools das selbe Eingabe-Bild empfiehlt sich die Nutzung eines HalconCognexConverterTool zur Konvertierung des Cognex-Bildes in ein Halcon-Bild. Indem die HalconWrapperTools das Bild direkt als Halcon-Input empfangen, wird Zeit für redundante Konvertierungen eingespart.

Regionen

Das Wrapper-Tool erzeugt für dokumentierte Ein- und Ausgabe-Regionen Terminals mit dem Präfix InputRegions beziehungsweise OutputRegions. Dazu muss in der Parameter-Dokumentation der Prozedur immer mindestens die Semantik region eingestellt werden. Bei der Konvertierung von- und zu Cognex-Typen muss zwischen Ein- und Ausgabe-Terminals unterschieden werden. Sie wird mit den folgenden zusätzlichen Angaben in der Parameter-Dokumentation unterstützt:

Cognex-Typ Input-Terminal	Semantik	Mehrere Werte
CogCircle CogEllipse CogRectangle CogRectangleAffine CogLineSegment CogPolygon	region	Nein

Cognex-Typ Ausgabe-Terminal	Semantik	Mehrere Werte
CogPolygon	region	Nein

Hinweis

Halcon-Regionen definieren pixel-genaue Flächen, während die geometrischen primitive subpixel-genau definiert sind. Die Konvertierung erzeugt die beste Annäherung durch einen möglichst spezifischen Operatoraufruf, zum Beispiel gen_circle. Ausgabe-Regionen werden stets als Polygon angenähert. Die Näherung erfolgt mit dem Halcon-Operator get_region_polygon, mit Tolerance 0.01 Pixel.

Warnung

Die Konvertierung von Ausgabe-Regionen zu Cognex-Polygonen ignoriert Hohlflächen und gibt nur die Hülle zurück! Nur eine Zusammenhangskomponente wird zurückgegeben (in der Regel die erste, siehe Halcon-Operator get_region_polygon).

XLDs

Für dokumentierte Ein- und Ausgabe-XLDs werden Terminals mit dem Präfix OutputXlds beziehungsweise InputXlds erzeugt. Dazu muss in der Parameterdokumentation mindestens die Semantik xld eingestellt werden. Die Semantik kann optional auch maximal spezifisch angegeben werden, zum Beispiel als xld_poly.

Ein automatische Konvertierung zu Cognex-Datentypen wird für XLDs nicht unterstützt. An den Terminals wird ein Wrapper um den Halcon-Typen bereitgestellt.

Control-Parameter / Tupel

Mit Ausnahme von Vektoren können Control-Parameter ohne Parameter-Dokumentation als Ein- oder Ausgabe-Terminals genutzt werden. Ohne Angabe der Semantik in der Parameter-Dokumentation ist jedoch nur ein Terminal-Zugriff als HTupel möglich. Parameter vom Typ HVector werden nicht unterstützt. Die Terminals werden in der Regel mit dem Präfix InputControlVariables beziehungsweise OutputControlVariables erzeugt. Ausnahmen sind hinreichend dokumentierte Parametertypen von Ressourcen wie camera_setup_model, welche beispielsweise mit dem Präfix InputCameraSetupModels erstellt werden. Mit den folgenden Dokumentations-Einstellungen ist auch ein Zugriff in Form der genannten System-Typen möglich:

Cognex-Typ	Semantik	Typliste	Standardtyp	gemischte Typen	mehrere Werte
System.Integer	integer	integer	integer	Nein	Nein
System.Integer[]	integer	integer	integer	Nein	Ja
System.Double[]	real	real	real	Nein	Nein
System.Double[]	real	real	real	Nein	Ja
System.String	string	byte	string	Nein	Nein
System.String[]	string	byte	string	Nein	Ja
HTupleOm3Box	object_model_3d	-	-	-	-
HTupleCameraSetupBox	camera_setup_model	-	-	-	-
HTupleCalibModelBox	calib_data	-	-	-	-

Hinweis

Die Wrapper-Objekte HTupleOm3Box implementieren eine Referezzählung und automatische Ressourcen-Freigabe. Ab Halcon 18.11 ist deren Nutzung nicht mehr erforderlich, sofern nicht der Halcon-Modus legacy_handle_mode aktiviert wird (nicht empfohlen). Bei aktivem legacy_handle_mode oder mit älteren Halcon-Versionen sollten die Wrapper-Typen genutzt werden um Speicherlecks zu vermeiden. Ressourcen die an derartigen Terminals übergeben werden, müssen und dürfen dann nicht vom Benutzer freigegeben werden.

Prozedur-Einstellung

Eine Tool-Instanz dient als Wrapper um genau eine Halcon-Prozedur. Geladen werden können sowohl lokale Prozeduren aus einer Programm-Datei (.hdev), als auch globale Prozeduren aus einzelnen Prozedur-Dateien (.hdvp). Empfohlen wird die Nutzung lokaler Prozeduren in Programmdateien.

Einstellung und Laden von Prozeduren erfolgen im Settings Tab des Tool-Editors:

1. Local procedure (.hdev): definiert, dass das Tool eine lokale Prozedur mit den angegebenen Einstellungen lädt.

2. HDev program folder: Verzeichnis-Pfad, in welchem die Programm-Datei (.hdev) liegt. Die Schaltfläche unterstützt Drag-And-Drop. Mit den Buttons rechts kann ein Ordner per Dateibrowser gewählt beziehungsweise der eingestellte Ordner im Browser geöffnet werden. Ändern des Pfades löst das Neu-Laden der Prozedur aus.

3. HDev program file: Auswahl einer Programmdatei (.hdev) innerhalb des Programm-Ordners aus dem die Prozedur geladen wird. Mit den Buttons rechts kann ein Dateibrowser zur Dateiwahl geöffnet und die Dropdown-liste aktualisiert werden (durchsucht das Verzeichnis nach relevanten Dateien). Das gewählte Programm wird erst bei einem Button-Klick auf Load program geladen.

4. HDev procedure: Auswahl der Prozedur innerhalb des geladenen Programms.

5. Current file und Changed at: Zeigt die aktuell geladene Programm-Datei und den Zeitpunkt des Ladens an.

6. Global procedure (.hdvp): definiert, dass das Tool eine globale Prozedur mit den angegebenen Einstellung lädt.

7. Custom procedure folder: Pfad, der Prozedurdateien (.hdvp) enthält. Ändern des Pfades löst das Neu-Laden der Prozedur aus. Mit den Buttons rechts kann ein Auswahl per Dateibrowser erfolgen beziehungsweise der Wert gelöscht werden. Ist kein Prozedurpfad eingestellt, so

8. HDev procedure: Name der Prozedur. Aufgelistet werden die Dateinamen innerhalb des Custom procedure folder (welche per Konvention mit dem Namen der enthaltenen Prozedur übereinstimmen). Mit den Buttons rechts kann eine Auswahl per Dateibrowser erfolgen, die Dropdown-Liste aktualisiert werden (bei Änderungen am Dateisystem). Erst ein Button-Klick auf Load procedure löst das Neu-Laden der gewählten Prozedur aus, reine Änderungen der Auswahl ändern noch nicht den Tool-Status.

9. Current file und Changed at: Zeigt den Namen der aktuell geladenen Prozedur und den Lade-Zeitpunkt an.

Terminals

Der Zugriff auf Ein- und Ausgabeparameter einer Prozedur erfolgt über Tool-Terminals. Beim Laden einer Prozedur werden Platzhalter für die Terminal-daten angelegt. Voraussetzung für die Erzeugung ist, dass in der Halcon-Parameterdokumentation der Prozedur die Datentypen der Parameter hinreichend und korrekt definiert sind. Bei ausreichender Dokumentation können auch automatische Konvertierungen von und zu Vision-Pro oder System-Datentypen erfolgen. Die notwendigen Dokumentations-Einträge und unterstützte Konvertierungen sind unter Vorbereiten der Prozedur beschrieben. Der Nutzer kann nach erfolgreichem Laden einer Prozedur im Terminals-Tab die Erzeugung von Terminals auslösen, welche auf die genannten Datenstrukturen verweisen. Dabei kann festgelegt werden, ob ein Terminals mit Halcon- oder Cognex-Datentyp (oder beide) erzeugt werden sollen.

Hinweis

Werden für einen Ausgabeparameter Terminals beider Typen angelegt, können beide Terminals genutzt werden. Bei Eingabe-Parametern hingegen darf jeweils nur genau ein Terminal verbunden werden, auch wenn zwei erzeugt werden können (damit die Zuweisung des Eingabewertes eindeutig ist).

Die Konfiguration erfolgt gegliedert nach den Datentypen der Parameter.

1. 2D/3D, Iconic Variables/Control Variables: Auswahl einer Parameterkategorie: 3D Parameter (ObjectModel3D und CameraSetupModel Handles) oder 2D Parameter, wiederum untergliedert in Ikonische und Steuerungs-Parameter.

2. Detail: Die Terminals aller Prozedur-Parameter des jeweiligen Halcon-Datentyps werden individuell konfiguriert. Die Prozedur-Parameter werden zur Konfiguration in der Details-Liste hinzugefügt.

3. Fast: Die Terminals aller Prozedur-Parameter des jeweiligen Halcon-Datentyps werden generisch konfiguriert: Die Optionen rechts definieren die zu erzeugenden Terminals.

4. Use Inputs: Gibt bei Verwendung von Fast an, ob die Terminals für alle Eingabe-Parameter erzeugt werden sollen. Das Terminal type Dropdown definiert, mit welchen Datentypen die Terminals erzeugt werden sollen: Halcon-Typen, Cognex-Typen oder Both. Letzteres erzeugt für jeden Parameter zwei Terminals: je eines mit Congex- und Halcon-Datentyp. Bei Eingabeparametern kann vom Nutzer jeweils nur ein einziges Terminal verbunden werden!

5. Use Outputs: Gibt bei Verwendung von Fast an, ob die Terminals für alle Ausgabe-Parameter erzeugt werden sollen. Das Terminal type Dropdown definiert, mit welchen Datentypen die Terminals erzeugt werden sollen: Halcon-Typen, Cognex-Typen oder Both.

6. Details: Eine Liste der Prozedur-Parameter, deren Terminal-Erzeugung aufgrund einer Detail Einstellung individuell konfiguriert wird.

• Use: Falls gewählt, wird für den Parameter ein Terminal erzeugt.

• Name: Name des Prozedur-Parameters

• Type: Halcon-Typ des Parameters

• TerminalType: Auswahl des Typs des zu erzeugenden Terminals: Cognex, Halcon oder Both

• IsCognexSupported: Zeigt an, ob eine Konvertierung zwischen Halcon und Cognex-Datentypen möglich ist. Falls nicht, ist entweder die Halcon-Parameterdokumentation unvollständig oder eine Konvertierung ist nicht unterstützt.

• Direction: Art des Prozedur-Parameters: Input oder Output.

7. sort terminals by name: definiert die Reihenfolge der erzeugten Terminals. Falls gewählt werden die Terminals alphabetisch nach dem Namen sortiert.

8. Generate terminals: Löst die (Re-)Generierung der Prozedur-Parameter-Terminals aus. Existierende Parameter-Terminals , die nicht den Einstellungen entsprechen werden entfernt, falls sie nicht den Einstellungen entsprechen.

Texteditor Tab

Im Tab Textditor kann der Quellcode lokaler Prozeduren des geladenen HDevelop Skripts angezeigt und bearbeitet werden.

1. Current HALCON file: Pfad der Programmdatei, die im Tool geladen ist.

2. Reload: Löst ein erneutes Laden der Programmdatei und der enthaltenen Prozeduren aus. Durch erneutes Laden werden ungespeicherte Quellcode-Änderungen im Editor verworfen.

3. Procedure: Name der aktuell im Editor angezeigten Prozedur.

4. Editor: Anzeige und Bearbeitung des Quellcodes. Änderungen am Code werden erst durch Bestätigung mittels Apply oder Save aktiviert werden.

5. Apply: Wendet Code-Änderungen auf das Tool an: Bei Ausführung des Tools wirkt dann der bearbeitete Code. Die originale Quellcodedatei bleibt jedoch unverändert, das Tool lädt die Änderungen aus einer temporären Datei. Beim Schließen des Tool-Editors wird der persistent gespeicherte Original-Zustand wiederhergestellt. Nur syntaktisch korrekte Programme können angewandt werden.

6. Cancel: Bricht Code-Änderungen ab und stellt den vorherigen Code-Zustand wieder her. Die Wiederherstellung erfolgt in zwei Stufen: enthält der Editor Änderungen, die weder angewandt noch gespeichert wurden, werden zunächst diese zurückgesetzt, so dass im Editor der aktuell ausgeführte Code angezeigt wird. Erst danach wird der persistent gespeicherte Code wiederhergestellt und somit alle Änderungen verworfen, die durch Apply aktiviert wurden. Nach dem Zurücksetzen sind angezeigter und aktiv ausgeführter Code stets identisch.

7. Save: Speichert die vorgenommenen Änderungen in der Programmdatei. Nur syntaktisch fehlerfreie Programme können gespeichert werden. Gespeichert werden alle Änderungen innerhalb des Programms, auch diejenigen an nicht angezeigten Prozeduren.

8. State: beschreibt den angezeigten Code-Zustand:

• editor contains inactive changes gibt an, dass der angezeigte Code Änderungen enthält, die bei der Tool-Ausführung nicht aktiv wirksam sind.

• tool using temporary file gibt an, dass bei Tool-Ausführung Code aktiv ist, der zuletzt mittels Apply übernommen wurde. Die Änderungen wurden jedoch noch nicht gespeichert und gehen beim Schließen des Tool-Editors verloren.

Inputs/Outputs Tab

Die Tabs Inputs und Outputs zeigen alle dokumentierten Eingabe bzw. Ausgabe-Parameter wie beispielsweise Bilder, Regionen und Steuervariablen an. Die Anzeige ist nach Parametertyp in Unter-Tabs wie „Images“, „Regions“ und „Control variables“ gegliedert. Der Tab „Outputs“ ist identisch zum Tab „Inputs” aufgebaut. Nachfolgend werden die einzelnen Unter-Tabs anhand der Inputs erläutert.

Images Tab

1. Input HImages: Auswahl eins Bildes zur Anzeige

2. Fit: Skalierung des Bildes. FitImage passt das Bild unter Beibehaltung des Seitenverhältnisses in das Fenster ein.

3. Display: Anzeige des Bildes

Hinweis

Die Ansicht wird durch Ausführen des Tools aktualisiert

Regions Tab

1. Regionslist: Zeigt die verfügbaren Parameter vom Typ Region. Die Ausgewählte Region wird im Display angezeigt.

2. Input HImages: Auswahl eines Bildes als Hintergrund der Anzeige.

3. Fit: Definiert den Skalierungsmodus des Bildes: FitImage passt das Bild unter Beibehaltung des Seitenverhältnisses in das Fenster ein.

4. Refresh Region: Aktualisiert die Anzeige.

5. Display: Anzeige der gewählten Region über dem gewählten Bild.

Control Variables Tab

Alle Control Parameter werden in einer Liste angezeigt. Die Spalten zeigen folgende Werte:

• Id: Name des Parameters

• MinEnabled: Minimum aktivieren

• Min: dokumentierter Minimalwert

• Value: Aktueller Wert

• Max: Maximalwert

• MaxEnabled: Maximalwert aktivieren