Halcon Schulung

Schulungsunterlagen: Halcon C-Interface
Florian Raisch
Florian.Raisch@de.bosch.com
Inhaltsverzeichnis
1 Überblick 1
2 Paketstruktur 3
3 def-Datei 5
3.1 Operator-Beschreibung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.1 Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.2 Short . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3.1.3 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.4 Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.5 Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1.6 Predecessor, successor, alternatives . . . . . . . . . . . . . . . . . . 8
3.1.7 Attention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.1.8 Result state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.2 Parameterbeschreibung . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2.1 Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2.2 Default type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2.3 Sem type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2.4 Multivalue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2.5 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2.6 Default value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4 hcomp 14
4.1 C-Schnittstellen Dateien . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2 C++-Schnittstellen Dateien . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3 Dokumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3.1 Dokumentation für die Skriptsprache in hdevelop . . . . . . . . . . 15
4.3.2 Dokumentation für die Programmiersprache C . . . . . . . . . . . . 16
4.3.3 Dokumentation für die Programmiersprache C++ . . . . . . . . . . 16
4.4 Dateien für Onlinezufriff der Dokumentation . . . . . . . . . . . . . . . . . 16
i
INHALTSVERZEICHNIS INHALTSVERZEICHNIS
5 DLL 17
5.1 Die Supply-Funktion: CIPUserMeanImage . . . . . . . . . . . . . . . . . . 17
5.1.1 Übernahme der Eingabeparameter . . . . . . . . . . . . . . . . . . 18
5.1.1.1 nichtikonische Parameter . . . . . . . . . . . . . . . . . . 18
5.1.1.2 ikonische Parameter . . . . . . . . . . . . . . . . . . . . . 19
5.1.2 Übergabe der Ausgabeparameter . . . . . . . . . . . . . . . . . . . 22
5.1.2.1 nichtikonische Parameter . . . . . . . . . . . . . . . . . . 23
5.1.2.2 ikonische Ausgabeparameter . . . . . . . . . . . . . . . . . 23
5.1.3 Hilfsmacros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.2 Die Aktion-Funktion: IPUserMeanImage . . . . . . . . . . . . . . . . . . . 26
5.3 Visual C++ - Projekt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.3.1 Projekterstellung . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.3.2 Projekteinstellungen . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6 Sytemeinstellungen 32
A 34
A.1 Datentyen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
ii
Kapitel 1
Überblick
Dieses Kapitel soll einen kurzen Überblick über die Komponenten eines halcon-Erweiterungs-
Paketes (DLL) und der Schnittstelle C-Interface zum Einbinden eines Erweiterungs-Paketes
geben. Diese Schnittstelle schreibt die Struktur und die Bestandteile des Erweiterungs-
Paketes vor. Ein Erweiterungs-Paket hat folgende Bestandteile:
• Ein Verzeichnis des Erweiterungs-Paketes mit vorgeschriebener Unterstruktur (siehe

Kap. 2).
• Eine Def-Datei, die die Dokumentation des Erweiterungspaketes in einer skript-

ähnlichen Sprache beschreibt (siehe Kap. 3).
• Eine DLL, die die neuen Operatoren enthält (in C geschrieben; siehe Kap. 5).
• Zwei DLLs, die die Schnittstellen zu C oder C++ darstellen (siehe Kap. 5).
• Mehrere Dateien, die die Dokumentation des Erweiterungs-Paketes beinhalten und

den Onlinezugriff auf diese regeln (siehe Kap. 4).
In dieser Schulung werden wir ein Erweiterungs-Paket mit einem Mittelwert-Filter als Ope-
rator erstellen. Der Name des Paketes soll usermean“ sein. Die Schnittstellen C-Interface
”
schreibt uns dann vor, daß folgende Bestandteile des Erweiterungs-Paketes die folgenden
Namen erhalten:
• Das Unterverzeichnis des Paketes muß denselben Namen besitzen wie das Paket selbst
(hier also: usermean).
• Die DLL, die die neuen Operatoren enthält, muß ebenfalls den Namen des Paketes
annehmen (hier also: usermean.dll).
• Die zwei DLLs, die die Schnittstellen zu C und C++ darstellen, haben in diesem
Fall die Namen usermeanc.dll und usermeancpp.dll . I.a. werden die Namen der
Schnittstellen-DLLs durch den Namen des Paketes + Namen der Schnittstelle zu-
sammengestellt.
1
KAPITEL 1. ÜBERBLICK
Ein Halcon-Operator besteht immer aus zwei Funktionen (siehe Kap. 5):
• Supply-Funktion
• Action-Funktion
Die Supply-Funktion hat die Aufgabe, die übergebenen Parameter auf ihre Wertigkeit und
Gültigkeit zu überprüfen und Parameter, die als Felder vorliegen, in ihre einzelnen Kom-
ponenten zu zerlegen und einzeln an die Aktion-Funktion zu übergeben.
Die Aktion-Funktion führt die eigentliche Aufgabe, hier im speziellen die eigentliche Bild-
verarbeitungsaufgabe durch.
In Abbildung 1.1 ist das Datenflußdiagramm für Halcon-Operatoren abgebildet.
Application Programs
Input Output
HALCON
C or C++ Interface Database
Buffer Buffer
Control Iconic Control Iconic

Parameter Objects Parameter Objects
Supply Procedure
Action Procedure
Abbildung 1.1: Datenflußdiagramm der Halcon-Schnittstelle
2
Kapitel 2
Paketstruktur
Die Struktur des Erweiterungs-Paketes beschreibt die Struktur des Verzeichnisses, in dem
die einzelnen Bestandteile des Verzeichnisses stehen müssen. Das Verzeichnis hat folgende
Unterordner:
bin\i486-nt4: Dieses Verzeichnis enthält alle DLLs. Also die DLL PAKET.dll und die
beiden Schnittstellen-DLLs PAKETc.dll & PAKETcpp.dll .
def: In dem Unterverzeichnis def wird die def-Datei, die in Kap. 3 beschrieben ist, abge-
legt.
doc: Dieses Verzeichnis besitzt eine sehr verzweigte Unterstruktur. Die Struktur hängt
davon ab, welche Dokumentationen man sich mit Hilfe des Intepreters hcomp (siehe
Kap. 4) erstellen läßt. Hier wird nur die Notwendige Struktur für die HTML-Files
angegeben:
html\reference: Hier unterteilt sich das Verzeichnis in die Dokumentationen der
einzelnen Programmiersprachen.
hdevelop: Dokumetation in hdevelop-Syntax.
c: Dokumentation in C-Syntax (low-level).
cpp: Dokumentation in C++-Syntax (high-level).
help: Dieses Verzeichnis enthält Dateien die nötig sind, um einen Online-Zugriff auf die
Dokumentation von hdevelop aus zu haben. Diese Dateien werden mit Hilfe des
Interpreters hcomp (siehe Kap. 4) und dem Parameter -M erzeugt und müssen in
diesem Unterverzeichnis stationiert werden.
include: Hier stehen die Header-Dateien der beiden Schnittstellen-DLLs.
lib\i486-nt4: Hier stehen die statischen Bibliotheken, die zum Einbinden in den Quellcode
benötigt werden (PAKET.lib,PAKETc.lib und PAKETcpp.lib).
source: In diesem Verzeichnis stehen die einzelnen Source-Codes für die Halcon-Operatoren
und die Schnittstellen-DLLs.
3
KAPITEL 2. PAKETSTRUKTUR
PAKET
PAKETc
PAKETcpp
Diese Verzeichnisstruktur jedesmal von Hand anzulegen ist sehr mühsam. Jedoch sollte
man dies einmal getan haben, um sich zu verdeutlichen, welche Bestandteile eines Paketes
in welchem Verzeichnis stehen und um Fehler beim Interpretieren der def-Datei (siehe Kap.
3) mit hcomp (siehe Kap. 4) schneller zu entdecken.
Diese Verzeichnisstruktur kann man sich mit Hilfe der bat-Datei hdirectory.bat1 erstellen
lassen.
Einen Überblick über die Verzeichnisstruktur eines Erweiterungs-Paketes ist in Abbildung
2.1 am Beispiel des Paketes Pad zu sehen.
Abbildung 2.1: Verzeichnisstruktur eines Erweiterungs-Paketes
1
Datei ist nicht im Lieferumfang von halcon, sondern auf der Schulungsdiskette enthalten
4
Kapitel 3
def-Datei
Die def-Datei ist diejenige Datei, in der alle Informationen zur Beschreibung eines Ope-
rators (Erweiterungs-Paketes) stehen, die die Halcon-Schnittstelle benötigt (hdevelop, C,
C++). In diesem Kapitel werden alle notwendigen Informationen und deren Syntax anhand
des Beispieles für den Mittelwert-Filter-Operator erklärt. Alle möglichen Informationen zur
Beschreibung eines Operators, die man der Halcon-Schnittstelle übergeben kann, sind in
[C-Interface] beschrieben.
3.1 Operator-Beschreibung
Die Operator-Beschreibung innerhalb einer def-Datei muß sich an die folgenden Restrik-
tionen halten:
• Alle Operator-Beschreibungen beginnen mit einem Header (siehe Abschnitt 3.1.1).
• Alle folgenden Informationen sind in ihrer Reihenfolge keiner Regel unterstellt.
• Jede Information zur Beschreibung eines Operators endet mit einem Semikolon ;“.
”
3.1.1 Header
Der Header1 , der am Anfang jeder Operator-Beschreibung steht, hat folgende Syntax:
operator_name <-
InterneCFunktion[EingabeObjekte:AusgabeObjekte:
EingabeCtrlPara:AusgabeCtrlPara]
1
! Bitte beachten Sie, daß dies der einzige Befehl innerhalb der def-Datei ist, der nicht mit einem
Semikolon ;“ endet !
”
5
KAPITEL 3. DEF-DATEI 3.1. OPERATOR-BESCHREIBUNG
Als Beispiel für den Mean-Filter:
user_mean_image <-
CIPUserMeanImage[InputImage:MeanImage:Masksize:]
Hierbei ist auch zu beachten, daß die Parameterübergabe an die Funktion bestimmten
Regeln obliegt. Die Parameter sind in Halcon in 4 Kategorien unterteilt.
1. Eingabeobjekte: Alle ikonischen Parameter, also Parameter, die bildhaft darstellbar
sind und der Funktion als Eingabeparameter dienen. Also Bilder, Regionen & XLD-
Strukturen.
2. Ausgabeobjekte: Alle ikonischen Parameter, die der Schnittstelle von der Funktion
zurückgegeben werden.
3. Eingabekontrollparameter: Alle nichtikonischen Parameter, also Parameter, die nicht

