Halcon-schulung

Schulungsunterlagen: Halcon C-Interface Florian Raisch [email protected]

Inhaltsverzeichnis ¨ 1 Uberblick

1

2 Paketstruktur

3

3 def-Datei 3.1 Operator-Beschreibung . . . . . . . . . . . 3.1.1 Header . . . . . . . . . . . . . . . . 3.1.2 Short . . . . . . . . . . . . . . . . . 3.1.3 Abstract . . . . . . . . . . . . . . . 3.1.4 Module . . . . . . . . . . . . . . . 3.1.5 Chapter . . . . . . . . . . . . . . . 3.1.6 Predecessor, successor, alternatives 3.1.7 Attention . . . . . . . . . . . . . . 3.1.8 Result state . . . . . . . . . . . . . 3.2 Parameterbeschreibung . . . . . . . . . . . 3.2.1 Name . . . . . . . . . . . . . . . . 3.2.2 Default type . . . . . . . . . . . . . 3.2.3 Sem type . . . . . . . . . . . . . . 3.2.4 Multivalue . . . . . . . . . . . . . . 3.2.5 Description . . . . . . . . . . . . . 3.2.6 Default value . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

5 5 5 6 7 7 7 8 9 9 10 11 11 11 13 13 13

4 hcomp 4.1 C-Schnittstellen Dateien . . . . . . . . . . . . . . . . . . 4.2 C++-Schnittstellen Dateien . . . . . . . . . . . . . . . . 4.3 Dokumentation . . . . . . . . . . . . . . . . . . . . . . . 4.3.1 Dokumentation f¨ ur die Skriptsprache in hdevelop 4.3.2 Dokumentation f¨ ur die Programmiersprache C . . 4.3.3 Dokumentation f¨ ur die Programmiersprache C++ 4.4 Dateien f¨ ur Onlinezufriff der Dokumentation . . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

. . . . . . .

14 14 15 15 15 16 16 16

i

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . .

INHALTSVERZEICHNIS

INHALTSVERZEICHNIS

5 DLL 5.1 Die Supply-Funktion: CIPUserMeanImage . ¨ 5.1.1 Ubernahme der Eingabeparameter . 5.1.1.1 nichtikonische Parameter . 5.1.1.2 ikonische Parameter . . . . ¨ 5.1.2 Ubergabe der Ausgabeparameter . . 5.1.2.1 nichtikonische Parameter . 5.1.2.2 ikonische Ausgabeparameter 5.1.3 Hilfsmacros . . . . . . . . . . . . . . 5.2 Die Aktion-Funktion: IPUserMeanImage . . 5.3 Visual C++ - Projekt . . . . . . . . . . . . 5.3.1 Projekterstellung . . . . . . . . . . . 5.3.2 Projekteinstellungen . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

. . . . . . . . . . . .

17 17 18 18 19 22 23 23 25 26 26 26 27

6 Sytemeinstellungen

32

A

34 34

A.1 Datentyen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ii

