TechTipps

„Dynamic Vision App for HALCON“

In wenigen Schritten von der HALCON Bildverarbeitung zur IDS NXT Vision App

Dynamic Vision App for HALCON

Mit der „Dynamic Vision App for HALCON“ können Sie Ihre mit HALCON entwickelte Bildverarbeitung einfach in einer IDS NXT Kamera ausführen. Zeitaufwändige Vision App-Entwicklung in C++ ist für HALCON-Nutzer nicht mehr nötig! Die „Dynamic Vision App for HALCON“ macht es möglich. Damit ist sie die perfekte Ergänzung für Ihre Bildverarbeitungsentwicklung.

Der TechTipp zeigt Ihnen, wie Sie mit wenigen Schritten eine passende HALCON Bibliothek in HDevelop erstellen und diese über das IDS NXT Cockpit einfach auf einen IDS NXT vegas hochladen und ausführen, ohne eine Zeile C++ Code zu schreiben. Das einfache Bildverarbeitungsbeispiel example_code2d.hdpl" sucht in den aufgenommenen Bilddaten nach Datamatrix-Codes und markiert diese in den Ergebnisbildern der Vision App. Zusätzlich werden die Code-Inhalte als Text ausgegeben. Das von IDS entwickelte IDS NXT Framework lässt Ihnen durch individuelle Entwicklung von Vision Apps die völlige Freiheit, was Sie auf Vision App-basierten Kameras ausführen. Das IDS NXT Vision App Development Kit unterstützt Sie bei der Entwicklung und Ausführung Ihrer individuellen Vision App, wozu lediglich C++ Kenntnisse vorausgesetzt werden. Viel einfacher macht es Ihnen jedoch die neu entwickelte „Dynamic Vision App for HALCON“. Damit ist sie die perfekte Ergänzung für Ihre Bildverarbeitungsentwicklung. Möchten Sie lediglich Bildverarbeitung mit dem bereits vorinstallierten HALCON ausführen, nimmt Ihnen diese generische App die zeitaufwendige Vision App-Erstellung in C++ komplett ab. Dabei führt diese nicht nur in HDevelop geschriebene HALCON Bildverarbeitung aus, sondern stellt die definierten Eingabe- und Ausgabeparameter mittels der REST-Schnittstelle zur Verfügung. Die „Dynamic Vision App for HALCON“ zeigt diese Parameter zudem im IDS NXT Cockpit, wodurch Sie Ihre Bildverarbeitung komfortabel konfigurieren und prüfen können.

Direktes Ausführen von HALCON Bibliotheken.
Direktes Ausführen von HALCON Bibliotheken.

Voraussetzungen

Zur Vorbereitung zu dem hier beschriebenen Vorgehen und zum besseren Verständnis des IDS NXT Konzepts bietet sich das Handbuch „IDS NXT - Entwicklung von Vision Apps“ sowie die IDS NXT Video Tutorials an. Um den TechTipp nachzuvollziehen benötigen Sie:

  • IDS NXT vegas (Firmware ab Version 1.3)
  • Windows PC (mit Netzwerkverbindung zum IDS NXT vegas)
    • Lizenzierte HALCON 13 Entwicklungsumgebung
    • IDS NXT Cockpit (ab Version 1.2.4)
  • „Dynamic Vision App for HALCON“

 

Installieren und aktivieren Sie die „Dynamic Vision App for HALCON“ auf dem IDS NXT vegas über das IDS NXT Cockpit. Wie Sie eine Vision App installieren, lesen Sie in Kapitel „Vision App Manager“ im Handbuch „IDS NXT - Bedienung“.

Starten der „Dynamic Vision App for HALCON“ im VApp Manager
Starten der „Dynamic Vision App for HALCON“ im VApp Manager

Wurde die Vision App erfolgreich gestartet, erscheint im Konfigurationsbereich des IDS NXT Cockpits deren Einstellungsdialog. Darüber können Sie kompatible HALCON Bibliotheken hochladen, deren Entwicklung nachfolgend erklärt wird.