bildhaft darstellbar sind und der Funktion von der Schnittstelle übergeben werden.
Das sind z.B. Strings, Integer und Floats.
4. Ausgabekontrollparameter: Alle nichtikonischen Parameter, die der Schnitstelle zu-

rückgegeben werden.
Diese Parameter müssen der Funktion in der oben aufgeführten Reihenfolge der Katego-
rien übergeben werden. Die einzelnen Kategorien werden mit Doppelpunkt :“ getrennt.
”
Werden mehrere Parameter einer Kategorie übergeben, werden diese Parameter mit Kom-
mata ,“ getrennt. Hat eine Kategorie keinen Parameter, so bleibt diese Kategorie leer,
”
wird jedoch mit Doppelpunkt :“ von den anderen Kategorien getrennt.
”
3.1.2 Short
Das Schlüsselwort short dient zur Kurzbeschreibung des Operators. Dem Schlüsselwort
short folgt die Angabe einer Sprache in der die Kurzbeschreibung folgt (z.B. english,
german).
Beispiel:
short.english
Smoothing of InputImage by using average value.;
short.german
Gl\"{a}ttung des Bildes durch Mittelwertbildung.;
Zu beachten ist, daß man beide Varianten (englisch & deutsch) verwenden kann, aber nicht
muß. Wobei es sinnvoll ist immer eine englische Version bereitzustellen. Dies gilt für alle
Schlüsselwörter, die ausschließlich Textinformation über den Operator enthalten.
Die Formatierung der Textinformation solcher Schlüsselwörter kann LATEX-Kommandos
[Gooosens94] einschließlich deren Syntax unterliegen.
6
3.1.3 Abstract
Das Schlüsselwort abstract ist ebenfalls ein Schlüsselwort, das ausschließlich Textinforma-
tion über den Operator enthält. Die Information, die dem Schlüsselwort abstract folgt,
kann ebenfalls in mehreren Sprachen erfolgen und dient der genauen Beschreibung des
Operators.
Beispiel:
abstract.german
\OpRef{user_mean_image} f\"{u}hrt eine lineare Gl\"{a}ttung aller
Eingabebilder (\ParRef{InputImage}) durch. Die Filtermatrix
der Gr\"{o}{\ss}e \ParRef{Masksize} X \ParRef{Masksize} besteht aus
Einsen. Das Ergebnis der Faltung wird durch \ParRef{Masksize}
X \ParRef{Masksize} dividiert. Die Randbehandlung wird durch
Fortsetzung der Grauwerte an den R\"{a}ndern realisiert.;
abstract.english
\OpRef{user_mean_image} smoothes all input images (\ParRef{
InputImage}). Each element of the filter-mask with the masksize
\ParRef{Masksize} X \ParRef{MaskSize} contains the value 1.
The result of the convolution is divided by the masksize
\ParRef{Masksize} X \ParRef{Masksize}. For margin control the
gray-values are extended at the image-edges.;
3.1.4 Module
Dieses Schlüsselwort gibt an, welchem halcon-Modul der Operator zugeordnet wird. Für
Erweiterungspakete ist jedoch vorgeschrieben, diese dem Modul basic zuzuordnen.
Beispiel:
module
basic;
3.1.5 Chapter
Die Funktion des Schlüsselwortes chapter ist die Strukturierung der halcon-Operatoren
beizubehalten. Alle halcon-Operatoren sind in einer hierarchischen Struktur mit Kapiteln
und Abschnitten unterteilt (z.B.: read image ist im Kapitel File Abschnitt images zu
finden). Diese Struktur soll bei Erweiterungs-Paketen beibehalten werden. Die Struktur
ist in den Hilfe-Manuals zu finden und im Menüpunkt Operators im Programm hdevelop.
Man unterliegt bei der Einteilung des Operators in ein Kapitel und einen Abschnitt keinen
7
Restriktionen. So kann man sowohl neue Kapitel und Abschnitte eröffnen, als auch neue
Operatoren in vorhandene Kapitel und Abschnitte eintragen. Jedoch muß jeder Abschnitt
bzw. Operator im Kapitel bzw. Abschnitt in der Namensgebung eindeutig sein. Außerdem
dürfen Namen von Kapiteln bzw. Abschnitten keine Leerzeichen beinhalten. Will man den
Namen eines Kapitels oder eines Abschnitts aus zusammengesetzten Wörter bilden, sollte
man einen Bindestrich (-) benutzen.
Beispiel:
chapter.english
Filter,UserSmoothing;
Der Operator user mean image wird also in das Kapitel Filter im Abschnitt UserS-
moothing eingetragen (siehe Abb. 3.1).
Abbildung 3.1: Ausschnitt aus hdevelop: Im Menüpunkt

operator→Filter→UserSmoothing→user mean image ist der Operator zu finden.
3.1.6 Predecessor, successor, alternatives

Diese 3 Schlüsselwörter dienen dazu Anwendern den Zusammenhang zu erläutern, indem
der Operator üblicherweise verwendet wird. So werden mit diesen Schlüsselwörtern mög-
liche Vorgänger-, Nachfolger- oder ähnliche Operatoren definiert. Diese Operatoren kann
man in hdevelop im Menü Suggestions abfragen (siehe Abb. 3.2), bzw. in der Hilfe-Datei
zu diesem Operator werden diese Vorschläge ebenfalls aufgeführt.
8
Abbildung 3.2: Ausschnitt aus hdevelop: Im Menüpunkt Suggestions→Successor werden

mögliche Nachfolger zum ausgewählten Operator angezeigt.
Beispiel:
successor
dyn_threshold, regiongrowing;
alternatives
smooth_image, gauss_image;
3.1.7 Attention
Mit attention wird auf mögliche Fehlerquellen und Beschränkungen des Operators hinge-
wiesen.
Beispiel:
attention.english
If an even-value instead of an odd-value is given for
\ParRef{Masksize}, the next larger odd one is used
instead (This way the center of the mask is always determined
exactly).;
attention.german
Falls statt einem ungeraden Wert ein gerader Wert f\"{u}r den
Parameter \ParRef{Masksize} angegeben wurde, wird der
n\"{a}chstgr\"{o}{\ss}ere ungerade Wert genommen (Somit ist jederzeit der
Schwerpunkt der Filtermaske eindeutig bestimmt).;
3.1.8 Result state