Kapitel 1 ¨ Uberblick ¨ Dieses Kapitel soll einen kurzen Uberblick u ¨ber die Komponenten eines halcon-ErweiterungsPaketes (DLL) und der Schnittstelle C-Interface zum Einbinden eines Erweiterungs-Paketes geben. Diese Schnittstelle schreibt die Struktur und die Bestandteile des ErweiterungsPaketes 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¨ahnlichen Sprache beschreibt (siehe Kap. 3). • Eine DLL, die die neuen Operatoren enth¨alt (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 Operator 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 enth¨alt, 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 zusammengestellt. 1

¨ KAPITEL 1. UBERBLICK 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 G¨ ultigkeit zu u ufen und Parameter, die als Felder vorliegen, in ihre einzelnen Kom¨berpr¨ ponenten zu zerlegen und einzeln an die Aktion-Funktion zu u ¨bergeben. Die Aktion-Funktion f¨ uhrt die eigentliche Aufgabe, hier im speziellen die eigentliche Bildverarbeitungsaufgabe durch. In Abbildung 1.1 ist das Datenflußdiagramm f¨ ur Halcon-Operatoren abgebildet. Application Programs Output

Input

HALCON Database

C or C++ Interface

Buffer

Control Parameter

Buffer

Control Parameter

Iconic Objects

Iconic 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 m¨ ussen. Das Verzeichnis hat folgende Unterordner: bin\i486-nt4: Dieses Verzeichnis enth¨alt 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, abgelegt. doc: Dieses Verzeichnis besitzt eine sehr verzweigte Unterstruktur. Die Struktur h¨angt davon ab, welche Dokumentationen man sich mit Hilfe des Intepreters hcomp (siehe Kap. 4) erstellen l¨aßt. Hier wird nur die Notwendige Struktur f¨ ur 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 enth¨alt Dateien die n¨otig 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 m¨ ussen 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 ben¨otigt werden (PAKET.lib,PAKETc.lib und PAKETcpp.lib). source: In diesem Verzeichnis stehen die einzelnen Source-Codes f¨ ur die Halcon-Operatoren und die Schnittstellen-DLLs. 3

KAPITEL 2. PAKETSTRUKTUR PAKET PAKETc PAKETcpp Diese Verzeichnisstruktur jedesmal von Hand anzulegen ist sehr m¨ uhsam. 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 Uberblick 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 Operators (Erweiterungs-Paketes) stehen, die die Halcon-Schnittstelle ben¨otigt (hdevelop, C, C++). In diesem Kapitel werden alle notwendigen Informationen und deren Syntax anhand des Beispieles f¨ ur den Mittelwert-Filter-Operator erkl¨art. Alle m¨oglichen 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 Restriktionen 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
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 f¨ ur den Mean-Filter: user_mean_image
3.1.2

Short

Das Schl¨ usselwort short dient zur Kurzbeschreibung des Operators. Dem Schl¨ usselwort 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 f¨ ur alle Schl¨ usselw¨orter, die ausschließlich Textinformation u ¨ber den Operator enthalten. Die Formatierung der Textinformation solcher Schl¨ usselw¨orter kann LATEX-Kommandos [Gooosens94] einschließlich deren Syntax unterliegen. 6

KAPITEL 3. DEF-DATEI

3.1.3

3.1. OPERATOR-BESCHREIBUNG

Abstract

Das Schl¨ usselwort abstract ist ebenfalls ein Schl¨ usselwort, das ausschließlich Textinformation u usselwort abstract folgt, ¨ber den Operator enth¨alt. Die Information, die dem Schl¨ 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 Schl¨ usselwort gibt an, welchem halcon-Modul der Operator zugeordnet wird. F¨ ur Erweiterungspakete ist jedoch vorgeschrieben, diese dem Modul basic zuzuordnen. Beispiel: module basic;

3.1.5

Chapter

Die Funktion des Schl¨ usselwortes 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 Men¨ upunkt Operators im Programm hdevelop. Man unterliegt bei der Einteilung des Operators in ein Kapitel und einen Abschnitt keinen 7

KAPITEL 3. DEF-DATEI

3.1. OPERATOR-BESCHREIBUNG

Restriktionen. So kann man sowohl neue Kapitel und Abschnitte er¨offnen, 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 d¨ urfen Namen von Kapiteln bzw. Abschnitten keine Leerzeichen beinhalten. Will man den Namen eines Kapitels oder eines Abschnitts aus zusammengesetzten W¨orter bilden, sollte man einen Bindestrich (-) benutzen. Beispiel: chapter.english Filter,UserSmoothing; Der Operator user mean image wird also in das Kapitel Filter im Abschnitt UserSmoothing eingetragen (siehe Abb. 3.1).

Abbildung 3.1: Ausschnitt aus hdevelop: Im Men¨ upunkt operator→Filter→UserSmoothing→user mean image ist der Operator zu finden.

3.1.6

Predecessor, successor, alternatives

Diese 3 Schl¨ usselw¨orter dienen dazu Anwendern den Zusammenhang zu erl¨autern, indem der Operator u usselw¨ortern m¨og¨blicherweise verwendet wird. So werden mit diesen Schl¨ liche Vorg¨anger-, Nachfolger- oder ¨ahnliche Operatoren definiert. Diese Operatoren kann man in hdevelop im Men¨ u Suggestions abfragen (siehe Abb. 3.2), bzw. in der Hilfe-Datei zu diesem Operator werden diese Vorschl¨age ebenfalls aufgef¨ uhrt.

8

KAPITEL 3. DEF-DATEI

3.1. OPERATOR-BESCHREIBUNG

Abbildung 3.2: Ausschnitt aus hdevelop: Im Men¨ upunkt Suggestions→Successor werden m¨ogliche Nachfolger zum ausgew¨ahlten Operator angezeigt. Beispiel: successor dyn_threshold, regiongrowing; alternatives smooth_image, gauss_image;

3.1.7

Attention

Mit attention wird auf m¨ogliche Fehlerquellen und Beschr¨ankungen des Operators hingewiesen. 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 Schl¨ usselwort result state beschreibt den R¨ uckgabewert des Operators und m¨oglicherweise 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 erl¨auterten Schl¨ usselw¨orter beschrieben wurde, werden die im header (siehe Abschn. 3.1.1) angegebenen Parameter n¨aher spezifiziert. F¨ ur unser Beispiel sieht das folgendermaßen aus: parameter InputImage:

input_object;

description.english:

Image to be smoothed.;

description.german: sem_type:

Zu gl\"{a}ttendes Bild.; image;

type_list:

byte;

multivalue:

optional;

parameter MeanImage:

output_object;

description.english:

Smoothed Image.;

description.german: sem_type:

Gegl\"{a}ttetes Bild.; image;

multivalue: parameter Masksize:

optional;

input_control;

description.english:

Size of filter-mask;

description.german:

Gr\"{o}{\ss}e der Filtermaske;

sem_type:

integer; 10

KAPITEL 3. DEF-DATEI

3.2. PARAMETERBESCHREIBUNG

type_list:

integer;

default_type: default_value:

integer; 5;

value_list:

3,5,7,9,11,13,15,17,19;

multivalue:

optional;

assertion:

Masksize > 2 && Masksize < 20;

Jede Beschreibung eines Parameters beginnt mit dem Schl¨ usselwort parameter, dem weitere Schl¨ usselw¨orter folgen. All diesen Schl¨ usselw¨ortern 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 Parameters, dessen Standardtyp (default type), dessen semantischer Typ (sem type) und die Anzahl der Parameter (multivalue). In den n¨achsten Abschnitten werden die am h¨aufigsten benutzten Schl¨ usselw¨orter zur Beschreibung von Parametern n¨aher beschrieben. Alle Schl¨ usselw¨orter 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 Schl¨ usselwort 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 Auff¨ uhrung der Parameter im header (siehe Absch. 3.1.1) u ¨bereinstimmen.

3.2.2

Default type

Dieses Schl¨ usselwort wird nur im Zusammenhang mit Kontrollparmetern ben¨ utzt. Der default type gibt an, was f¨ ur eine Art von Variable im Normalfall f¨ ur diesen Parameter angenommen wird. Der default type muß genau einen der folgenden Werte annehmen. default_type:

3.2.3

integer, real, string;

Sem type

Dieses Schl¨ usselwort 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 n¨otig, wenn 11

KAPITEL 3. DEF-DATEI

3.2. PARAMETERBESCHREIBUNG

man in einer objektorientierten Sprache wie C++ die Halcon-Operatoren einbindet. Einige Parameter m¨ ussen 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 Verf¨ ugung stehen, sind unten aufgef¨ uhrt (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

KAPITEL 3. DEF-DATEI

3.2.4

3.2. PARAMETERBESCHREIBUNG

Multivalue

multivalue gibt an, ob der Parameter als Array u ¨bergeben werden muß (true) oder ob nur ein einzelner Wert zul¨assig ist (false). Ist beides m¨oglich, wird multivalue auf optional gesetzt. multivalue:

true, false, optional;

Die folgenden Schl¨ usselw¨orter sind zur Beschreibung eines Parameters nicht mehr zwingend notwendig, aber oft sehr hilfreich.

3.2.5

Description

Mit dem Schl¨ usselwort description.language wird eine kurze Beschreibung des Parameters in der jeweiligen Sprache gegeben. Der beschreibende Text kann wie in Abschnitt 3.1 bei allen beschreibenden Schl¨ usselw¨ortern der LATEX-Sytax unterliegen (siehe [Gooosens94]). A description.english: LTEX/Ascii-Text;

3.2.6

Default value

default value wird nur bei Eingabekontrollparametern ben¨ utzt und kann dem Anwender sehr hilfreich sein, um geeignete Werte zu finden. Default Values f¨ ur Strings werden nicht mit Anf¨ uhrungszeichen angegeben (nicht:’AB’, sondern: AB). Die Ausnahme stellen der leere String und Strings mit Sonderzeichen dar. default_value: DefaultValue;

Alle weiteren Schl¨ usselw¨orter sind in [C-Interface] beschrieben. Diese Schl¨ usselw¨orter werden jedoch nicht allzu h¨aufig benutzt und deshalb hier nicht explizit aufgef¨ uhrt.

13

Kapitel 4 hcomp Der Interpreter hcomp der zum Lieferumfang des halcon-Paketes geh¨ort, 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 n¨achsten Abschnitten erl¨autert. Der Aufruf des Interpreters geschieht in der DOS-Konsole. Um den Interpreter von jedem Verzeichnis aus aufrufen zu k¨onnen, sollte man der Systemvariable PATH den Pfad des Interpreters hinzuf¨ ugen. 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, m¨ ussen zwei Dateien mit dem ” Interpreter hcomp erstellt werden. Die Namen der Dateien lauten: • HCPAKET.c • HCPAKET.h Daf¨ ur 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

4.2. C++-SCHNITTSTELLEN DATEIEN

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, m¨ ussen in folgendes Unterverzeichnis kopiert werden: • \source\PAKETcpp Diese Dateien werden in die CPP-Schnittstellen-DLL eingebunden (siehe Abschn. 5.3.1).

4.3

Dokumentation

Es ist grunds¨atzlich m¨oglich die Dokumentation eines Operators als Postscript, PDFDokument oder HTML-Seite zu erstellen. Der Onlinezugriff auf die Dokumentation des Operators unter hdevelop geschieht jedoch immer auf die HTML-Seite. Das Erstellen dieses 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 f¨ ur 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, m¨ ussen mehrere Dokumentationen erstellt werden.

4.3.1

Dokumentation fu ¨ r die Skriptsprache in hdevelop

Um die Dokumentation f¨ ur 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 m¨ ussen in das Paketunterverzeichnis (siehe Kap. 2) • \doc\html\reference\hdevelop

15

¨ ONLINEZUFRIFF DER DOKUMENTATION KAPITEL 4. HCOMP 4.4. DATEIEN FUR kopiert werden. Achtung: Entscheidet man sich die Dokumentation in mehreren Sprachen zu verfassen, sollte man die Dokumentation der gew¨ unschten Sprache in obiges Verzeichnis kopieren. F¨ ur die Dokumentation in der anderen Sprache sollte man sich ein weiteres Paketunterverzeichnis anlegen. Z.B.: • \doc english\html. . . Dies gilt auch f¨ ur 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 m¨ ussen 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 m¨ ussen 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 OnlineZugriff auf die Dokumentation eines Operators hat und dieser in hdevelop in einen Men¨ upunkt eingebettet wird, braucht man Dateien die dieses erm¨oglichen. Diese Dateien werden mit folgendem Interpreteraufruf erstellt: hcomp -M -llanguage Destination+Name der def-Datei (language: german, english) Die Dateien m¨ ussen in folgendes Paketunterverzeichnis kopiert werden (siehe Kap. 2): • \help kopiert werden. Wer diese ganze Prozedur einmal gemacht hat, weiß danach genau aus welchen Bestandteilen ein Erweiterungspaket besteht. Deshalb ist es auch nur einmal notwendig diese Prozedur zu machen, da auf der Schulungsdiskette eine bat-Datei mit dem Namen hcompall ist, die die oben erl¨auterten Schritte ausf¨ uhrt. 16

Kapitel 5 DLL Auf der Schulungsdiskette finden Sie die DLL usermean.dll“ im Verzeichnis example\user” mean\bin\i486-nt4. Der dazugeh¨orige 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 erl¨autert. Hierzu werden einige von halcon bereitgestellte Macros verwendet. Auf diese in diesem Beispiel verwendeten Macros und deren zugrunde liegenden Funktionen wird hier n¨aher 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 Randbehandlung des zu filternden Bildes. Die zwei wichtigen Funktionen der DLL sind die Funktionen IPUserMeanImage und die Funktion CIPUserMeanImage. Diese zwei Funktionen sind die in Kapitel 1 erw¨ahnten Supply- & Aktion-Funktionen. Die Supply-Funktion CIPUserMeanImage wird von der halcon-Schnittstelle aufgerufen und hat nur einen Parameter. Diese Funktion wird in Abschnitt 5.1 n¨aher erl¨autert. Die Aktion-Funktion IPUserMeanImage 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 holen, sie auf Validit¨at zu pr¨ ufen und an die Aktion-Funktion weiterzugeben. Außerdem werden in der Supply-Funktion Ausgabe-Parameter in der halcon-Datenbank registriert und Speicher f¨ ur diese Parameter allokiert. Zus¨atzlich u ¨bergibt die Supply-Funktion die Ausgabeparameter der halcon-Schnittstelle. Die einzige Verbindung zwischen der Supply-Funktion und der Schnittstelle ist der Parameter der Supply-Funktion. Er wird der Supply-Funktion von der Schnittstelle u ¨bergeben und mit ihm k¨onnen alle n¨otigen Verbindungen zur Schnittstelle hergestellt werden. 17

KAPITEL 5. DLL

5.1.1

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

¨ Ubernahme der Eingabeparameter

Wie in Abschnitt 3.1.1 beschrieben, wird in halcon nicht nur zwischen Eingabe- und Ausgabeparametern unterschieden, sondern auch zwischen ikonischen und nicht ikonischen Parametern. Diese Unterscheidung spiegelt sich in der Repr¨asentation der Daten in der halcon-Datenbank wider. Als ersten Schritt behandeln wir in Abschnitt 5.1.1.1 den ein¨ facheren Fall der Ubernahme der nichtikonischen Eingabeparameter. In Abschnitt 5.1.1.2 ¨ wird der Fall der Ubernahme ikonischer Parameter behandelt. 5.1.1.1

nichtikonische Parameter

Es gibt zwei Funktionen, die es erlauben nichtikonische Eingabeparameter von der Schnittstelle zu u ¨bernehmen: HGetCPar: Die Funktion HGetCPar hat folgende Parameter: HGetCPar(Hproc_handle INT

proc_handle, par_num,

INT

type,

Hcpar

*val,

INT4_8 INT4_8

min,max, *num)

Die Parameter haben folgende Bedeutungen: proc handle ist der einzige Parameter, der der Supply-Funktion von halcon u ¨bergeben wird und beschreibt den Prozeß, dem die Funktion angeh¨ort n¨aher. 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) abgespeichert. 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) zur¨ uck. F¨ ur val muß gen¨ ugend Speicher allokiert werden. 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 gr¨oßer als die Anzahl der allokierten Elemente f¨ ur val sein. 18