Die Installation und Deinstallation von IDS NXT Vision Apps kann nur vom Administrator-Benutzer vorgenommen werden!

HALCON Entwicklung

Die „Dynamic Vision App for HALCON“ stellt die Verbindung zwischen einer „HDevelop procedure library“ (HDPL) und dem IDS NXT Framework einer Vision App-basierte Kameras der IDS NXT Familie her. Steuerparameter und Ergebnisse der Bildverarbeitung werden dadurch der Kamera REST-Schnittstelle und dem IDS NXT Cockpit zur Verfügung gestellt. So kann die Bildverarbeitung direkt wie eine vollständige Vision App bedient werden.

Um die Kompatibilität der HALCON Bibliothek mit der Dynamic Vision App zu gewährleisten, müssen HALCON Prozeduren mit bestimmten Namen vorhanden sein, deren Eingabe- und Ausgabeparameter (Prozedurschnittstelle) genau bestimmt sind (Semantiktypen). Nur dann kann die „Dynamic Vision App for HALCON“ automatisch die passenden Konfigurations- oder Ergebnisvariablen auswählen, welche über die REST-Schnittstelle bereitgestellt werden.

Die „Dynamic Vision App for HALCON“ stellt die Verbindung zwischen HALCON und dem IDS NXT Framework her.
Die „Dynamic Vision App for HALCON“ stellt die Verbindung zwischen HALCON und dem IDS NXT Framework her.

Aufbau der HALCON Bibliothek

Für die Kommunikation zwischen der Dynamic Vision App und der HALCON Bildverarbeitung müssen folgende HDPL-Prozeduren als Einstiegspunkte angelegt sein:

  • „init“ - wird beim Laden der Bibliothek ausgeführt. Hier werden InputCtrlParams (Variablen, Steuerparameter) und OutputCtrlParams (Anzeigen, Ergebnisse) registriert.
  • „finalize“ - wird vor dem Entladen der Bibliothek aufgerufen und räumt alle in "init" angelegten Datenstrukturen auf.
  • „train“ - erlaubt ein Training der HALCON Bildverarbeitung. Diese Prozedur ist optional. Wenn vorhanden, wird das entsprechende Training durchgeführt.
  • „process“ - ist die Bearbeitungsfunktion der eigentlichen Bildverarbeitung.

Prozeduren anlegen

Legen Sie in HDevelop die benötigten Prozeduren vom Typ „Bibliotheksprozedur (.hdpl)“ an und speichern Sie diese in derselben Bibliothek ab. Geben Sie für jede Prozedur die benötigten Eingabe- oder Ausgabeparameter (ikonisch und steuernd) sowie deren Parameterdokumentation (Semantik) an.

 

Vollständig definierte Prozedurschnittstellen inklusive Parameterdokumentation (Semantik) sind entscheidend.

Wichtig: Den Eingabe- und Ausgabeparametern der HALCON Prozeduren müssen die korrekten „Semantiktypen“ im Tab „Parameter Dokumentation“ zugewiesen werden!

Für das Bildverarbeitungsbeispiel dieses TechTipps (example_code2d.hdpl) legen Sie folgende Parameter für die Prozeduren an:

Prozedur Parameter Typ Semantik
init codetype  Input: Steuerparameter

string