Das Schlüsselwort result state beschreibt den Rückgabewert des Operators und mögli-
cherweise auftretende Exception-Handlings.
9
KAPITEL 3. DEF-DATEI 3.2. PARAMETERBESCHREIBUNG
Beispiel:
result_state.english
\OpRef{user_mean_image} returns TRUE if all parameters are
correct\; otherwise a exception is raised.;
result_state.german
\OpRef{user_mean_image} liefert den Wert TRUE zur\"{u}ck, wenn
alle Parameter korrekt \"{u}bergeben wurden\; sonst wird eine
Ausnahmebehandlung durchgef\"{u}hrt.;
3.2 Parameterbeschreibung
Nachdem der Operator mit den unter Abschnitt 3.1 erläuterten Schlüsselwörter beschrie-
ben wurde, werden die im header (siehe Abschn. 3.1.1) angegebenen Parameter näher
spezifiziert.
Für unser Beispiel sieht das folgendermaßen aus:
parameter
InputImage: input_object;
description.english: Image to be smoothed.;
description.german: Zu gl\"{a}ttendes Bild.;
sem_type: image;
type_list: byte;
multivalue: optional;
parameter
MeanImage: output_object;
description.english: Smoothed Image.;
description.german: Gegl\"{a}ttetes Bild.;
sem_type: image;
parameter
Masksize: input_control;
description.english: Size of filter-mask;
description.german: Gr\"{o}{\ss}e der Filtermaske;
sem_type: integer;
10
type_list: integer;
default_type: integer;
default_value: 5;
value_list: 3,5,7,9,11,13,15,17,19;
assertion: Masksize > 2 && Masksize < 20;
Jede Beschreibung eines Parameters beginnt mit dem Schlüsselwort parameter, dem wei-
tere Schlüsselwörter folgen. All diesen Schlüsselwörtern folgt ein Doppelpunkt :“ und
”
ein Wert, der mit einem Semikolon ;“ abgeschlossen wird. All diese Werte sind online
”
innerhalb des halcon-Systems mit dem Befehl get param info abrufbar.
Das Minimum, das an Information bereitgestellt werden muß, ist der Name (name) des Pa-
rameters, dessen Standardtyp (default type), dessen semantischer Typ (sem type) und die
Anzahl der Parameter (multivalue). In den nächsten Abschnitten werden die am häufig-
sten benutzten Schlüsselwörter zur Beschreibung von Parametern näher beschrieben. Alle
Schlüsselwörter sind in [C-Interface] beschrieben.
3.2.1 Name
parameter
Name: input_object, output_object, input_control,
output_control;
Der Name des Parameters steht immer am Anfang der Beschreibung eines Parameters
und folgt dem Schlüsselwort parameter unmittelbar. Den Wert, den der Name annimmt,
beschreibt die Kategorie des Parameters (siehe Abschn. 3.1.1). Die Reihenfolge in der die
Parameter beschrieben werden, muß mit der der Aufführung der Parameter im header
(siehe Absch. 3.1.1) übereinstimmen.
3.2.2 Default type

Dieses Schlüsselwort wird nur im Zusammenhang mit Kontrollparmetern benützt. Der
default type gibt an, was für eine Art von Variable im Normalfall für diesen Parameter
angenommen wird. Der default type muß genau einen der folgenden Werte annehmen.
default_type: integer, real, string;
3.2.3 Sem type

Dieses Schlüsselwort beschreibt die Art des Parameters genauer als in Abschn. 3.2.1, wo die
Parameter nur in ikonische und nichtikonische Eingangs- / Ausgangsparameter klassifiziert
werden. sem type beschreibt die genaue Klasse eines Parameters. Dies wird nötig, wenn
11
man in einer objektorientierten Sprache wie C++ die Halcon-Operatoren einbindet. Einige
Parameter müssen noch genauer beschrieben werden, da sie keine Instanz einer Klasse
”
darstellen, sondern eine Member-Variable dieser Klasse“. Dies geschieht mit dem unten zu
sehenden Ausdruck .spec.
sem_type: class[.spec];
Ein Teil der Klassen, die unter Halcon zur Verfügung stehen, sind unten aufgeführt (restl.
Klassen sind in [C-Interface] zu finden):
• ikonische Daten (Objektparameter):
– object (jedes ikonisches Objekt: images, regions, XLDs)

– image
– region
– xld (jede Art von XLD (eXtended Line Description))
– xld cont, xld poly, xld para, xld mod para, xld ext para
• elementare Daten (Kontrollparameter):
– number (alle Kontrollparameter)

– integer
– real
– string
– grayval
– channel (Bildkanalnummer)
• Handles (Kontrollparameter):
– framegrabber
– file
• Felder (Kontrollparameter):
– histogram.values
– distribution.values
• geometrische Daten (Kontrollparameter):
– point.x, point.y
– circle.center.y, circle.center.x, circle.center.radius
– line.begin.y, line.begin.x, line.end.y, line.end.x
12
3.2.4 Multivalue
multivalue gibt an, ob der Parameter als Array übergeben werden muß (true) oder ob nur
ein einzelner Wert zulässig ist (false). Ist beides möglich, wird multivalue auf optional
gesetzt.
multivalue: true, false, optional;
Die folgenden Schlüsselwörter sind zur Beschreibung eines Parameters nicht mehr zwingend
notwendig, aber oft sehr hilfreich.
3.2.5 Description
Mit dem Schlüsselwort description.language wird eine kurze Beschreibung des Parame-
ters in der jeweiligen Sprache gegeben. Der beschreibende Text kann wie in Abschnitt 3.1
bei allen beschreibenden Schlüsselwörtern der LATEX-Sytax unterliegen (siehe [Gooosens94]).
description.english: LATEX/Ascii-Text;
3.2.6 Default value

default value wird nur bei Eingabekontrollparametern benützt und kann dem Anwender
sehr hilfreich sein, um geeignete Werte zu finden. Default Values für Strings werden nicht
mit Anführungszeichen angegeben (nicht:’AB’, sondern: AB). Die Ausnahme stellen der
leere String und Strings mit Sonderzeichen dar.
default_value: DefaultValue;
Alle weiteren Schlüsselwörter sind in [C-Interface] beschrieben. Diese Schlüsselwörter

werden jedoch nicht allzu häufig benutzt und deshalb hier nicht explizit aufgeführt.
13
Kapitel 4
hcomp
Der Interpreter hcomp der zum Lieferumfang des halcon-Paketes gehört, interpretiert
die in Kap.3 beschriebene def-Datei und erstellt einige Dateien, die die Schnittstelle eines
Paketes darstellen. Dazu muß man dem Interpreter verschiedene Parameter übergeben.
Diejenigen Parameter, die notwendig sind, um alle notwendigen Dateien der Schnittstelle
zu erstellen, werden in den nächsten Abschnitten erläutert.
Der Aufruf des Interpreters geschieht in der DOS-Konsole. Um den Interpreter von jedem
Verzeichnis aus aufrufen zu können, sollte man der Systemvariable PATH den Pfad des
Interpreters hinzufügen. Das Verzeichnis, in dem der Interpreter steht, ist:
• %HALCONROOT%\bin\i486-nt4
4.1 C-Schnittstellen Dateien

Um die Schnittstelle zur Sprache C“ bereit zu stellen, müssen zwei Dateien mit dem
”
Interpreter hcomp erstellt werden. Die Namen der Dateien lauten:
• HCPAKET.c
• HCPAKET.h
Dafür muß der Interpreter in folgender Weise aufgerufen werden:

hcomp -u -C -pPAKET Destination+Name der def-Datei
Die Dateien werden in folgendes Unterverzeichnis des Paketverzeichnisses kopiert (siehe
Kap. 2):
• \source\PAKETc
Beide Dateien werden in die C-Schnittstellen-DLL eingebunden (siehe Abschn. 5.3.1).
14
KAPITEL 4. HCOMP 4.2. C++-SCHNITTSTELLEN DATEIEN
4.2 C++-Schnittstellen Dateien

Die 3 Dateien der C++-Schnittstelle werden ebenfalls mit Hilfe des Interpreters hcomp
erstellt. Die Namen der Dateien lauten:
• HCPPPAKET.cpp
• HCPPPAKET Global.cpp
• HCPPPAKET.h
hcomp -u -D -pPAKET Destination+Name der def-Datei
Diese Dateien, die nach obigem Interpreteraufruf enstehen, müssen in folgendes Unterver-
zeichnis kopiert werden:
• \source\PAKETcpp
Diese Dateien werden in die CPP-Schnittstellen-DLL eingebunden (siehe Abschn. 5.3.1).
4.3 Dokumentation
Es ist grundsätzlich möglich die Dokumentation eines Operators als Postscript, PDF-
Dokument oder HTML-Seite zu erstellen. Der Onlinezugriff auf die Dokumentation des
Operators unter hdevelop geschieht jedoch immer auf die HTML-Seite. Das Erstellen die-
ses Dokumentes ist also zwingend notwendig. Das Erstellen der anderen Dokumente hat
sich nach den Erfahrungen des Autors in der Praxis nicht als notwendig herausgestellt. Aus
diesem Grund wird an dieser Stelle nur der Interpreteraufruf gezeigt, der die HTML-Seite
erstellt. Die Parametereinstellungen für die anderen Interpreteraufrufe sind in [C-Interface]
nachzulesen.
Da der Operator nicht nur in einer Programmiersprache aufgerufen werden kann und die
Dokumentation nicht nur in einer Sprache verfaßt wurde, müssen mehrere Dokumentatio-
nen erstellt werden.
4.3.1 Dokumentation für die Skriptsprache in hdevelop