KAPITEL 5. DLL

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

*num gibt die Anzahl der ausgegebenen Elemente an. HGetSPar: Die Funktion HGetSpar liefert im Gegensatz zu HGetCPar nur eine festgelegte Anzahl von Elementen eines Parameters. Die Funktion hat folgende Parameter: HGetSPar(Hproc_handle INT

proc_handle, 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 Ubernahme 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 h¨aufigsten gebrauchten Funktionen vorgestellt (die restlichen Funktionen sind in [C-Interface] nachzuschlagen). Bevor jedoch die einzelnen Funktionen f¨ ur den Zugriff auf Eingabeparameter 7.1. BASIC ACCESS TO ICONIC INPUT OBJECTS 61 beschrieben werden, muß das grunds¨atzliche Prinzip der halcon-Datenbank erkl¨art werden.

operator call 1st input object parameter

1st input object parameter 1st object of 1st input object parameter

2nd input object parameter

parameter number Hkey HGetObj

obj_key

HGetComp Hkey region

channel1

HGetImage HGetRL

Abbildung 5.1: Aufbau der halcon-Datenbank Figure 7.2: Direct access to input image objects. INT2 INT4 Hkey

comp_key

channel2

inp_pars; num_objs; key;

19

Himage Hrlregion

image region

KAPITEL 5. DLL

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

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 dieser 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 Kan¨alen zusammengestetzt wird, bestehen. F¨ ur diese Komponenten werden die daf¨ ur vorgesehenen Strukturen (Himage, Hrlregion) in der Datenbank abgelegt. Der Vorteil dieser Art der Zuweisung von Parametern ist, daß man z.B. f¨ ur Bilder, die dieselbe Grauwertmatrix, 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 umst¨andliche Prozedur durchmachen muß, um auf ein einfaches Bild zu zugreifen. Man kann auf ein Bild und seine Region zugreifen, wenn man folgende Funktionen nacheinander aufruft: HGetObj: Mit HGetObj hat man Zugriff auf die ID eines bestimmten Eingabeparameters. HGetObj(Hproc_handle INT

proc_handle, 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 Eingabeparameter. *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 Datenbank.

20

KAPITEL 5. DLL

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

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 daf¨ ur f¨ ur die einzelnen Kan¨ale eines Bildes. *comp key ist der Ausgabeparameter der Funktion und gibt die ID der ObjektKomponente an. Als letzter Schritt wird nun die Funktion HGetImage, HGetRl oder HGetXLD aufgerufen, 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 Hkey Himage

proc_id, image_key, *image)

Der Parameter image key wurde mit durch die Funktion HGetComp gewonnen und *image liefert einen Zeiger auf die Struktur Himage zur¨ uck, die ein Einzelbild beschreibt. HGetImage liefert einen Zeiger direkt auf die Grauwertmatrix des Bildes zur¨ uck, 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 Datenacquisition beschrieben. Diesen Macros liegen die oben beschriebenen Funktionen zu Grunde.

21

KAPITEL 5. DLL HAllObj:

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

HAllObj(Hproc_handle

proc_handle,

INT Hkey

par_num, &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 Eingabeparameter enth¨alt. 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 Kan¨ale eines Bildes realisiert ist. In einem Durchlauf werden zwei Grundfunktionen aufgerufen. Als erstes wird HGetComp aufgerufen, welche die Komponenten-ID zur Objekt-ID obj key zur¨ uckliefert. Danach wird HGetImage aufgerufen, welche die Bildmatrix in image in zur¨ uckliefert.

5.1.2

¨ Ubergabe der Ausgabeparameter

Wie bei den Eingabeparametern wird bei den Ausgabeparametern auch zwischen ikonischen und nichtikonischen Parametern unterschieden. Auch hier erweist sich der Fall der nichtikonischen Ausgabeparametern als der einfachere. Bei Ausgabeparametern muß zu¨ s¨atzlich zur Ubergabe des Parameters Speicher f¨ ur den Parameter allokiert werden. Hierf¨ ur gibt es eigene halcon-Macros (siehe [C-Interface]).

22

KAPITEL 5. DLL 5.1.2.1

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

nichtikonische Parameter

¨ F¨ ur die Ubergabe nichtikonischer Ausgabeparameter gibt es nur eine Funktion: ¨ HPutCPar: Bei der Ubergabe von nichtikonischen Parametern muß man Speicher nur allokieren, wenn ein Parameter als Element einen String enth¨alt (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 Hcpar

par_num, *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 m¨ ussen folgende Schritte zur Ubergabe nichtikonischer Objekte durchgef¨ uhrt werden: • speichern der berechneten Kan¨ale, Regionen und XLDs in der halcon-Datenbank u ¨ber IDs. • Speicher allokieren f¨ ur Regionen, Bilder und XLDs. • Regionen und Kan¨ale zu Bildern verbinden. • den berechneten Regionen, Bildern & XLDs ein Ausgabeobjekt einschließlich Komponente u ¨ber IDs zuweisen. Zuerst werden hierzu wieder die Grundfunktionen und dann einige Macros, die im Beispiel verwendet wurden, erl¨autert. Die restlichen Funktionen und Macros sind in [C-Interface] beschrieben. HCrObj: erstellt ein neues Objekt (Region o. Bild) in der halcon-Datenbank. Dieses Objekt enth¨alt folgende Standardkomponenten: • Eine leere Region als Area of Definition. Diese kann mit HPutDRL oder HPutRect ge¨andert werden. 23

KAPITEL 5. DLL

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

• Leere Kan¨ale. Diese k¨onnen 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 erh¨alt 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 Kan¨ale zugewiesen wie dem Objekt mit der ID input key. Dies ist insbesondere bei Filteranwendungen sinnvoll, wenn sich beim Ausgabeobjekt nur“ die Grauwerte der Kan¨ale ” ¨andern. HCopyObj(Hproc_handle

proc_handle,

Hkey

input_key,

INT

par_num,

Hkey

*output_key)

HNewImage: stellt Speicher f¨ ur das neue Bild (den neuen Kanal) zur Verf¨ ugung. HNewImage(Hproc_handle

proc_handle,

Himage INT

*output_image, type,

INT

width,height)

HNewImage allokiert Speicher f¨ ur 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

KAPITEL 5. DLL

5.1. DIE SUPPLY-FUNKTION: CIPUSERMEANIMAGE

HPutImage: speichert den Bildkanal - bestimmt durch output image - in der halconDatenbank und gibt die Komponenten-ID comp key zur¨ uck 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

5.1.3

proc_handle,

Hkey Hkey

obj_key comp_key,

INT

comp)

Hilfsmacros

Wie man im Beispielquelltext sieht, gibt es nicht nur halcon-spezifische Macros, die der Parameter¨ ubergabe und Speicherallokierung dienen, sondern noch einige Macros, die unterst¨ utzende Wirkung bei der Fehlerbehandlung haben. Die zwei verwendeten Macros werden hier kurz beschrieben, alle anderen sind in [C-Interface] nachzulesen. HCkNoObj: u uft, ob alle ikonischen Eingabeparameter initialisierte Objkete ent¨berpr¨ halten. Falls dies nicht der Fall ist, wird die Supply-Funktion mit einem Fehler beendet. HCkP: u uft den R¨ uckgabewert einer Funktion bzw. eines Macros. Falls der R¨ uck¨berpr¨ gabewert einen Fehlerzustand beschreibt, wird die Supply-Funktion mit der u ¨bergebenen Fehlermeldung beendet.

25

KAPITEL 5. DLL

5.2

5.2. DIE AKTION-FUNKTION: IPUSERMEANIMAGE

Die Aktion-Funktion: IPUserMeanImage

In diesem Beispiel werden in der Aktion-Funktion (IPUserMeanImage) keine spezifischen halcon-Funktionen verwendet. Deshalb wird im Skript nicht n¨aher auf die Funktion eingegangen.

5.3

Visual C++ - Projekt

Zum Erstellen der DLL muß ein Projekt Visual C++ Projekt angelegt werden. Die Vorgehensweise zum Anlegen eine Projektes und die Einstellungen des Projektes werden in den n¨achsten beiden Abschnitten anhand von Screenshots beschrieben.

5.3.1

Projekterstellung

Die nachfolgenden Screenshots zeigen die Vorgehensweise zur Erstellung eines DLL-Projektes f¨ ur ein halcon Erweiterungspaket. W¨ahlt man den Men¨ upunkt File→New ¨offnet sich folgendes Fenster: Man w¨ahlt im Datenblatt Projekt“ den Punkt Win32 Dynamik-Link ” ”

Abbildung 5.2: Wizard zum Erstellen eines neuen Visual C++ Projektes Library“ aus und tr¨agt den Paketnamen (hier: usermean) als Projektnamen im Editfeld Projektname“ ein. Als Pfad“ gibt man das Unterverzeichnis source des Pfades f¨ ur das Er” ” weiterungspaket an (siehe Kap. 2). Danach muß man den Dialog mit OK“ quittieren. Als ” n¨achstes erscheint folgender Dialog der mit der Einstellung Ein leeres DLL-Projekt“ quit” tiert wird. Nach diesem Schritt wird das leere Projekt erstellt. Diesem Projekt f¨ ugt man jetzt die Quelldatei PAKET.c hinzu (hier:usermean.c). Diese Datei enth¨alt 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 f¨ ugt 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 f¨ ugt 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 hinzugef¨ ugt (hier: HCPPusermean.cpp, HCPPusermeanGlobal.cpp, HCPPusermean.h). Nach dem Erstellen der Projekte m¨ ussen noch einige Einstellungen gemacht werden. Diese werden im n¨achsten Abschnitt beschrieben.

5.3.2

Projekteinstellungen

¨ Zur besseren Ubersicht sollte man die zwei Projekte PAKETc und PAKETcpp dem Projekt PAKET hinzuf¨ ugen (siehe Abb. 5.4-5.5).

Abbildung 5.4: Hinzuf¨ ugen eines Projektes zu einem Arbeitsbereich

Abbildung 5.5: Hinzuf¨ ugen eines Projektes zu einem Arbeitsbereich

Sind beide Projekte hinzugef¨ ugt, erscheinen diese im Fenster Arbeitsbereich“ (siehe Abb. 5.6). Da man zur Erstellung eines Erweiterungspaketes alle ” 27

KAPITEL 5. DLL

5.3. VISUAL C++ - PROJEKT

Abbildung 5.6: Visualisierung der hinzugef¨ ugten Projekte im Arbeitsbereichsfenster 3 Projekte kompilieren muß, ist es hilfreich, geeignete Abh¨angigkeiten zwischen den Projekten 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 abh¨angen, sollte dieses zuerst u ¨bersetzt werden. Die einzustellenden Abh¨angigkeiten und das Erreichen des dazu geh¨origen Dialoges ist in den Abb. 5.7-5.9 illustriert.

Abbildung 5.8: Abh¨angigkeit zwischen dem Projekt PAKETc und dem Projekt PAKET

Abbildung 5.7: Men¨ upunkt zum Erreichen des Abh¨angigkeiten-Dialog

F¨ ur jedes Projekt sind einige Einstellungen im Dialog Projekteinstellungen“, der u ¨ber ” den Men¨ upunkt Projekt→Einstellungen erreicht wird, zu erledigen. Die Einstellungen sind wiederum in den Abb. 5.10-5.16 illustriert.

28

KAPITEL 5. DLL

5.3. VISUAL C++ - PROJEKT

Abbildung 5.9: Abh¨angigkeit zwischen dem Projekt PAKETcpp und dem Projekt PAKETc

Abbildung 5.10: Allgemeine Einstellungen des Projektes PAKET

Abbildung 5.11: Debug-Einstellungen des Projektes PAKET

Abbildung 5.12: Linker-Einstellungen des Projektes PAKET

Abbildung 5.13: Allgemeine Einstellungen des Projektes PAKETc

Abbildung 5.14: Linker-Einstellungen des Projektes PAKETc

29

KAPITEL 5. DLL

5.3. VISUAL C++ - PROJEKT

Abbildung 5.15: Allgemeine Einstellungen des Projektes PAKETcpp

Abbildung 5.16: Linker-Einstellungen des Projektes PAKETcpp

Als letzte Einstellungen der Projekte m¨ ussen 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 Men¨ upunkt Extras→Optionen zu finden (siehe Abb. 5.17).

Abbildung 5.17: Men¨ upunkt Extras→Optionen zur Einstellung der Verzeichnisse

Abbildung 5.18: Einstellungen Bibliothek-Verzeichnisse

f¨ ur

Abbildung 5.19: Einstellungen Include-Verzeichnisse

f¨ ur

Nachdem alle Einstellungen gemacht sind, setzt man das Projekt PAKETcpp als aktives Projekt (siehe Abb. 5.20) und u ¨bersetzt die Projekte. Als n¨achstes sind noch zwei Einstel30

KAPITEL 5. DLL

5.3. VISUAL C++ - PROJEKT

lungen in der Sytemsteuerung zu machen, die in Kap. 6 beschrieben sind. Danach ist das Erweiterungspaket unter hdevelop und als Element der Bibliothek halcon lauff¨ahig.

Abbildung 5.20: Festlegen eines aktiven Projektes unter Visual C++

31

Kapitel 6 Sytemeinstellungen Der letzte Schritt, um das Erweiterungspaket lauff¨ahig zu machen, ist, halcon mitzuteilen, daß es ein Erweiterungspaket gibt und wo es sich befindet. Bei der Installation von halcon wurden 3 Umgebungsvariablen angelegt. Umgebungsvariablen kann man unter NT in der Systemsteuerung unter dem Eintrag System betrachten und ¨andern. Hierzu w¨ahlt 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 HALCONEXTENSIONS 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. Existieren 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 n¨achstes 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 Anderung der Variablen aktiv und der Operator m¨ usste bei einem Start von hdevelop aktiv sein.

33

Anhang A

A.1

Datentyen

CHAPTER 6. HALCON DATA TYPES

50

typedef union { HBYTE *b; HBYTE *z; HBYTE *d; INT1 *i; INT4 *l; float *f; HXYPixel xy; HComplexPixel c; HLutPixel lut; HInt2Pixel s; } HPixelImage;

/* /* /* /* /* /* /* /* /* /* /*

0..255 (BYTE_IMAGE) 0..255 mod 256 (CYCLIC_IMAGE) orientation 0..180 (DIR_IMAGE) -127..126 (INT1_IMAGE) 4 byte integer (LONG_IMAGE) 4 byte real (FLOAT_IMAGE) displacement vector field (XY_IMAGE) complex image (COMPLEX_IMAGE) byte with LUT (LUT_IMAGE) 2 bytes with sign (INT2_IMAGE)

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 #define #define #define #define #define #define #define #define #define

BYTE_IMAGE LONG_IMAGE FLOAT_IMAGE DIR_IMAGE CYCLIC_IMAGE INT1_IMAGE XY_IMAGE COMPLEX_IMAGE LUT_IMAGE INT2_IMAGE

(INT)1 (INT)2 (INT)4 (INT)8 (INT)16 (INT)32 (INT)64 (INT)128 (INT)256 (INT)512

/* 1 byte per pixel (0..255) /* 4 byte per pixel (INT4) /* 4 byte per pixel (float) /* edge orientation 0..180 /* 0..255 cyclic /* -127..126 /* 2 byte images with sign /* 2 float-images /* 34 (0..255) with color table /* 2 bytes with sign

Figure 6.2: Definitions of pixel types.

*/ */ */ */ */ */ */ */ */ */

UINT1 UINT1 UINT1 UINT2 UINT1 UINT2A. ANHANG } Himage;

min; hour; day; yday; mon; year;

/* /* /* /* /* /*

minutes 0.59 0..23 1..31 1..366 1..12 starting at 1900

*/ */ */ */ */ */ A.1.

DATENTYEN

Figure 6.1: Data type Himage for images. #define #define #define #define #define #define #define #define #define #define

BYTE_IMAGE LONG_IMAGE FLOAT_IMAGE DIR_IMAGE CYCLIC_IMAGE INT1_IMAGE XY_IMAGE COMPLEX_IMAGE LUT_IMAGE INT2_IMAGE

(INT)1 (INT)2 (INT)4 (INT)8 (INT)16 (INT)32 (INT)64 (INT)128 (INT)256 (INT)512

/* /* /* /* /* /* /* /* /* /*

1 byte per pixel (0..255) 4 byte per pixel (INT4) 4 byte per pixel (float) edge orientation 0..180 0..255 cyclic -127..126 2 byte images with sign 2 float-images (0..255) with color table 2 bytes with sign

*/ */ */ */ */ */ */ */ */ */

Figure 6.2: Definitions of pixel types. Abbildung A.2: Die verschiedenen Pixeltypen, die unter Himage (siehe Abb. A.1) m¨oglich sind R = HRow(L,image.width);

6.2. REGION (HRLREGION) C =DATA HCol(L,image.width);

51

Please see section 5.2.2 for routines to allocate image data within Himage. typedef struct { float *re; float *im; } HComplexPixel;

/* real image part /* imaginary image part

*/ */

typedef struct { INT2 *p; /* pixel INT1 num_bits; /* number of used bits } HInt2Pixel;

*/ */

typedef struct { INT1 *row; INT1 *col; } HXYPixel;

/* y-direction /* x-direction

*/ */

/* 0..255 /* length of color table

*/ */

typedef struct { HBYTE *b; INT num_lut; 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) m¨oglich 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

CHAPTER 6. HALCON DATA TYPES

52

typedef struct { INT2 l; INT2 cb; INT2 ce; } Hrun;

/* line number (row) of chord */ /* column index of beginning of chord */ /* column index of ending of chord */

typedef struct { HBOOL is_compl; INT4 num; INT4 num_max; HRegFeature feature; Hrun rl[RL_LENGTH]; } Hrlregion;

/* /* /* /* /*

region is complement number of chords maximal number of chords already processed features array of chords

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_connected8; HBOOL is_thin; float circularity; float compactness; float contlength; float convexity; float phi; 36 float ra, rb; float ra_, rb_; float anisometry, bulkiness, structure_faktor;

*/ */ */ */ */

HBOOL is_compl; /* region is complement */ INT4 num; /* number of chords */ INT4 num_max; /* maximal number of chords */ 56 CHAPTER 6. HALCON DATA TYPES HRegFeature feature; /* already processed features */ Hrun rl[RL_LENGTH]; /* array of chords */ } Hrlregion; ANHANG A.1. DATENTYEN typedefA.struct lin_seg_type { float row,col; a control point of the polygon: */ Figure 6.4: Data type/*Hrlregion 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 */ HBOOL is_connected4; } Hline_seg; HBOOL is_connected8; 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_,The rb_; XLD data type Hpoly for subpixel polygons. float anisometry, bulkiness, structure_faktor; float m11, m20, m02, ia, ib; H ERR XLD CAND as result of the procedure call, if no attribute with the specified name is defloat row, col; fined. INT4 area; INT2 row1,col1,row2,col2; The XLD data type Hpoly , 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.5: Data type HRegFeature for)region features. 6.4 ControlFigure Parameters (Hpar , Hcpar Abbildung A.5: 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 float char } Hpar;