(Wert: QR Code (Default), Data Matrix ECC 200

codemodel  Output: Steuerparameter datacode_2d
process


image  Input: Ikonischer Parameter image
searcharea  Input: Ikonischer Parameter region
codemodel  Input: Steuerparameter datacode_2d
contour  Output: Ikonischer Parameter xld
cutout  Output: Ikonischer Parameter image
content  Output: Steuerparameter string
finalize codemodel  Input: Steuerparameter datacode_2d
train


image  Input: Ikonischer Parameter image
firstarea  Input: Ikonischer Parameter image
codemodel  Input: Steuerparameter datacode_2d
content  Output: Steuerparameter string
sizemin  Output: Steuerparameter integer
sizemax  Output: Steuerparameter integer

Parametersemantik

Die Semantik der HALCON Parameter ist besonders wichtig. Damit definieren Sie, welche Parametertypen der Dynamic Vision App an die einzelnen HALCON Prozeduren übergeben bzw. abgefragt werden. Anhand der Semantik eines HALCON Parameter erzeugt die Vision App dynamisch einen passenden Interaktionsparameter für die REST-Schnittstelle. Im Beispiel werden folgende Interaktionsparameter erzeugt:

HALCON
Prozedurparameter

IDS NXT
Interaktionsparameter

codetype Combo Box Ctrl
image Bild
contour Bild mit Markierung
content Label
searcharea Einstellbare Region (Bildausschnitt)

 

Interaktionsparameter werden als graphische Elemente der Vision App angezeigt.
Interaktionsparameter werden als graphische Elemente der Vision App angezeigt.

Bildverarbeitung

Im Rahmen dieses Techtipps wird lediglich auf den Austausch zwischen der „Dynamic Vision App for HALCON“ und der HALCON Bibliothek mittels der Prozedurschnittstellen eingegangen.

In der „init“-Prozedur wird der Steuerparameter „codetype" zur Auswahl des Codetyps angelegt und ein 2D-Codemodell „codemodel“ erzeugt, das auch in anderen Prozeduren als Eingabeparameter verwendet wird. Des Weiteren wird eine Datei mit Trainingsdaten geladen bzw. angelegt, um ein detaillierteres Codemodell zu erzeugen.

init ( : : codetype : codemodel )

if (FileExistsTraining)
read_data_code_2d_model(TrainingFilePath, codemodel)
[...]
else
create_data_code_2d_model(codetype, [], [], codemodel)

In der „process“-Prozedur werden die Bilddaten zuerst mit Hilfe der vom Anwender eingestellten Region „searcharea“ reduziert. Danach sucht HALCON in dieser Region mittels des (trainierten) „codemodel“ nach 2D-Codes und übergibt die Ergebnisse im „content“ String und deren Bildposition als XLD im "contour“-Bild. Das „cutout“-Bild zeigt zudem den ausgeschnittenen Code an.

process ( image, searcharea : contour : codemodel : content )

find_data_code_2d (image, contour, codemodel, [], [], ResultHandles, content)
[...]
reduce_domain(image, Region, cutout)

Innerhalb der „train“-Prozedur wird das Codemodell weiter verbessert und die Trainingsdaten in einer Datei gespeichert.

train ( image, firstarea : : codemodel : content, sizemin, sizemax )

find_data_code_2d(ImageReduced, contour, codemodel, ['train'], ['all'], ResultHandles, content)
[...]
write_data_code_2d_model(codemodel, TrainingFilePath)

Die „finalize“-Prozedur bereinigt den Speicher, indem das „codemodel“ gelöscht wird.

finalize ( : : codemodel : )

clear_data_code_2d_model(codemodel)

HALCON Bibliothek hochladen

Jetzt können Sie die erstellte HALCON Bibliothek verwenden. Benutzen Sie den „Upload“-Button () der Dynamic Vision App, um die zuvor erstellte HALCON Bibliothek hochzuladen. Eine Meldung informiert Sie, wenn die Bibliothek erfolgreich geladen wurde. In diesem Fall stellt die Dynamic Vision App die Eingabe- und Ausgabeparameter der HALCON Bibliothek im IDS NXT Cockpit dar. Die Bildverarbeitung ist sofort verwendbar.

Die HALCON Bibliothek bleibt auch über den nächsten Neustart permanent im Speicher, bis sie über den „Löschen“-Button () vom System entfernt bzw. durch den Upload einer anderen Bibliothek überschrieben wird. Es kann immer nur eine Bibliothek geladen und aktiv sein. Sie können die Bildverarbeitung aber beliebig oft verändern.

Hinweise

Performance

Die Kombination aus der generischen Vision App und einer HALCON Bibliothek ist nicht optimiert auf Geschwindigkeit und kann daher nicht mit der Programmierung einer speziell implementierten C++ Vision App verglichen werden. Das Techtipp Beispiel  example_code2d.hdpl erreicht etwa 70 % der Geschwindigkeit der spezialisierten Matrixcode-Leser Vision App. Die „Dynamic Vision App for HALCON“ bietet hingegen den Vorteil, HALCON Bildverarbeitung sehr schnell und einfach auf einer Vision App-basierten Kamera zu testen, ohne dafür eine Zeile C++ Sourcecode zu schreiben und für die Kamera-Plattform aufwendig cross-kompilieren zu müssen.

Exception Handling

Tritt während der Ausführung einer HALCON Prozedur eine unbehandelte Ausnahme (unhandled exception) auf, startet die Vision App neu und entlädt dabei die HALCON Bibliothek. Um ein Abstürzen zu vermeiden, stellen Sie innerhalb der HALCON Prozeduren sicher, dass jeder auftretende Fehler behandelt wird (Exception Handling mittels try...catch).

Tipps

Neustart vermeiden

Wenn es während der Entwicklung der HALCON Bildverarbeitungsbibliothek zu Abstürzen der Vision App kommt, wäre es sinnvoll, dass diese nicht immer wieder automatisch neu startet. Mit einem REST-Befehl können Sie dies verhindern. Danach entscheiden Sie manuell, wann die App starten soll.

curl -u <user credentials> -X PUT /vapps/activated/dynamic_vision_app_for_halcon?temporary=true <device URL>

Dieser REST-Befehl ist nur einmalig für die aktuelle Ausführung der Vision App gültig!

Log anzeigen

Um ein detailliertes Log der „Dynamic Vision App for HALCON“ anzuzeigen, um z.B. einem Fehlverhalten der Vision App bzw. der Bildverarbeitung auf die Spur zu kommen, rufen Sie im Browser folgende URL auf:

http://<Geräte IP>/vapps/dynamic_vision_app_for_halcon/log

Der Logauszug zeigt einen fehlerfreien Ablauf beim Laden einer HALCON Bibliothek.
Der Logauszug zeigt einen fehlerfreien Ablauf beim Laden einer HALCON Bibliothek.

Die „Dynamic Vision App for HALCON“ analysiert die in der Bibliothek definierten Prozedurparameter und erstellt die benötigten Vision App-Interaktionselemente (siehe gelbe Markierungen), wie z.B. Configurables, Inputs und Results. Fehler in der Ausführung der HALCON Bildverarbeitung lassen sich mit diesem Log  der Anwendung einfacher identifizieren und beheben.

Durch die Verwendung der Standard-Output Datei können auch aus HALCON Meldungen in dieses Log integriert werden.

open_file('standard', 'output', stdout)
result := 'NIO'
fwrite_string (stdout, result + '\n')

Fazit

Die „Dynamic Vision App for HALCON“ bietet eine schnellen, unkomplizierten Weg, um HALCON-basierte Bildverarbeitung auf einer Vision App-basierten Kamera, wie dem IDS NXT vegas auszuführen. Dies spart Ihnen die zeitaufwendige C++ Programmierung einer eigenen Vision App, wodurch Sie sich auf die Erstellung der HALCON Routinen konzentrieren können. Durch den einfachen Upload-Mechanismus können Sie die Aufgabe der IDS NXT Vision App-basierten Kamera beliebig oft zur Laufzeit ändern. Dazu benötigen Sie weder Kenntnisse in C++ bzw. in der Vision App Programmierung. Embedded Bildverarbeitung „it's so easy“.

Wenn Sie mehr über das IDS NXT Vision App Konzept und dessen Verwendung erfahren wollen, lesen Sie das Handbuch zur Entwicklung von IDS NXT Vision Apps und schauen Sie sich die IDS NXT VideoTutorials an. Den Einstieg in die einfache und intuitive Programmierung Ihrer eigenen HALCON Machine-Vision-Anwendung finden Sie auf den HALCON Produktseiten von MVTec.

Weitere TechTipps und Applikationsberichte finden Sie auf der IDS-Webseite. Dort finden Sie auch mehr Informationen über die neuartigen Vision App-basierten Industriekameras der IDS NXT Familie.