Um die Dokumentation für die Skriptsprache hdevelop zu erstellen muß der Interpreter
hcomp folgendermaßen aufgerufen werden:
hcomp -Ltrias:all -llanguage Destination+Name der def-Datei
(language: german, english)
Die enstandenen Dateien müssen in das Paketunterverzeichnis (siehe Kap. 2)
• \doc\html\reference\hdevelop
15
KAPITEL 4. HCOMP
4.4. DATEIEN FÜR ONLINEZUFRIFF DER DOKUMENTATION
kopiert werden.
Achtung: Entscheidet man sich die Dokumentation in mehreren Sprachen zu verfassen,
sollte man die Dokumentation der gewünschten Sprache in obiges Verzeichnis kopieren.
Für die Dokumentation in der anderen Sprache sollte man sich ein weiteres Paketunterver-
zeichnis anlegen. Z.B.:
• \doc english\html. . .
Dies gilt auch für die in den Abschnitten 4.3.2 und 4.3.3 erstellten Dokumentationen.
4.3.2 Dokumentation für die Programmiersprache C

Hier lautet der Interpreteraufruf
hcomp -Lc:all -llanguage Destination+Name der def-Datei
und die Dateien müssen in das Paketunterverzeichnis (siehe Kap. 2)
• \doc\html\reference\c
kopiert werden.
4.3.3 Dokumentation für die Programmiersprache C++

Hier lautet der Interpreteraufruf
hcomp -Lc++:all -llanguage Destination+Name der def-Datei
und die Dateien müssen in das Paketunterverzeichnis (siehe Kap. 2)
• \doc\html\reference\cpp
kopiert werden.
4.4 Dateien für Onlinezufriff der Dokumentation

Da man mit der Umgebung hdevelop und mit dem Operator get operator info Online-
Zugriff auf die Dokumentation eines Operators hat und dieser in hdevelop in einen Menü-
punkt eingebettet wird, braucht man Dateien die dieses ermöglichen. Diese Dateien werden
mit folgendem Interpreteraufruf erstellt:
hcomp -M -llanguage Destination+Name der def-Datei
(language: german, english)
Die Dateien müssen in folgendes Paketunterverzeichnis kopiert werden (siehe Kap. 2):
• \help
kopiert werden.
Wer diese ganze Prozedur einmal gemacht hat, weiß danach genau aus welchen Bestand-
teilen ein Erweiterungspaket besteht. Deshalb ist es auch nur einmal notwendig diese Pro-
zedur zu machen, da auf der Schulungsdiskette eine bat-Datei mit dem Namen hcompall
ist, die die oben erläuterten Schritte ausführt.
16
Kapitel 5
DLL
Auf der Schulungsdiskette finden Sie die DLL usermean.dll“ im Verzeichnis example\user-
”
mean\bin\i486-nt4. Der dazugehörige Workspace usermean.dsw“ liegt im Verzeichnis
”
example\usermean\source\usermean (Der Quelltext der DLL ist auch im Anhang zu
finden). Anhand dieses Beispieles wird in den folgenden Unterabschnitten das Erstellen
einer DLL erläutert. Hierzu werden einige von halcon bereitgestellte Macros verwendet.
Auf diese in diesem Beispiel verwendeten Macros und deren zugrunde liegenden Funktio-
nen wird hier näher eingegangen. Es gibt jedoch weitere Macros, deren Beschreibung in
[C-Interface] nachzulesen ist.
In der Datei usermean.c“ befinden sich 3 Funktionen. Die erste Funktion ExtendImage
”
ist eine Funktion die der Bildverarbeitung dient. Diese Funktion übernimmt die Randbe-
handlung des zu filternden Bildes. Die zwei wichtigen Funktionen der DLL sind die Funk-
tionen IPUserMeanImage und die Funktion CIPUserMeanImage. Diese zwei Funk-
tionen sind die in Kapitel 1 erwähnten Supply- & Aktion-Funktionen. Die Supply-Funktion
CIPUserMeanImage wird von der halcon-Schnittstelle aufgerufen und hat nur einen Pa-
rameter. Diese Funktion wird in Abschnitt 5.1 näher erläutert. Die Aktion-Funktion IPU-
serMeanImage wird von CIPUserMeanImage aufgerufen und übernimmt den ganzen
BV-Anteil der DLL. IPUserMeanImage wird in Abschnitt 5.2 genauer beschrieben 5.2.
5.1 Die Supply-Funktion: CIPUserMeanImage

Die Supply-Funktion hat die Aufgabe, die Eingabeparameter von der Schnittstelle zu ho-
len, sie auf Validität zu prüfen und an die Aktion-Funktion weiterzugeben. Außerdem
werden in der Supply-Funktion Ausgabe-Parameter in der halcon-Datenbank registriert
und Speicher für diese Parameter allokiert. Zusätzlich übergibt die Supply-Funktion die
Ausgabeparameter der halcon-Schnittstelle.
Die einzige Verbindung zwischen der Supply-Funktion und der Schnittstelle ist der Para-
meter der Supply-Funktion. Er wird der Supply-Funktion von der Schnittstelle übergeben
und mit ihm können alle nötigen Verbindungen zur Schnittstelle hergestellt werden.
17
KAPITEL 5. DLL 5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE
5.1.1 Übernahme der Eingabeparameter

Wie in Abschnitt 3.1.1 beschrieben, wird in halcon nicht nur zwischen Eingabe- und Aus-
gabeparametern unterschieden, sondern auch zwischen ikonischen und nicht ikonischen
Parametern. Diese Unterscheidung spiegelt sich in der Repräsentation der Daten in der
halcon-Datenbank wider. Als ersten Schritt behandeln wir in Abschnitt 5.1.1.1 den ein-
facheren Fall der Übernahme der nichtikonischen Eingabeparameter. In Abschnitt 5.1.1.2
wird der Fall der Übernahme ikonischer Parameter behandelt.
5.1.1.1 nichtikonische Parameter

Es gibt zwei Funktionen, die es erlauben nichtikonische Eingabeparameter von der Schnitt-
stelle zu übernehmen:
HGetCPar: Die Funktion HGetCPar hat folgende Parameter:
HGetCPar(Hproc_handle proc_handle,
INT par_num,
INT type,
Hcpar *val,
INT4_8 min,max,
INT4_8 *num)
Die Parameter haben folgende Bedeutungen:
proc handle ist der einzige Parameter, der der Supply-Funktion von halcon überge-
ben wird und beschreibt den Prozeß, dem die Funktion angehört näher. Dieser
Parameter ist nur zum lesen geeignet, da über diesen Parameter die Schnittstelle
mit der Funktion kommuniziert!
par num besagt, welcher der nichtikonischen Eingabeparameter ausgelesen werden
soll ([1 . . . N ]).
type Mit jedem Wert wird der Typ in der Struktur Hcpar (siehe Abb. A.6) abge-
speichert. Diesen Typ (LONG PAR, FLOAT PAR, STRING PAR) muß man
explizit angeben. Man kann jedoch auch Typkombinationen angeben.
*val Ist der Ausgabeparameter der Funktion und gibt einen Zeiger auf die Struktur
Hcpar (siehe Abb. A.6) zurück. Für val muß genügend Speicher allokiert wer-
den. In dieser Struktur stehen die eigentlichen Werte des Eingabeparameters.
min,max Mit min,max gibt man die Anzahl der minimal und maximal erwarteten
Werte an. max darf nicht größer als die Anzahl der allokierten Elemente für
val sein.
18
*num gibt die Anzahl der ausgegebenen Elemente an.

HGetSPar: Die Funktion HGetSpar liefert im Gegensatz zu HGetCPar nur eine festge-
legte Anzahl von Elementen eines Parameters. Die Funktion hat folgende Parameter:
HGetSPar(Hproc_handle proc_handle,
INT par_num,
INT type,
Hcpar *val,
INT4_8 num)
Die Bedeutung der Parameter ist dieselbe wie bei HGetCpar, nur, daß man hier die
Anzahl der ausgegebenen Parameter nicht als Ausgabeparameter geliefert bekommt,
sondern diese mit Hilfe des Parameters num vorher festlegt.
5.1.1.2 ikonische Parameter

Die Übernahme ikonischer Eingabeparameter von der halcon-Schnittstelle erweist sich als
nicht so einfach wie die der nichtikonischen Eingabeparameter; da man unter ikonischen
Objekten Bilder, Regionen, XLDs usw. versteht. Daher werden hier nur die am häufigsten
gebrauchten Funktionen vorgestellt (die restlichen Funktionen sind in [C-Interface] nach-
zuschlagen). Bevor jedoch die einzelnen Funktionen für den Zugriff auf Eingabeparameter
7.1. BASIC ACCESS
beschrieben TO ICONIC
werden, muß INPUT OBJECTS
das grundsätzliche 61
Prinzip der halcon-Datenbank erklärt werden.
operator call
1st input object parameter 2nd input object parameter
1st input object parameter