l; f; *s;

/* 4 byte integer */ /* 4 byte real */ /* string */

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 parameters 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 Version 5.2,MVTec Software GmbH, M¨ unchen 1999 [Gooosens94] Michael Goosens, Frank Mittelbach, Alexander Samarin, Der LATEXBegleiter, Addison Wesley GmbH, M¨ unchen 1994

38

Abbildungsverzeichnis 1.1

Schnittstelle C-Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2

2.1

Verzeichnisstruktur . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4

3.1 3.2

hdevelop: operator→Filter→UserSmoothing→user mean image . . . . . . hdevelop: Suggestions→Successor . . . . . . . . . . . . . . . . . . . . . . .

8 9

5.1 5.2 5.3 5.4 5.5 5.6 5.7 5.8 5.9 5.10 5.11 5.12 5.13 5.14 5.15 5.16 5.17 5.18 5.19 5.20

halcon Datenbank . . . . . . . . Neue DLL 1 . . . . . . . . . . . Neue DLL 2 . . . . . . . . . . . Projekt hinzuf¨ ugen 1 . . . . . . Projekt hinzuf¨ ugen 2 . . . . . . Arbeitsbereich-Fenster . . . . . Abh¨angigkeiten 1 . . . . . . . . Abh¨angigkeiten 2 . . . . . . . . Abh¨angigkeiten 3 . . . . . . . . Einstellungen 1.1 . . . . . . . . Einstellungen 1.2 . . . . . . . . Einstellungen 1.3 . . . . . . . . Einstellungen 2.1 . . . . . . . . Einstellungen 2.2 . . . . . . . . Einstellungen 3.1 . . . . . . . . Einstellungen 3.2 . . . . . . . . Visual C++: Extras→Optionen Bibliothek-Verzeichnis . . . . . Include-Verzeichnis . . . . . . . Aktives Projekt . . . . . . . . .

. . . . . . . . . . . . . . . . . . . .

19 26 27 27 27 28 28 28 29 29 29 29 29 29 30 30 30 30 30 31

6.1

HALCONEXTENSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . .

32

A.1 A.2 A.3 A.4 A.5

Datenstruktur: Himage . . . Pixelarten . . . . . . . . . . Bildarten . . . . . . . . . . Datenstruktur: Hrlregion . . Datenstruktur: Hregfeature

34 35 35 36 37

. . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

39

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . . . . . . . . . . . . . . . . .

. . . . .

. . . . .

ABBILDUNGSVERZEICHNIS A.6 Datenstruktur: Hcpar

ABBILDUNGSVERZEICHNIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

40

37