find_ncc_models
— Suche der besten Matches mehrerer NCC-Modelle.
find_ncc_models(Image : : ModelIDs, AngleStart, AngleExtent, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels : Row, Column, Angle, Score, Model)
find_ncc_models
findet die besten NumMatches
Instanzen der NCC-Modelle, die in dem Tupel ModelIDs
übergeben werden, im Eingabebild Image
. Die Modelle müssen
zuvor mit create_ncc_model
erzeugt oder mit
read_ncc_model
eingelesen worden sein. Im Gegensatz zu
find_ncc_model
kann also eine Mehrzahl von
Modellen gleichzeitig im selben Bild gesucht werden.
Die Position und Rotation der gefundenen Instanzen des Modells wird
in Row
, Column
und Angle
zurückgeliefert.
In Score
wird die Bewertung der gefundenen
Instanzen zurückgegeben.
Der gefundene Modelltyp wird in Model
zurückgeliefert.
Nähere Informationen finden Sie in den parameterspezifischen Abschnitten.
Gegenüber find_ncc_model
unterscheidet sich die Semantik
aller Eingabeparameter etwas. Alle
Eingabeparameter müssen entweder genau ein Element enthalten oder
dieselbe Anzahl von Elementen wie ModelIDs
.
(NumLevels
kann auch zwei oder zweimal die Anzahl von
Elementen wie ModelIDs
enthalten; siehe unten.) Im ersten
Fall wird der Wert des Eingabeparameters für alle Modelle gleich
verwendet. Im zweiten Fall wird das jeweilige Element des
Eingabeparameters für das entsprechende Modell in ModelIDs
verwendet. Details hierzu werden im zugehörigen Abschnitt
weiter unten beschrieben.
Ein Aufruf von find_ncc_models
mit mehreren Werten für ModelIDs
, NumMatches
und
MaxOverlap
entspricht von der Wirkung her also mehreren
unabhängigen Aufrufen von find_ncc_model
mit den
jeweiligen Parametern, ist allerdings wesentlich effizienter.
Der Definitionsbereich des Bildes Image
gibt den
Suchbereich für den Referenzpunkt des Modells an, d.h. für den
Schwerpunkt der Region des Bildes, das zur Erzeugung des NCC-Modells
mit create_ncc_model
verwendet wurde. Ein eventuell mit
set_ncc_model_origin
anders gesetzter Ursprung wird nicht
berücksichtigt. Das Modell wird innerhalb des Definitionsbereiches
des Eingabebildes nur an den Stellen gesucht, an denen das Modell
vollständig in das Bild passt. Das bedeutet, dass das Modell nicht
gefunden werden kann, wenn es aus dem Bild herausragt, selbst wenn
es eine Bewertung größer als MinScore
erreichen würde.
Image
kann ein einzelnes Bildobjekt beinhalten oder
ein Bildobjektarray. Falls Image
ein einzelnes Bildobjekt
enthält, wird dessen Region als Suchbereich für alle Modelle in
ModelIDs
verwendet. Falls Image
mehrere
Bildobjekte enthält, wird die jeweilige Region als Suchbereich für
das entsprechende Modell aus ModelIDs
verwendet. In diesem
Fall müssen die Bilder, abgesehen von ihrer Region, identisch sein. D.h.
Image
kann nicht in beliebiger Weise mit concat_obj
aufgebaut werden, sondern muss aus demselben Bild mit
add_channels
oder äquivalenten Aufrufen erzeugt werden.
Falls das nicht der Fall ist, wird eine Fehlermeldung
zurückgeliefert.
Die Parameter AngleStart
und AngleExtent
legen den
Winkelbereich fest, in dem nach dem Modell gesucht wird. Der
Winkelbereich wird gegebenenfalls auf den Bereich beschnitten, der
bei der Erzeugung des Modells mit create_ncc_model
angegeben worden ist.
Außerdem ist zu beachten, dass es in manchen Fällen vorkommen kann, dass Instanzen gefunden werden, deren Rotation geringfügig außerhalb des übergebenen Winkelbereichs liegt. Dies kann dann auftreten, wenn der übergebene Winkelbereich kleiner ist als der Bereich, der bei der Erzeugung des Modells angegeben worden ist.
Der Parameter MinScore
legt fest, welche Bewertung ein
potentieller Match mindestens besitzen muss, damit er als eine
Instanz des Modells im Bild angesehen wird. Je größer der Wert von
MinScore
gewählt werden kann, desto schneller verläuft die
Suche. Falls erwartet werden kann, dass das Modell niemals verdeckt
wird, kann MinScore
auf so hohe Werte wie 0.8 oder sogar
0.9 gesetzt werden. Werden die Matches nicht bis zur untersten
Pyramidenebene verfolgt (siehe unten), kann es in manchen Fällen
vorkommen, dass Instanzen gefunden werden, deren Score geringfügig
unter dem Wert von MinScore
liegen.
Mit NumMatches
kann angegeben werden, wieviele Instanzen
des Modells im Bild höchstens gefunden werden sollen. Falls mehr
als NumMatches
Instanzen eine Bewertung größer als
MinScore
erreichen, werden nur die besten
NumMatches
Instanzen zurückgeliefert. Falls weniger als
NumMatches
Instanzen gefunden werden, werden nur diese
Instanzen zurückgeliefert, d.h. der Parameter MinScore
hat Vorrang vor NumMatches
. Sollen alle Modellinstanzen, deren
Bewertung MinScore
übersteigt, im Bild gefunden werden,
muss NumMatches
auf 0 gesetzt werden.
Falls NumMatches
einen Wert enthält, liefert
find_ncc_models
die NumMatches
besten Instanzen
des Modells unabhängig von der Art des Modells zurück. Falls
z.B. in ModelIDs
zwei Modelle übergeben werden und
NumMatches
= 2 gewählt wird, kann es sein, dass zwei
Instanzen des ersten Modells und keine des zweiten Modells, eine
Instanz des ersten Modells und eine des zweiten Modells oder keine
Instanz des ersten Modells und zwei des zweiten Modells
zurückgeliefert werden. Falls hingegen NumMatches
mehrere
Werte enthält, werden so viele Instanzen des jeweiligen Modells in
ModelIDs
zurückgeliefert, wie durch das entsprechende
Element von NumMatches
angegeben. Falls
z.B. NumMatches
= [1,1] gewählt wird, wird eine Instanz
des ersten Modells und eine des zweiten Modells zurückgeliefert.
Falls das Modell Symmetrien aufweist, kann es vorkommen, dass
mehrere Instanzen an ähnlichen Positionen im Bild, aber mit
verschiedenen Rotationen gefunden werden. Mit dem Parameter
MaxOverlap
kann bestimmt werden, um welchen Anteil,
ausgedrückt als Zahl zwischen 0 und 1, sich zwei Instanzen höchstens
überlappen dürfen, damit sie als verschieden angesehen werden, und
somit zurückgeliefert werden. Falls sich zwei Instanzen um mehr als
MaxOverlap
überlappen, wird nur die beste gefundene Instanz
zurückgeliefert. Die Berechnung der Überlappung erfolgt anhand der
kleinsten umschließenden Rechtecke beliebiger Orientierung der
Konturen (siehe smallest_rectangle2
). Bei
MaxOverlap
=0 dürfen sich die gefundenen Instanzen nicht
überlappen, bei MaxOverlap
=1 werden alle gefundenen
Instanzen zurückgeliefert.
Falls MaxOverlap
einen Wert
enthält, wird die Überlappung für alle gefundenen Instanzen des
Modells unabhängig von der Art des Modells berechnet. Es werden also
Instanzen verschiedener und gleicher Modelle eliminiert, die sich zu stark
überlappen. Falls hingegen mehrere Werte in
MaxOverlap
übergeben werden, wird die Überlappung nur
innerhalb der gefundenen Instanzen des jeweiligen Typs der Modelle
in ModelIDs
berechnet. Es werden dann nur sich zu stark
überlappende Instanzen gleicher Modelle eliminiert. Modelle
verschiedenen Typs können sich in diesem Modus vollständig
überlappen.
Der Parameter SubPixel
gibt an, ob die Extraktion
subpixelgenau erfolgen soll. Falls SubPixel
auf
'false' gesetzt wird, wird die Lage des Modells nur pixelgenau
bzw. mit der bei create_ncc_model
angegebenen Winkelauflösung
bestimmt. Falls SubPixel
auf 'true' gesetzt wird, werden
sowohl die Position als auch die Rotation subpixelgenau bestimmt. Dabei wird
die Lage des Modells anhand der Score-Funktion interpoliert.
Mit NumLevels
wird die Anzahl der Pyramidenebenen
festgelegt, die bei der Suche verwendet werden soll. Die Anzahl der
Ebenen wird gegebenenfalls auf den bei der Erzeugung mit
create_ncc_model
angegebenen Bereich beschnitten. Falls
NumLevels
als 0 angegeben wird, wird die mit
create_ncc_model
angegebene Anzahl verwendet.
In manchen Fällen kann es sein, dass die Anzahl der Pyramidenebenen,
die beispielsweise automatisch mit create_ncc_model
ermittelt wurde,
zu hoch ist. Dann werden eventuell Instanzen, die eine sehr hohe finale
Bewertung gehabt hätten, bereits auf der höchsten Pyramidenebene
ausgeschlossen und damit nicht gefunden. Anstatt nun MinScore
auf einen sehr geringen Wert zu setzen, um alle Matches zu finden, kann der
Wert von NumLevels
mit get_ncc_model_params
ermittelt
werden und dann ein etwas geringerer Wert in find_ncc_models
genutzt werden. Diese Herangehensweise führt oft zu besseren Ergebnissen
hinsichtlich Geschwindigkeit und Robustheit.
Optional kann NumLevels
einen zweiten Wert enthalten, der die
unterste Pyramidenebene spezifiziert, bis auf welche die Matches
verfolgt werden sollen. Ein Wert von [4,2] bedeutet also,
dass das Matching auf der vierten Pyramidenebene begonnen wird und
auf der zweituntersten Pyramidenebene beendet wird (die unterste
Pyramidenebene hat den Wert 1). Dieser Mechanismus kann dazu
verwendet werden, Laufzeit einzusparen. Allerdings ist in diesem
Modus im Allgemeinen die Genauigkeit der gefundenen Lageparameter
geringer als im Normalfall, in dem die Matches bis auf die unterste
Pyramidenebene verfolgt werden. Falls die unterste zu verwendende
Pyramidenebene zu groß gewählt wird, kann es vorkommen, dass die
gewünschte Genauigkeit nicht mehr erreicht werden kann, oder dass falsche
Instanzen des Modells gefunden werden, weil das Modell auf den oberen
Pyramidenstufen nicht eindeutig genug ist, um eine sichere Selektion der
korrekten Instanz des Modells zu ermöglichen. In diesem Fall muss ein
kleinerer Wert für die unterste zu verwendende Pyramidenebene
gewählt werden.
Falls die unterste Pyramidenebene für jedes Modell
einzeln spezifiziert werden soll, müssen in NumLevels
zweimal die Anzahl von Elementen in ModelIDs
angegeben
werden. Dabei sind die Anzahl der Pyramidenebenen und die untersten
Pyramidenebenen verschränkt anzugeben. Falls z.B. zwei Modelle in
ModelIDs
angegeben sind, die oberste Pyramidenebene für das
erste Modell 5 und für das zweite Modell 4 sein soll und die
unterste Pyramidenebene für das erste Modell 2 und für das zweite 1
sein soll, so ist NumLevels
= [5,2,4,1] zu
wählen. Falls genau zwei Modelle in ModelIDs
angegeben sind,
ergibt sich als Spezialfall, dass, falls die unterste Pyramidenebene
spezifiziert werden soll, die oberste und unterste Pyramidenebene
für beide Modelle explizit spezifiziert werden muss, selbst, wenn
sie gleich sind. Ein Tupel der Länge zwei in NumLevels
wird in diesem Fall nämlich als Spezifikation der obersten
Pyramidenebene für die zwei Modelle interpretiert.
Die Position und Rotation der gefundenen Instanzen der Modelle wird
in Row
, Column
und Angle
zurückgeliefert.
Die Koordinaten Row
und Column
sind die
Koordinaten des Ursprungs des Modells im Suchbild. Normalerweise
ist der Ursprung des Modells der Schwerpunkt der Region des Bildes,
das zur Erzeugung des NCC-Modells mit create_ncc_model
verwendet wurde. Ein anderer Ursprung kann mit
set_ncc_model_origin
festgelegt werden.
Beachten Sie, dass die Koordinaten Row
und Column
nicht exakt mit dem Ursprung des Modells übereinstimmen und daher
nicht direkt verwendet werden sollten. Die Werte sind dafür
optimiert, die Transformationsmatrix zu erzeugen, mit der die
Matching-Ergebnisse für verschiedene Aufgaben verwendet werden
können, z.B. um ROIs für andere Bildverarbeitungsschritte einem
Objekt nachzuführen. Das bei find_ncc_model
angegebene
Beispiel zeigt, wie diese Matrix erzeugt wird und wie man damit das
Modell an der gefundenen Position im Suchbild visualisiert und die
exakten Koordinaten berechnet.
Beachten Sie, dass die Visualisierung aber auch mit der Prozedur dev_display_ncc_matching_results realisiert werden kann.
In Score
wird die Bewertung der gefundenen
Instanzen zurückgegeben. Die Berechnung von Score
ist in
find_ncc_model
beschrieben.
Der gefundene Modelltyp wird in Model
zurückgeliefert. Die
Elemente von Model
sind ein Index in das Tupel
ModelIDs
, d.h. sie können Werte von 0 bis
|ModelIDs
|-1 enthalten. Ein Wert von 0 in einem Element
von Model
entspricht also einer Instanz des ersten in
ModelIDs
übergebenen Modells.
Mittels des Operators set_ncc_model_param
können sie einen
'timeout' für find_ncc_models
angeben. Falls die durch
ModelIDs
referenzierten Modelle unterschiedliche Werte für
'timeout' besitzen, wählt find_ncc_models
den
niedrigsten aus. Wenn find_ncc_models
diesen 'timeout'
erreicht endet er ohne Ergebnis und gibt den Fehlercode 9400 (H_ERR_TIMEOUT)
zurück.
Die Verwendung der Prozedur dev_display_ncc_matching_results
wird zur Darstellung der Resultate formbasierten Matchings
stark empfohlen.
Ein Überblick zu den verschiedenen in HALCON verwendeten 2D Koordinatensystemen ist in der Einleitung zum Kapitel Transformationen / 2D-Transformationen gegeben.
Es sei bemerkt, dass der intern benötigte Speicher mit der Anzahl der verwendeten Threads anwächst.
Image
(input_object) (multichannel-)image(-array) →
object (byte* / uint2*) *erlaubt für Compute Devices
Eingabebild, in dem die Modelle gefunden werden sollen.
ModelIDs
(input_control) ncc_model(-array) →
(handle)
Handle der Modelle.
AngleStart
(input_control) angle.rad(-array) →
(real)
Kleinste auftretende Rotation des Modelle.
Defaultwert: -0.39
Wertevorschläge: -3.14, -1.57, -0.79, -0.39, -0.20, 0.0
AngleExtent
(input_control) angle.rad(-array) →
(real)
Ausdehnung des Winkelbereichs.
Defaultwert: 0.79
Wertevorschläge: 6.29, 3.14, 1.57, 0.79, 0.39, 0.0
Restriktion: AngleExtent >= 0
MinScore
(input_control) real(-array) →
(real)
Minimale Bewertung der zu findenden Instanzen des Modelle.
Defaultwert: 0.8
Wertevorschläge: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typischer Wertebereich: 0
≤
MinScore
≤
1
Minimale Schrittweite: 0.01
Empfohlene Schrittweite: 0.05
NumMatches
(input_control) integer(-array) →
(integer)
Anzahl der zu findenden Instanzen des Modelle (oder 0 für alle Treffer).
Defaultwert: 1
Wertevorschläge: 0, 1, 2, 3, 4, 5, 10, 20
MaxOverlap
(input_control) real(-array) →
(real)
Maximale Überlappung der zu findenden Instanzen des Modelle.
Defaultwert: 0.5
Wertevorschläge: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Typischer Wertebereich: 0
≤
MaxOverlap
≤
1
Minimale Schrittweite: 0.01
Empfohlene Schrittweite: 0.05
SubPixel
(input_control) string(-array) →
(string)
Subpixelgenauigkeit.
Defaultwert: 'true'
Werteliste: 'false' , 'true'
NumLevels
(input_control) integer(-array) →
(integer)
Anzahl der verwendeten Pyramidenebenen (und
unterste zu verwendende Pyramidenebene falls
|NumLevels
| = 2).
Defaultwert: 0
Werteliste: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
Row
(output_control) point.y-array →
(real)
Zeilenkoordinate der gefundenen Instanzen des Modelle.
Column
(output_control) point.x-array →
(real)
Spaltenkoordinate der gefundenen Instanzen des Modelle.
Angle
(output_control) angle.rad-array →
(real)
Rotationswinkel der gefundenen Instanzen des Modelle.
Score
(output_control) real-array →
(real)
Bewertung der gefundenen Instanzen des Modelle.
Model
(output_control) integer-array →
(integer)
Indices der gefundenen Instanzen des Modelle.
read_image (Image, 'pcb_focus/pcb_focus_telecentric_061') gen_rectangle1 (ROI_0, 236, 241, 313, 321) gen_circle (ROI_1, 281, 653, 41) reduce_domain (Image, ROI_0, ImageReduced1) reduce_domain (Image, ROI_1, ImageReduced2) create_ncc_model (ImageReduced1, 'auto', rad(-45), rad(90), 'auto', \ 'use_polarity', ModelID1) create_ncc_model (ImageReduced2, 'auto', rad(-45), rad(90), 'auto', \ 'use_polarity', ModelID2) ModelIDs:=[ModelID1, ModelID2] find_ncc_models (Image, ModelIDs, rad(-45), rad(90), 0.7, [1,1], 0.5, \ 'true', 0, Row, Column, Angle, Score, Model) dev_display_ncc_matching_results (ModelIDs, 'red', Row, Column, \ Angle, Model)
Sind die Parameterwerte korrekt, dann liefert
find_ncc_models
den Wert 2 (H_MSG_TRUE). Das Verhalten bei leerer
Eingabe (keine Eingabebilder vorhanden) lässt sich mittels
set_system('no_object_result',<Result>)
festlegen.
Gegebenenfalls wird eine Fehlerbehandlung durchgeführt.
create_ncc_model
,
read_ncc_model
,
set_ncc_model_origin
find_shape_model
,
find_scaled_shape_model
,
find_aniso_shape_model
,
find_shape_models
,
find_scaled_shape_models
,
find_aniso_shape_models
Matching