parameter number
1st object Hkey
of 1st input object parameter HGetObj obj_key
HGetComp Hkey comp_key
region channel1 channel2
HGetImage Himage
image
HGetRL Hrlregion
region
Abbildung
Figure 5.1: Aufbau
7.2: Direct der
access to halcon-Datenbank
input image objects.
INT2 inp_pars; 19
INT4 num_objs;
Hkey key;
In der halcon-Datenbank werden alle ikonischen Objekte abgelegt. Wie in Abb. 5.1 zu
sehen, in folgender Weise. Jeder ikonische Eingabeparameter wird durch eine ID (obj key)
in der Datenbank dargestellt. Diese ID identifiziert einen Parameter in der Datenbank
eindeutig. Da ein Parameter aus mehr als einem Objekt bestehen kann, wird jedem die-
ser Objekte wiederum eine ID (comp key) zugewiesen. Diese jeweilige Komponente kann
wiederum nur aus einer Region oder aus einem Bild, das aus einer Region und mehreren
Kanälen zusammengestetzt wird, bestehen. Für diese Komponenten werden die dafür vor-
gesehenen Strukturen (Himage, Hrlregion) in der Datenbank abgelegt. Der Vorteil dieser
Art der Zuweisung von Parametern ist, daß man z.B. für Bilder, die dieselbe Grauwert-
matrix, aber eine andere Region besitzen, die Grauwertmatrix nicht zweimal ablegen muß,
sondern Ihnen nur andere IDs zuweisen kann, die auf dieselbe Grauwertmatrix verweisen.
Der Nachteil ist, daß man eine ziemlich umständliche Prozedur durchmachen muß, um auf
ein einfaches Bild zu zugreifen.
Man kann auf ein Bild und seine Region zugreifen, wenn man folgende Funktionen nach-
einander aufruft:
HGetObj: Mit HGetObj hat man Zugriff auf die ID eines bestimmten Eingabeparame-
ters.
HGetObj(Hproc_handle proc_handle,
INT par_num,
INT4 obj_num,
Hkey obj_key)
Die Bedeutung der einzelnen Parameter ist:
proc handle siehe 5.1.1.1

par num beschreibt den par num.ten ikonischen Eingabeparameter ([1 . . . N ]).
obj num beschreibt das obj num.te Objekt im par num.ten ikonischen Eingabepa-
rameter.
*obj key ist der Ausgabeparameter der Funktion und gibt die ID des Objektes an.
Mit dieser ID hat man nun Zugriff auf die gegeignete Komponenten-ID aus der Da-
tenbank.
20
HGetComp: Mit HGetComp hat man Zugriff auf die jeweilige Komponenten-ID, die dazu
berechtigt auf die eigentlichen Strukturen, wie Himage und Hrlregion (siehe Abb. A.1
& A.4), zu zugreifen.
HGetComp(Hproc_handle proc_handle,
Hkey obj_key,
INT comp,
Hkey *comp_key)
Dabei haben die einzelnen Parameter die folgenden Bedeutungen:
proc handle siehe 5.1.1.1.

obj key ist diejenige ID, die man mit HGetobj bekommen hat.
comp beschreibt die Komponente, auf die man zugreifen will. Die Werte sind hierbei
REGION, IMAGEINDEX= IMAGE1, IMAGE2,. . . . Die Konstanten IMAGEX
stehen dafür für die einzelnen Kanäle eines Bildes.
*comp key ist der Ausgabeparameter der Funktion und gibt die ID der Objekt-
Komponente an.
Als letzter Schritt wird nun die Funktion HGetImage, HGetRl oder HGetXLD auf-
gerufen, um auf die verschiedenen Strukturen Zugriff zu haben. Im weiteren wird
nur die Funktion HGetImage beschrieben. Die Beschreibung der anderen Funktionen
finden Sie in [C-Interface].
HGetImage: liefert einen Zeiger auf die Struktur Himage (siehe Abb. A.1)
HGetImage(Hproc_handle proc_id,
Hkey image_key,
Himage *image)
Der Parameter image key wurde mit durch die Funktion HGetComp gewonnen
und *image liefert einen Zeiger auf die Struktur Himage zurück, die ein Einzelbild
beschreibt. HGetImage liefert einen Zeiger direkt auf die Grauwertmatrix des Bildes
zurück, was voraussetzt, daß *image nur zum Lesen benutzt wird.
Nachdem nun die Grundfunktionen zur Datenacquisition von der Schnittstelle beschrieben
worden sind, werden jetzt die in der Supply-Funktion verwendeten Macros zur Datenacqui-
sition beschrieben. Diesen Macros liegen die oben beschriebenen Funktionen zu Grunde.
21
HAllObj: HAllObj(Hproc_handle proc_handle,

INT par_num,
Hkey &obj_key,
INT4_8 &index)
Dieses Makro ruft in einer Schleife sukzessive die Funktion HGetObj auf. Dabei
wird vor dem Eintritt in die Schleife abgefragt, wieviel Objekte der par num.ten Ein-
gabeparameter enthält. Je Schleifendurchgang wird die ID (*obj key) der einzelnen
Objekte des Eingabeparameters ausgegeben.
Das Macro übernimmt folgende Funktionen:
int i;
Hkey input_obj_key;
for(i=1;i<=Anzahl der Objekte des x.ten Parameters;i++) {
HGetObj(proc_handle,x,i,&input_obj_key);
}
HAllComp: HAllComp(Hproc_handle proc_handle,

Hkey obj_key,
Hkey &image_in_key,
Himage &image_in,
INT4_8 &index)
HAllComp ist ein Macro, das als Schleife über alle Kanäle eines Bildes realisiert ist.
In einem Durchlauf werden zwei Grundfunktionen aufgerufen. Als erstes wird HGet-
Comp aufgerufen, welche die Komponenten-ID zur Objekt-ID obj key zurückliefert.
Danach wird HGetImage aufgerufen, welche die Bildmatrix in image in zurücklie-
fert.
5.1.2 Übergabe der Ausgabeparameter

Wie bei den Eingabeparametern wird bei den Ausgabeparametern auch zwischen ikoni-
schen und nichtikonischen Parametern unterschieden. Auch hier erweist sich der Fall der
nichtikonischen Ausgabeparametern als der einfachere. Bei Ausgabeparametern muß zu-
sätzlich zur Übergabe des Parameters Speicher für den Parameter allokiert werden. Hierfür
gibt es eigene halcon-Macros (siehe [C-Interface]).
22
5.1.2.1 nichtikonische Parameter

Für die Übergabe nichtikonischer Ausgabeparameter gibt es nur eine Funktion:
HPutCPar: Bei der Übergabe von nichtikonischen Parametern muß man Speicher nur
allokieren, wenn ein Parameter als Element einen String enthält (HAllocStringMem:
siehe [C-Interface]). Ansonsten werden die Werte der Struktur Hcpar (siehe Abb.
A.6) in die halcon-Datenbank kopiert.
HPutCPar(Hproc_handle proc_handle,
INT par_num,
Hcpar *val,
INT4_8 num)
par num gibt an, um welchen Ausgabeparameter ([1 . . . N ]) es ich handelt; in *val
stehen die zu übergebenen Werte und num gibt an wieviele Werte mit dem par num.ten
Ausgabeparameter übergeben werden.
5.1.2.2 ikonische Ausgabeparameter

Um ikonische Ausgabeparameter an die Schnittstelle zu übergeben, muß man sich noch
einmal die Struktur der halcon-Datenbank (siehe Abb. 5.1) klarmachen. Regionen, Bilder
und XLDs werden durch Komponenten-IDs und diese wiederum durch Objekt-IDs identifi-
ziert. Deshalb müssen folgende Schritte zur Übergabe nichtikonischer Objekte durchgeführt
werden:
• speichern der berechneten Kanäle, Regionen und XLDs in der halcon-Datenbank über
IDs.
• Speicher allokieren für Regionen, Bilder und XLDs.
• Regionen und Kanäle zu Bildern verbinden.
• den berechneten Regionen, Bildern & XLDs ein Ausgabeobjekt einschließlich Kom-
ponente über IDs zuweisen.
Zuerst werden hierzu wieder die Grundfunktionen und dann einige Macros, die im Beispiel
verwendet wurden, erläutert. Die restlichen Funktionen und Macros sind in [C-Interface]
beschrieben.
HCrObj: erstellt ein neues Objekt (Region o. Bild) in der halcon-Datenbank. Dieses
Objekt enthält folgende Standardkomponenten:
• Eine leere Region als Area of Definition. Diese kann mit HPutDRL oder
HPutRect geändert werden.
23
• Leere Kanäle. Diese können mit HDefObj, HPutImage, oder HPutDImage

