find_ncc_model
— Suche der besten Matches eines NCC-Modells in einem Bild.
find_ncc_model(Image : : ModelID, AngleStart, AngleExtent, MinScore, NumMatches, MaxOverlap, SubPixel, NumLevels : Row, Column, Angle, Score)
find_ncc_model
findet die besten NumMatches
Instanzen des NCC-Modells ModelID
im Eingabebild
Image
. Das Modell muss zuvor mit create_ncc_model
erzeugt oder mit read_ncc_model
eingelesen worden sein.
Die Position und Rotation der gefundenen Instanzen des Modells wird
in Row
, Column
und Angle
zurückgeliefert.
Zusätzlich wird in Score
die Bewertung der gefundenen
Instanzen zurückgegeben.
Nähere Informationen finden Sie in den parameterspezifischen Abschnitten.
Es ist zu beachten, dass die NCC sehr empfindlich gegenüber
Verdeckungen und Störobjekten sowie gegenüber nichtlinearen
Beleuchtungsänderungen im Bild ist. Falls ein Modell selbst bei
Verdeckungen, Störobjekten oder nichtlinearen Beleuchtungsänderungen
gefunden werden soll, sollte die Suche mit dem formbasierten
Matching durchgeführt werden (siehe
z.B. create_shape_model
).
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 hier
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 (siehe unten).
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.
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.
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 das Modell Symmetrien aufweist, kann es vorkommen, dass
mehrere Instanzen an ähnlichen Positionen im Bild, aber mit
verschiedenen Rotationen gefunden werden. Falls das Modell sich
wiederholende Strukturen aufweist, kann es vorkommen, dass mehrere
Instanzen mit gleichen Rotationen an ähnlichen Positionen im Bild
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 des
Definitionsbereiches der Modelle (siehe
smallest_rectangle2
). Bei MaxOverlap
=0 dürfen
sich die gefundenen Instanzen nicht überlappen, bei
MaxOverlap
=1 werden alle gefundenen Instanzen
zurückgeliefert.
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. Dieser Modus kostet
fast keine Rechenzeit und liefert eine hohe Genauigkeit. Im
Normalfall sollte also SubPixel
= 'true' gewählt
werden. Für eine subpixelgenaue Bestimmung der Lage muss das Modell
auf der untersten verwendeten Pyramidenebene einen Abstand von
mindestens 2 Pixel vom Bildrand haben. Wenn die gefundene Instanz
des Modells näher am Bildrand liegt, wird die Lage des Modells nur
pixelgenau bzw. mit der bei create_ncc_model
angegebenen
Winkelauflösung bestimmt, selbst wenn SubPixel
auf
'true' gesetzt ist.
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_model
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.
Die Position und Rotation der gefundenen Instanzen des Modells wird
in Row
, Column
und Angle
zurückgeliefert.
Die Koordinaten Row
und Column
beschreiben die
Position des Ursprungs des Modells im Suchbild. Die Werte sind
allerdings bereits geringfügig angepasst, so dass sie direkt zur
Erstellung einer Transformationsmatrix verwendet werden können, die
für ein Alignment oder die Visualisierung des Modells benötigt
wird. Diese Anpassung der Koordinaten hat mit der Art und Weise zu
tun, in der HALCON ikonische Objekte transformiert, siehe hierzu
affine_trans_pixel
. Das Beispiel weiter unten zeigt, wie die
Transformationsmatrix erzeugt wird und wie man damit die exakten
Koordinaten berechnet.
Beachten Sie, dass die Visualisierung aber auch mit der Prozedur dev_display_ncc_matching_results realisiert werden kann.
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.
In Score
wird die Bewertung der gefundenen
Instanzen zurückgegeben. Die Bewertung ist die normalisierte
Kreuzkorrelation (engl.: normalized cross correlation) zwischen dem
Muster t(r,c) und dem Bild i(r,c):
Hierbei bezeichnet n die Anzahl der Punkte im Muster, R den
Definitionsbereich (ROI) des Musters, den mittleren
Grauwert des Musters
die Varianz der Grauwerte des Musters
den mittleren Grauwert an der Position
(r,c) über alle Punkte im Muster (d.h. die Punkte im Muster sind
um (r,c) verschoben)
und die Varianz der Grauwerte an der
Position (r,c) über alle Punkte im Muster
Die NCC misst, wie gut das Muster und das Bild an einem bestimmten Punkt (r,c) übereinstimmen. Sie nimmt Werte zwischen -1 und 1 an. Je größer der Absolutbetrag der Korrelation ist, desto besser ist die Übereinstimmung zwischen Muster und Bild. Ein Wert von 1 bedeutet, dass die Grauwerte im Bild eine lineare Transformation der Grauwerte im Muster sind: i(r+u,c+v) = a * t(u,v) + b wobei a > 0. Ein Wert von -1 bedeutet, dass die Grauwerte im Bild eine lineare Transformation der Grauwerte im Muster mit a < 0 sind. Das Muster hat in diesem Fall im Bild also genau die umgekehrte Polarität. Aufgrund der obigen Eigenschaft ist die NCC invariant gegenüber linearen Beleuchtungsänderungen.
Die NCC wie oben definiert wird verwendet, falls das Modell mit
Metric
= 'use_polarity' erzeugt wurde. Falls
das Modell mit Metric
= 'ignore_global_polarity'
erzeugt wurde, wird der Absolutbetrag von
ncc(r,c) als Bewertung verwendet.
Mittels des Operators set_ncc_model_param
können sie einen
'timeout' für find_ncc_model
angeben. Wenn
find_ncc_model
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.
find_ncc_model
kann teilweise auf OpenCL Geräten ausgeführt werden,
wenn diese die cl_khr_global_int32_base_atomics OpenCL Erweiterung
unterstützen. Es wird nur die Suche auf der obersten Pyramidenstufe auf dem
OpenCL Gerät durchgeführt, während das Tracking der potentiellen Matches auf
der CPU durchgeführt wird. Wenn die Domäne des Bildes in dem gesucht werden
soll deutlich kleiner ist als die Größe des Bildes, sollte daher
crop_domain
verwendet werden, um die Menge der von dem OpenCL auf das
Host-System zu übertragenden Daten zu reduzieren. Abhängig von einer Vielzahl
von Faktoren kann find_ncc_model
auf OpenCL Geräten sowohl deutlich
schneller, als auch deutlich langsamer laufen. Daher kann man hier keine
generelle Aussage treffen und muss jeweils mit Bildern aus der Anwendung
testen, ob der Einsatz von OpenCL für find_ncc_model
Sinn macht oder
nicht.
Außerdem sei bemerkt, dass der intern benötigte Speicher mit der Anzahl der verwendeten Threads anwächst.
Image
(input_object) singlechannelimage →
object (byte* / uint2*) *erlaubt für Compute Devices
Eingabebild, in dem das Modell gefunden werden soll.
ModelID
(input_control) ncc_model →
(handle)
Handle des Modells.
AngleStart
(input_control) angle.rad →
(real)
Kleinste auftretende Rotation des Modells.
Defaultwert: -0.39
Wertevorschläge: -3.14, -1.57, -0.79, -0.39, -0.20, 0.0
AngleExtent
(input_control) angle.rad →
(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 →
(real)
Minimale Bewertung der zu findenden Instanzen des Modells.
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 →
(integer)
Anzahl der zu findenden Instanzen des Modells (oder 0 für alle Treffer).
Defaultwert: 1
Wertevorschläge: 0, 1, 2, 3, 4, 5, 10, 20
MaxOverlap
(input_control) real →
(real)
Maximale Überlappung der zu findenden Instanzen des Modells.
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 →
(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 Modells.
Column
(output_control) point.x-array →
(real)
Spaltenkoordinate der gefundenen Instanzen des Modells.
Angle
(output_control) angle.rad-array →
(real)
Rotationswinkel der gefundenen Instanzen des Modells.
Score
(output_control) real-array →
(real)
Bewertung der gefundenen Instanzen des Modells.
create_ncc_model (TemplateImage, 'auto', rad(-45), rad(90), 'auto', \ 'use_polarity', ModelID) find_ncc_model (SearchImage, ModelID, rad(-45), rad(90), 0.7, 1, \ 0.5, 'true', 0, Row, Column, Angle, Score) * Create transformation matrix vector_angle_to_rigid (0, 0, 0, Row, Column, Angle, HomMat2D) * Calculate true position of the model origin in the search image affine_trans_pixel (HomMat2D, 0, 0, RowObject, ColumnObject) * display the results dev_display_ncc_matching_results (ModelID, 'red', Row, Column, \ Angle, 0)
Sind die Parameterwerte korrekt, dann liefert find_ncc_model
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