belegt werden.
HCrObj(Hproc_handle proc_handle,
INT par_num,
Hkey *obj_key)
Das neuangelegte Objekt wird dem par num.ten Ausgabeparameter zugewiesen und
erhält die Objekt-ID obj key.
HCopyObj: hat die dieselbe Wirkung wie HCrObj, jedoch wird das Objekt nicht als
leeres initialisert, sondern dem Objekt werden dieselbe Region und dieselben Kanäle
zugewiesen wie dem Objekt mit der ID input key. Dies ist insbesondere bei Filteran-
wendungen sinnvoll, wenn sich beim Ausgabeobjekt nur“ die Grauwerte der Kanäle
”
ändern.
HCopyObj(Hproc_handle proc_handle,
Hkey input_key,
INT par_num,
Hkey *output_key)
HNewImage: stellt Speicher für das neue Bild (den neuen Kanal) zur Verfügung.
HNewImage(Hproc_handle proc_handle,
Himage *output_image,
INT type,
INT width,height)
HNewImage allokiert Speicher für die Struktur Himage (siehe Abb. A.1) und die
Bildmatrix, deren Speicherbedarf über die Parameter width, height und type (siehe
Abb. A.2) bestimmt ist.
24
HPutImage: speichert den Bildkanal - bestimmt durch output image - in der halcon-
Datenbank und gibt die Komponenten-ID comp key zurück über die der Kanal einem
Objekt in der Datenbank zugewiesen werden kann.
HPutImage(Hproc_handle proc_handle,
Himage *output_image,
HBOOL copy,
Hkey *comp_key)
Der Parameter copy (TRUE o. FALSE) gibt an, ob image in die Datenbank kopiert
wird oder nur ein Zeiger darauf übergeben wird.
HDefObj: weist einer Komponente comp [1 . . . N ] mit der Komponenten-ID comp key
einem Objekt mit der ID obj key in der halcon-Datenbank zu.
HDefObj(Hrpoc_handle proc_handle,
Hkey obj_key
Hkey comp_key,
INT comp)
5.1.3 Hilfsmacros
Wie man im Beispielquelltext sieht, gibt es nicht nur halcon-spezifische Macros, die der
Parameterübergabe und Speicherallokierung dienen, sondern noch einige Macros, die un-
terstützende Wirkung bei der Fehlerbehandlung haben.
Die zwei verwendeten Macros werden hier kurz beschrieben, alle anderen sind in [C-Interface]
nachzulesen.
HCkNoObj: überprüft, ob alle ikonischen Eingabeparameter initialisierte Objkete ent-

halten. Falls dies nicht der Fall ist, wird die Supply-Funktion mit einem Fehler
beendet.
HCkP: überprüft den Rückgabewert einer Funktion bzw. eines Macros. Falls der Rück-
gabewert einen Fehlerzustand beschreibt, wird die Supply-Funktion mit der überge-
benen Fehlermeldung beendet.
25
KAPITEL 5. DLL 5.2. DIE AKTION-FUNKTION: IPUSERMEANIMAGE
5.2 Die Aktion-Funktion: IPUserMeanImage

In diesem Beispiel werden in der Aktion-Funktion (IPUserMeanImage) keine spezifi-
schen halcon-Funktionen verwendet. Deshalb wird im Skript nicht näher auf die Funktion
eingegangen.
5.3 Visual C++ - Projekt

Zum Erstellen der DLL muß ein Projekt Visual C++ Projekt angelegt werden. Die Vorge-
hensweise zum Anlegen eine Projektes und die Einstellungen des Projektes werden in den
nächsten beiden Abschnitten anhand von Screenshots beschrieben.
5.3.1 Projekterstellung
Die nachfolgenden Screenshots zeigen die Vorgehensweise zur Erstellung eines DLL-Projektes
für ein halcon Erweiterungspaket. Wählt man den Menüpunkt File→New öffnet sich fol-
gendes Fenster: Man wählt im Datenblatt Projekt“ den Punkt Win32 Dynamik-Link
” ”
Abbildung 5.2: Wizard zum Erstellen eines neuen Visual C++ Projektes
Library“ aus und trägt den Paketnamen (hier: usermean) als Projektnamen im Editfeld
Projektname“ ein. Als Pfad“ gibt man das Unterverzeichnis source des Pfades für das Er-
” ”
weiterungspaket an (siehe Kap. 2). Danach muß man den Dialog mit OK“ quittieren. Als
”
nächstes erscheint folgender Dialog der mit der Einstellung Ein leeres DLL-Projekt“ quit-
”
tiert wird. Nach diesem Schritt wird das leere Projekt erstellt. Diesem Projekt fügt man
jetzt die Quelldatei PAKET.c hinzu (hier:usermean.c). Diese Datei enthält die Supply- &
Aktion-Funktion.
Danach erstellt man zwei weitere Projekte im selben Pfad mit den Namen PAKETc und
PAKETcpp (hier: usermeanc und usermeancpp). Diesen Projekten fügt man die folgenden
Dateien hinzu, die bei der Interpretation mit dem Interpreter hcomp (siehe Absch. 4.1 &
4.2) erstellt wurden.
26
KAPITEL 5. DLL 5.3. VISUAL C++ - PROJEKT
Abbildung 5.3: Wizard zum Erstellen einer neuen Win32 Dynamik-Link Library“
”
• Dem Projekt PAKETc fügt man die Dateien HCPAKET.c und HCPAKET.h
hinzu (hier: HCusermean.c und HCusermean.h).
• Dem Projekt PAKETcpp werden die Dateien HCPPPAKET.cpp, HCPPPAKET -
Global.cpp und HCPPPAKET.h hinzugefügt (hier: HCPPusermean.cpp, HCP-
PusermeanGlobal.cpp, HCPPusermean.h).
Nach dem Erstellen der Projekte müssen noch einige Einstellungen gemacht werden. Diese
werden im nächsten Abschnitt beschrieben.
5.3.2 Projekteinstellungen
Zur besseren Übersicht sollte man die zwei Projekte PAKETc und PAKETcpp dem Pro-
jekt PAKET hinzufügen (siehe Abb. 5.4-5.5).
Abbildung 5.4: Hinzufügen eines Projek- Abbildung 5.5: Hinzufügen eines Projek-
tes zu einem Arbeitsbereich tes zu einem Arbeitsbereich
Sind beide Projekte hinzugefügt, erscheinen diese im Fenster

Arbeitsbereich“ (siehe Abb. 5.6). Da man zur Erstellung eines Erweiterungspaketes alle
”
27
Abbildung 5.6: Visualisierung der hinzugefügten Projekte im Arbeitsbereichsfenster
3 Projekte kompilieren muß, ist es hilfreich, geeignete Abhängigkeiten zwischen den Pro-
jekten zu definieren, so daß man nur noch ein Projekt kompilieren muß und die anderen
Projekte mit diesem kompiliert werden. Da die zwei Projekte PAKETc und PAKETcpp
vom Projekt PAKET abhängen, sollte dieses zuerst übersetzt werden. Die einzustellenden
Abhängigkeiten und das Erreichen des dazu gehörigen Dialoges ist in den Abb. 5.7-5.9
illustriert.
Abbildung 5.8: Abhängigkeit zwischen

Abbildung 5.7: Menüpunkt zum Errei- dem Projekt PAKETc und dem Projekt
chen des Abhängigkeiten-Dialog PAKET
Für jedes Projekt sind einige Einstellungen im Dialog Projekteinstellungen“, der über
”
den Menüpunkt Projekt→Einstellungen erreicht wird, zu erledigen. Die Einstellungen sind
wiederum in den Abb. 5.10-5.16 illustriert.
28
Abbildung 5.9: Abhängigkeit zwischen

dem Projekt PAKETcpp und dem Pro- Abbildung 5.10: Allgemeine Einstellun-
jekt PAKETc gen des Projektes PAKET
Abbildung 5.11: Debug-Einstellungen des Abbildung 5.12: Linker-Einstellungen des

Projektes PAKET Projektes PAKET
Abbildung 5.13: Allgemeine Einstellun- Abbildung 5.14: Linker-Einstellungen des

gen des Projektes PAKETc Projektes PAKETc
29
Abbildung 5.15: Allgemeine Einstellun- Abbildung 5.16: Linker-Einstellungen des

gen des Projektes PAKETcpp Projektes PAKETcpp
Als letzte Einstellungen der Projekte müssen dem Compiler noch die Verzeichnisse der
halcon-Bibliotheken und halcon-Header mitgeteilt werden (siehe Abb. 5.18 - 5.19). Der
Dialog zur Einstellung der Verzeichnisse ist im Menüpunkt Extras→Optionen zu finden
(siehe Abb. 5.17).
Abbildung 5.17: Menüpunkt Extras→Optionen zur Einstellung der Verzeichnisse
Abbildung 5.18: Einstellungen für Abbildung 5.19: Einstellungen für

Bibliothek-Verzeichnisse Include-Verzeichnisse
Nachdem alle Einstellungen gemacht sind, setzt man das Projekt PAKETcpp als aktives
Projekt (siehe Abb. 5.20) und übersetzt die Projekte. Als nächstes sind noch zwei Einstel-
30
lungen in der Sytemsteuerung zu machen, die in Kap. 6 beschrieben sind. Danach ist das
Erweiterungspaket unter hdevelop und als Element der Bibliothek halcon lauffähig.
Abbildung 5.20: Festlegen eines aktiven Projektes unter Visual C++
31
Kapitel 6
Sytemeinstellungen
Der letzte Schritt, um das Erweiterungspaket lauffähig zu machen, ist, halcon mitzuteilen,
daß es ein Erweiterungspaket gibt und wo es sich befindet.
Bei der Installation von halcon wurden 3 Umgebungsvariablen angelegt. Umgebungsvaria-
blen kann man unter NT in der Systemsteuerung unter dem Eintrag System betrachten
und ändern. Hierzu wählt man das Datenblatt Umgebung aus. Die 3 Variablen, die halcon
angelegt hat, heissen:
• HALCONROOT
• HALCONIMAGES
• HALCONEXTENSIONS
Abbildung 6.1: Systemvariable: HALCONEXTENSIONS
Um halcon mitzuteilen, daß ein Erweiterungspaket existiert, muß man die Variable HAL-
CONEXTENSIONS editieren. Dies kann man, indem man die Variable anklickt und
sie dann im Editierfeld Variable und ihr Inhalt im Editierfeld Wert erscheint (siehe Abb.
32
KAPITEL 6. SYTEMEINSTELLUNGEN
6.1). Hier muß nun das Verzeichnis des Erweiterungspaketes eingetragen werden. Existie-
ren mehrere Verzeichnisse werden diese mit Semikolon ;“ getrennt. Das letzte Element
”
der Liste darf jedoch nicht mit einem Semikolon enden. Sind alle Eintragungen gemacht,
wird die Variable über den Button Setzen gesetzt.
Als nächstes muß der Variablen PATH noch das Verzeichnis mitgeteilt werden, in dem
sich die DLLs befinden. Dieses Verzeichnis ist das Verzeichnis des Erweiterungspaketes +
\bin\i486-nt4 (in unserem Beispiel: ..\usermean\bin\i486-nt4). Auch diese Variable wird
mit dem Button Setzen gesetzt.
Danach wird der Dialog mit dem Button OK geschlossen und der User abgemeldet. Bei
erneutem Anmelden ist die Änderung der Variablen aktiv und der Operator müsste bei
einem Start von hdevelop aktiv sein.
33
Anhang A
A.1 Datentyen
50 CHAPTER 6. HALCON DATA TYPES
typedef union {
HBYTE *b; /* 0..255 (BYTE_IMAGE) */
HBYTE *z; /* 0..255 mod 256 (CYCLIC_IMAGE) */
HBYTE *d; /* orientation 0..180 (DIR_IMAGE) */
INT1 *i; /* -127..126 (INT1_IMAGE) */
INT4 *l; /* 4 byte integer (LONG_IMAGE) */
float *f; /* 4 byte real (FLOAT_IMAGE) */
HXYPixel xy; /* displacement vector field */
/* (XY_IMAGE) */
HComplexPixel c; /* complex image (COMPLEX_IMAGE) */
HLutPixel lut; /* byte with LUT (LUT_IMAGE) */
HInt2Pixel s; /* 2 bytes with sign (INT2_IMAGE) */
} HPixelImage;
typedef struct {
INT kind; /* pixel type */
HPixelImage pixel; /* pixel data */
INT width; /* image width */
INT height; /* image height */
/* time of creation of image */
UINT2 msec; /* milliseconds 0..999 */
UINT1 sec; /* seconds 0..59 */
UINT1 min; /* minutes 0.59 */
UINT1 hour; /* 0..23 */
UINT1 day; /* 1..31 */
UINT2 yday; /* 1..366 */
UINT1 mon; /* 1..12 */
UINT2 year; /* starting at 1900 */
} Himage;
Figure 6.1: Data type Himage for images.

Abbildung A.1: Datenstruktur: Himage
#define BYTE_IMAGE (INT)1 /* 1 byte per pixel (0..255) */
#define LONG_IMAGE (INT)2 /* 4 byte per pixel (INT4) */
#define FLOAT_IMAGE (INT)4 /* 4 byte per pixel (float) */
#define DIR_IMAGE (INT)8 /* edge orientation 0..180 */
#define CYCLIC_IMAGE (INT)16 /* 0..255 cyclic */
#define INT1_IMAGE (INT)32 /* -127..126 */
#define XY_IMAGE (INT)64 /* 2 byte images with sign */
#define COMPLEX_IMAGE (INT)128 /* 2 float-images */
#define LUT_IMAGE (INT)256 /* 34
(0..255) with color table */
#define INT2_IMAGE (INT)512 /* 2 bytes with sign */
Figure 6.2: Definitions of pixel types.

UINT1 min; /* minutes 0.59 */
UINT1 hour; /* 0..23 */
UINT1 day; /* 1..31 */
UINT2 yday; /* 1..366 */
UINT1 mon; /* 1..12 */
UINT2A.
ANHANG year; /* starting at 1900 */
A.1. DATENTYEN
} Himage;
Figure 6.1: Data type Himage for images.
#define BYTE_IMAGE (INT)1 /* 1 byte per pixel (0..255) */

#define LONG_IMAGE (INT)2 /* 4 byte per pixel (INT4) */
#define FLOAT_IMAGE (INT)4 /* 4 byte per pixel (float) */
#define DIR_IMAGE (INT)8 /* edge orientation 0..180 */
#define CYCLIC_IMAGE (INT)16 /* 0..255 cyclic */
#define INT1_IMAGE (INT)32 /* -127..126 */
#define XY_IMAGE (INT)64 /* 2 byte images with sign */
#define COMPLEX_IMAGE (INT)128 /* 2 float-images */
#define LUT_IMAGE (INT)256 /* (0..255) with color table */
#define INT2_IMAGE (INT)512 /* 2 bytes with sign */
Figure 6.2: Definitions of pixel types.

Abbildung A.2: Die verschiedenen Pixeltypen, die unter Himage (siehe Abb. A.1) möglich
sind
R = HRow(L,image.width);
6.2. REGION
C =DATA (HRLREGION)
HCol(L,image.width); 51
Please see section 5.2.2 for routines to allocate image data within Himage.
typedef struct {
float *re; /* real image part */
float *im; /* imaginary image part */
} HComplexPixel;
typedef struct {
INT2 *p; /* pixel */
INT1 num_bits; /* number of used bits */
} HInt2Pixel;
typedef struct {
INT1 *row; /* y-direction */
INT1 *col; /* x-direction */
} HXYPixel;
typedef struct {
HBYTE *b; /* 0..255 */
INT num_lut; /* length of color table */
HBYTE red[256];
HBYTE green[256];
HBYTE blue[256];
} HLutPixel;
Figure 6.3: Data types Himage.

Abbildung A.3: Die verschiedenen Bildtypen, diefor
unter Himage (siehe Abb. A.1) möglich
sind
6.2 Region Data (Hrlregion)
In HALCON region data is represented by a special

35 variant of the runlength encoding – a chord
encoding: For every line (chord) of a region its row index (“y coordinate”,“line number”) and
the column index (“x coordinate”) of its start and end point is stored. Both the start point and
ANHANG A. A.1. DATENTYEN
52 CHAPTER 6. HALCON DATA TYPES
typedef struct {
INT2 l; /* line number (row) of chord */
INT2 cb; /* column index of beginning of chord */
INT2 ce; /* column index of ending of chord */
} Hrun;
typedef struct {
HBOOL is_compl; /* region is complement */
INT4 num; /* number of chords */
INT4 num_max; /* maximal number of chords */
HRegFeature feature; /* already processed features */
Hrun rl[RL_LENGTH]; /* array of chords */
} Hrlregion;
Figure 6.4: Data type Hrlregion for region encoding.

Abbildung A.4: Datenstruktur: Hrlregion
typedef struct {
union {
HFeatureFlags single; /* a bitfield */
long all;
} def;
UINT1 shape; /* SHAPE_* */
HBOOL is_convex;
HBOOL is_filled;
HBOOL is_connected4;
HBOOL is_thin;
float circularity;
float compactness;
float contlength;
float convexity;
float phi;
float ra, rb; 36
float ra_, rb_;
float anisometry, bulkiness, structure_faktor;
HBOOL is_compl; /* region is complement */
INT4 num; /* number of chords */
56 INT4 num_max; /* maximal number of
CHAPTER chords
6. HALCON */
DATA TYPES
HRegFeature feature; /* already processed features */
Hrun rl[RL_LENGTH]; /* array of chords */
} Hrlregion;
ANHANG
typedefA.struct lin_seg_type { A.1. DATENTYEN
float row,col;
Figure 6.4: Data type/*Hrlregion
a control point of the polygon:
for region encoding. */
/* row (y) and column (x) coordinate */
float length; /* length of the line from the */
typedef struct {
/* current to the next point */
union {
float phi; /* orientation (rad) of this line */
HFeatureFlags single; /* a bitfield */
Hkey ref; /* data base key of the underlying */
long all;
/* contour */
} def;
INT4 first; /* index of the first point of the */
UINT1 shape; /* SHAPE_* */
/* underlying contour belonging to */
HBOOL is_convex;
/* current side of the polygon */
HBOOL is_filled;
INT4 last; /* index of the last contour point */
} Hline_seg;
HBOOL is_thin;
typedef struct poly_type {
float circularity;
INT4 num_line; /* number of lines */
float compactness;
INT4 len_line; /* maximum number of lines (size */
float contlength;
/* of the array lines) */
float convexity;
Hline_seg *lines; /* control points of the polygon */
float phi;
} Hpoly;
float ra, rb;
float Figure 6.10: ra_,Therb_;
XLD data type Hpoly for subpixel polygons.
float anisometry, bulkiness, structure_faktor;
float m11, m20, m02, ia, ib;
H ERR XLD
float CAND as result of the
row, procedure call, if no attribute with the specified name is de-
col;
fined. INT4 area;
The XLDINT2 data type Hpolyrow1,col1,row2,col2;
, displayed in Figure 6.10, encodes subpixel accurate polygons.
float row_rect, col_rect, phi_rect, length1, length2;
Basically it contains an array of control points. In many applications such polygons are derived
float row_circle, col_circle, radius;
from contours. Thus, the data structure can also hold a reference to the underlying part of a
INT2 min_chord, max_chord;
contour specified by a HALCON data base key.
INT2 min_chord_gap, max_chord_gap;
} HRegFeature;
6.4 ControlFigure
Parameters (Hpar
6.5: Data type
Abbildung A.5: , Hcpar
HRegFeature for)region features.
Datenstruktur: Hregfeature
all features extracted so far to avoid repeating a computation. HFeatureFlags encodes, which
typedef union {
features already have been extracted. Do not forget to reset these flags if you modify a region.
INT4 l; /* 4 byte integer */
float f; /* 4 byte real */
char *s; /* string */
} Hpar;
typedef struct {
Hpar par;
INT1 type;
} Hcpar;
Figure 6.11: Data types Hpar and Hcpar for control parameters.
Abbildung A.6: Datenstruktur: Hcpar
The HALCON data types Hpar and Hcpar are used within the C-Interface to pass control pa-
rameters to supply procedures. Fig. 6.11 shows the corresponding definitions. Hpar encodes
37
Literaturverzeichnis
[C-Interface] MVTec Software GmbH, HALCON C-Interface Programmer’s Manual Ver-

sion 5.2,MVTec Software GmbH, München 1999
[Gooosens94] Michael Goosens, Frank Mittelbach, Alexander Samarin, Der LATEX-

Begleiter, Addison Wesley GmbH, München 1994
38
Abbildungsverzeichnis
1.1 Schnittstelle C-Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.1 Verzeichnisstruktur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1 hdevelop: operator→Filter→UserSmoothing→user mean image . . . . . . 8

3.2 hdevelop: Suggestions→Successor . . . . . . . . . . . . . . . . . . . . . . . 9
5.1 halcon Datenbank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5.2 Neue DLL 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.3 Neue DLL 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.4 Projekt hinzufügen 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.5 Projekt hinzufügen 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.6 Arbeitsbereich-Fenster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.7 Abhängigkeiten 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.8 Abhängigkeiten 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.9 Abhängigkeiten 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.10 Einstellungen 1.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.11 Einstellungen 1.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.12 Einstellungen 1.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.13 Einstellungen 2.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.14 Einstellungen 2.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.15 Einstellungen 3.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.16 Einstellungen 3.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.17 Visual C++: Extras→Optionen . . . . . . . . . . . . . . . . . . . . . . . . 30
5.18 Bibliothek-Verzeichnis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.19 Include-Verzeichnis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.20 Aktives Projekt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.1 HALCONEXTENSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
A.1 Datenstruktur: Himage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

A.2 Pixelarten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
A.3 Bildarten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
A.4 Datenstruktur: Hrlregion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
A.5 Datenstruktur: Hregfeature . . . . . . . . . . . . . . . . . . . . . . . . . . 37
39
ABBILDUNGSVERZEICHNIS ABBILDUNGSVERZEICHNIS
A.6 Datenstruktur: Hcpar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
40

Halcon Schulung

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Halcon Schulung

Hochgeladen von

Copyright:

Verfügbare Formate

Schulungsunterlagen: Halcon C-Interface

• Ein Verzeichnis des Erweiterungs-Paketes mit vorgeschriebener Unterstruktur (siehe

• Eine Def-Datei, die die Dokumentation des Erweiterungspaketes in einer skript-

• Mehrere Dateien, die die Dokumentation des Erweiterungs-Paketes beinhalten und

Control Iconic Control Iconic

Abbildung 1.1: Datenflußdiagramm der Halcon-Schnittstelle

Abbildung 2.1: Verzeichnisstruktur eines Erweiterungs-Paketes

• Alle Operator-Beschreibungen beginnen mit einem Header (siehe Abschnitt 3.1.1).

• Alle folgenden Informationen sind in ihrer Reihenfolge keiner Regel unterstellt.

Als Beispiel für den Mean-Filter:

3. Eingabekontrollparameter: Alle nichtikonischen Parameter, also Parameter, die nicht

4. Ausgabekontrollparameter: Alle nichtikonischen Parameter, die der Schnitstelle zu-

Abbildung 3.1: Ausschnitt aus hdevelop: Im Menüpunkt

3.1.6 Predecessor, successor, alternatives

Abbildung 3.2: Ausschnitt aus hdevelop: Im Menüpunkt Suggestions→Successor werden

3.1.8 Result state

3.2.2 Default type

default_type: integer, real, string;

3.2.3 Sem type

• ikonische Daten (Objektparameter):

– object (jedes ikonisches Objekt: images, regions, XLDs)

• elementare Daten (Kontrollparameter):

– number (alle Kontrollparameter)

• geometrische Daten (Kontrollparameter):

multivalue: true, false, optional;

3.2.6 Default value

Alle weiteren Schlüsselwörter sind in [C-Interface] beschrieben. Diese Schlüsselwörter

4.1 C-Schnittstellen Dateien

Dafür muß der Interpreter in folgender Weise aufgerufen werden:

Beide Dateien werden in die C-Schnittstellen-DLL eingebunden (siehe Abschn. 5.3.1).

4.2 C++-Schnittstellen Dateien

hcomp -u -D -pPAKET Destination+Name der def-Datei

Diese Dateien werden in die CPP-Schnittstellen-DLL eingebunden (siehe Abschn. 5.3.1).

4.3.1 Dokumentation für die Skriptsprache in hdevelop

4.3.2 Dokumentation für die Programmiersprache C

4.3.3 Dokumentation für die Programmiersprache C++

4.4 Dateien für Onlinezufriff der Dokumentation

5.1 Die Supply-Funktion: CIPUserMeanImage

5.1.1 Übernahme der Eingabeparameter

5.1.1.1 nichtikonische Parameter

HGetCPar: Die Funktion HGetCPar hat folgende Parameter:

Die Parameter haben folgende Bedeutungen:

*num gibt die Anzahl der ausgegebenen Elemente an.

5.1.1.2 ikonische Parameter

1st input object parameter 2nd input object parameter

1st input object parameter

Die Bedeutung der einzelnen Parameter ist:

proc handle siehe 5.1.1.1

Dabei haben die einzelnen Parameter die folgenden Bedeutungen:

proc handle siehe 5.1.1.1.

HAllObj: HAllObj(Hproc_handle proc_handle,

HAllComp: HAllComp(Hproc_handle proc_handle,

5.1.2 Übergabe der Ausgabeparameter

5.1.2.1 nichtikonische Parameter

5.1.2.2 ikonische Ausgabeparameter

• Leere Kanäle. Diese können mit HDefObj, HPutImage, oder HPutDImage

HCkNoObj: überprüft, ob alle ikonischen Eingabeparameter initialisierte Objkete ent-

5.2 Die Aktion-Funktion: IPUserMeanImage

5.3 Visual C++ - Projekt

Sind beide Projekte hinzugefügt, erscheinen diese im Fenster

Abbildung 5.6: Visualisierung der hinzugefügten Projekte im Arbeitsbereichsfenster

Abbildung 5.8: Abhängigkeit zwischen

Abbildung 5.9: Abhängigkeit zwischen