find_shape_model_3d — Suche der besten Matches eines 3D-Formmodells in einem Bild.
find_shape_model_3d(Image : : ShapeModel3DID, MinScore, Greediness, NumLevels, GenParamName, GenParamValue : Pose, CovPose, Score)
find_shape_model_3d findet die besten Matches des
3D-Formmodells ShapeModel3DID im Eingabebild
Image. Das 3D-Formmodell muss zuvor mit
create_shape_model_3d erzeugt oder mit
read_shape_model_3d eingelesen worden sein.
Die 3D-Lage der gefundenen Modellinstanzen wird in Pose
zurückgeliefert.
Sie ist in der Form . Dabei steht
ccs für das Kamerakoordinatensystem und
mcs für das Modellkoordinatensystem (ein 3D Weltkoordinatensystem),
siehe auch Transformationen / Posen und
„Solution Guide III-C - 3D Vision“.
Dies bedeutet, sie beschreibt die Lage des 3D-Objektmodells im
Kamerakoordinatensystem. Zu beachten ist, dass sich die
resultierende Pose nicht auf das in
create_shape_model_3d eingeführte
Referenzkoordinatensystem bezieht, sondern auf das ursprüngliche
durch die CAD-Datei definierte Koordinatensystem des
3D-Objektmodells. Falls eine 3D-Lagen-Verfeinerung durchgeführt
wurde (siehe unten), werden zusätzlich die Genauigkeiten der
sechs 3D-Lagen-Parameter in CovPose zurückgeliefert.
Standardmäßig enthält CovPose die 6
Standardabweichungen der 3D-Lagen-Parameter pro Match. Wurde der
generische Parameter 'cov_pose_mode' (siehe unten) dagegen
auf 'covariances' gesetzt, enthält CovPose die
36 Werte der kompletten 6×6 Kovarianzmatrix
der 6 Posenwerte. Zu beachten ist, dass es dabei nur um eine innere
Genauigkeit der 3D-Lagen-Verfeinerung handelt. Die tatsächliche
Genauigkeit der 3D-Lage kann davon abweichen. Schließlich wird in
Score die Bewertung der gefundenen Instanzen
zurückgegeben. Die Bewertung ist eine Zahl zwischen 0 und 1 und
ist ein ungefähres Maß dafür, welcher Anteil des Modells im
Bild zu sehen ist. Falls z.B. die Hälfte des Modells im Bild
verdeckt ist, kann die Bewertung nicht größer als 0.5 sein.
Image und seine Region:
Der Definitionsbereich des Bildes Image gibt den
Suchbereich für den Referenzpunkt des 3D-Objektmodells an.
MinScore:
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. Zu beachten ist, dass in Bildern mit vielen
Störobjekten oder mit starker Hintergrundtextur der Wert für
MinScore nicht deutlich niedriger als 0.7 gesetzt
werden sollte, da ansonsten falsche Matches gefunden werden könnten.
Greediness:
Der Parameter Greediness bestimmt, wie „gierig“ die Suche
durchgeführt werden soll. Für Greediness=0 wird eine
sichere Suchheuristik verwendet, die das Modell, falls im Bild
vorhanden, immer findet. Allerdings ist die Suche hiermit relativ
zeitaufwendig. Für Greediness=1 wird eine unsicherere
Suchheuristik verwendet, bei der es in seltenen Fällen vorkommen
kann, dass das Modell nicht gefunden wird, obwohl es im Bild
sichtbar ist. Für Greediness=1 wird die maximale
Suchgeschwindigkeit erreicht. In den allermeisten Fällen wird das
3D-Formmodell für Greediness=0.9 immer sicher gefunden.
NumLevels:
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_shape_model_3d angegebenen Bereich beschnitten.
Falls NumLevels als 0 angegeben wird, wird die mit
create_shape_model_3d angegebene Anzahl verwendet. 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, um Laufzeit einzusparen. 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.
GenParamName und GenParamValue:
Zusätzlich zu den oben beschriebenen Parametern gibt es generische
Parameter, die optional angegeben werden können, um das Matching zu
beeinflussen. Für die meisten Anwendungen müssen diese Parameter
nicht spezifiziert werden, sondern können mit den Defaultwerten
übernommen werden. Fall erwünscht, können die generischen Parameter
und deren Werte in GenParamName und
GenParamValue übergeben werden. Die folgenden Werte für
GenParamName sind möglich:
Für den Fall, dass der Pose-Bereich, in dem das Modell gesucht
werden soll, kleiner ist als der Pose-Bereich, der bei der
Modellgenerierung mit create_shape_model_3d angegeben
wurde, kann der Pose-Bereich mit den folgenden Parametern
eingeschränkt werden. Falls die Werte außerhalb des Pose-Bereichs
des Modell liegen, werden diese automatisch auf den Pose-Bereich
des Modells beschnitten.
Setzt die kleinste geographische Länge des Pose-Bereichs.
Wertevorschläge: 'rad(-45)', 'rad(-30)', 'rad(-15)'
Defaultwert: 'rad(-180)'
Setzt die größte geographische Länge des Pose-Bereichs.
Wertevorschläge: 'rad(15)', 'rad(30)', 'rad(45)'
Defaultwert: 'rad(180)'
Setzt die kleinste geographische Breite des Pose-Bereichs.
Wertevorschläge: 'rad(-45)', 'rad(-30)', 'rad(-15)'
Defaultwert: 'rad(-90)'
Setzt die größte geographische Breite des Pose-Bereichs.
Wertevorschläge: 'rad(15)', 'rad(30)', 'rad(45)'
Defaultwert: 'rad(90)'
Setzt den kleinsten Kamerarollwinkel des Pose-Bereichs.
Wertevorschläge: 'rad(-45)', 'rad(-30)', 'rad(-15)'
Defaultwert: 'rad(-180)'
Setzt den größten Kamerarollwinkel des Pose-Bereichs
Wertevorschläge: 'rad(15)', 'rad(30)', 'rad(45)'
Defaultwert: 'rad(180)'
Setzt den kleinsten Kamera-Objekt-Abstand des Pose-Bereichs.
Wertevorschläge: 0.05, 0.1, 0.5, 1.0
Defaultwert: 0
Setzt den größten Kamera-Objekt-Abstand des Pose-Bereichs.
Wertevorschläge: 0.05, 0.1, 0.5, 1.0
Defaultwert:
Weitere generische Parameter, die nicht den Pose-Bereich betreffen, können wie folgt angegeben werden:
Mit diesem Parameter kann angegeben werden, wie viele Instanzen
des Modells im Bild höchstens gefunden werden sollen. Falls
mehr als die angegebene Anzahl Instanzen eine Bewertung größer
als MinScore erreichen, werden nur die besten
'num_matches' Instanzen zurückgeliefert. Falls weniger
als 'num_matches' Instanzen gefunden werden, werden nur
diese Instanzen zurückgeliefert, d.h. der Parameter
MinScore hat Vorrang vor 'num_matches'. Wird
für 'num_matches' der Wert 0 übergeben, werden
alle Matches, die das Score-Kriterium erfüllen zurückgegeben. Zu
beachten ist, dass je mehr Instanzen gefunden werden sollen,
desto langsamer wird das Matching sein.
Wertevorschläge: 0, 1, 2, 3
Defaultwert: 1
Es kann vorkommen, dass mehrere Instanzen an ähnlichen
Positionen im Bild, aber mit verschiedenen Posen gefunden
werden. Mit dem Parameter 'max_overlap' 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
'max_overlap' ü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).
Wurde in create_shape_model_3d für
'lowest_model_level' ein Wert größer als 1
übergeben, basiert die Berechnung anstatt auf den Konturen
auf dem kleinsten umschließenden Rechteck der Projektion des kleinsten
umschließenden achsenparallelen Quaders des 3D-Objektmodells.
Da in diesem Fall die Überlappung überschätzt werden kann, ist es
in manchen Fällen nötig, einen größeren Wert für
'max_overlap' zu übergeben.
Bei 'max_overlap'=0 dürfen sich die gefundenen
Instanzen nicht überlappen, bei 'max_overlap'=1
werden alle gefundenen Instanzen zurückgeliefert.
Wertevorschläge: 0.0, 0.2, 0.4, 0.6, 0.8, 1.0
Defaultwert: 0.5
Dieser Parameter
gibt an, ob die Posen der gefundenen Instanzen verfeinert werden
sollen. Falls für 'pose_refinement' 'none'
gewählt wird, wird die Pose des Modells nur mit einer
eingeschränkten Genauigkeit bestimmt. In diesem Fall hängt die
Genauigkeit von verschiedenen Abtastschrittweiten ab, die
während der Suche verwendet werden. Daher lässt sich die damit
erzielbare Genauigkeit nur schlecht abschätzen. Aus diesem Grund
sollte für 'pose_refinement' nur dann 'none'
gewählt werden, wenn es in erster Linie auf die Geschwindigkeit
ankommt und eine Näherungspose ausreichend ist. In allen
anderen Fällen sollte die Pose durch Ausgleichsrechnung, d.h.,
durch Minimierung der Abstände der Modellpunkte und der
zugehörigen Bildpunkte (Least-Squares Adjustment), bestimmt
werden. Um eine möglichst hohe Genauigkeit zu erzielen, wird die
Pose-Verfeinerung direkt in 3D durchgeführt. Daher kostet dieser
Modus auch zusätzliche Rechenzeit.
Ist die Systemvariable (siehe set_system)
'opengl_hidden_surface_removal_enable' auf 'true'
gesetzt (Standard, sofern es verfügbar ist) und wurde das Modell
mit 'fast_pose_refinement' auf 'false' gesetzt
erzeugt, wird die Modellprojektion für die Pose-Verfeinerung auf
der Grafikkarte durchgeführt.
Abhängig von der verwendeten Grafikkarte ist dies signifikant
schneller als die analytische Projektion.
Es ist zu beachten, dass die Ergebnisse der OpenGL Projektion
leicht verschieden zu denen der analytischen Projektion sind.
Mit den verschiedenen Modi ('least_squares',
'least_squares_high' und 'least_squares_very_high')
kann dabei die Genauigkeit festgelegt werden, mit der der
minimale Abstand gesucht wird. Je höher die Genauigkeit
gewählt wird, desto länger dauert allerdings auch die
Pose-Verfeinerung. Im Normalfall sollte 'pose_refinement'
auf 'least_squares_high' gesetzt werden, da sich so
der optimale Kompromiss zwischen Laufzeit und Genauigkeit
ergibt. Zu beachten ist, dass die Pose-Verfeinerung durch die
Wahl von 'fast_pose_refinement' für den Parameter
GenParamName des Operators create_shape_model_3d
beschleunigt werden kann.
Werteliste: 'none', 'least_squares', 'least_squares_high', 'least_squares_very_high'
Defaultwert: 'least_squares_high'
Dieser Parameter
gibt an, ob der Score der Matches nach der Pose-Verfeinerung neu
berechnet wird. Wird für 'recompute_score'
'false' gewählt, wird der Score zurückgegeben, der vor
der Pose-Verfeinerung errechnet wurde. In manchen Fällen ändert
sich die Objekt-Pose durch die Pose-Verfeinerung allerdings um
mehr als nur ein Pixel im Bild. Folglich beschreibt der
ursprüngliche Score unter Umständen den verfeinerten Match nicht
mehr angemessen. Dies kann dazu führen, dass falsche Matches
einen relativ hohen Score erhalten oder dass perfekte Matches
einen relativ geringen Score erhalten. Um einen
aussagekräftigeren Score zu erhalten, kann der Score nach der
Pose-Verfeinerung neu berechnet werden indem der Parameter
'recompute_score' auf 'true' gesetzt wird. Zu
beachten ist, dass sich dadurch die Reihenfolge der
zurückgegebenen Matches ändern kann. Außerdem kann sich auch
die Auswahl der zurückgegebenen Matches ändern. Des Weiteren
ist zu beachten, dass die Neuberechnung der Score-Werte
zusätzliche Rechenzeit beansprucht. Die zusätzliche Rechenzeit
kann durch das Setzen des Parameters
'fast_pose_refinement' des Operators
create_shape_model_3d auf 'true' reduziert
werden.
Werteliste: 'false', 'true'
Defaultwert: 'false'
Dieser Parameter wirkt sich nur dann aus, wenn für 'pose_refinement' ein anderer Wert als 'none' gewählt wird, also eine Ausgleichsrechnung durchgeführt wird. Dann kann es in einigen Fällen sinnvoll sein, während der Ausgleichsrechnung eine robuste Ausreißerunterdrückung anzuwenden. Dies ist insbesondere dann hilfreich, wenn im Bild ein hoher Grad an Störobjekten vorhanden ist, die verhindern, dass die Ausgleichsrechnung die optimale Pose findet. In diesem Fall sollte 'outlier_suppression' entweder auf 'medium' (eliminiert eine mittlere Anzahl an Ausreißern) oder auf 'high' (eliminiert eine hohe Anzahl an Ausreißern) gesetzt werden. Für die meisten Anwendungen ist jedoch keine Ausreißerunterdrückung notwendig, d.h. 'pose_refinement' kann auf 'none' gesetzt werden. Zu beachten ist auch, dass eine aktivierte Ausreißerunterdrückung mit einer deutlich längeren Rechenzeit verbunden ist.
Werteliste: 'none', 'medium', 'high'
Defaultwert: 'none'
Dieser Parameter
wirkt sich nur dann aus, wenn für 'pose_refinement' ein
anderer Wert als 'none' gewählt wird, also eine
Ausgleichsrechnung durchgeführt wird. 'cov_pose_mode'
legt fest, in welcher Form die Genauigkeiten CovPose
der in der Ausgleichsrechnung berechneten Pose-Parameter
zurückgegeben werden. Wird für 'cov_pose_mode'
'standard_deviations' übergeben, so werden für die 6
Pose-Parameter eines Matches deren 6 Standardabweichungen
zurückgegeben. Wird für 'cov_pose_mode' dagegen
'covariances' gewählt, enthält CovPose pro
Match die 36 Werte der kompletten 6×6
Kovarianzmatrix der 6 Posenwerte.
Werteliste: 'standard_deviations', 'covariances'
Defaultwert: 'standard_deviations'
Im Normalfall wird das Modell 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.
Außerdem kann es sein, dass das Modell, wenn es in einer der
Pyramidenebenen den Bildrand berührt, ebenfalls nicht gefunden wird,
auch wenn es im ursprünglichen Bild vollständig enthalten ist. Als
Daumenregel gilt hier, dass das Modell dann nicht gefunden werden
könnte, wenn seine Distanz zum Bildrand unter
fällt.
Dieses Verhalten kann durch
das Setzen von 'border_model' auf 'true'
dahingehend verändert werden, dass auch Modelle gefunden werden,
die aus dem Bild herausragen, falls sie eine Bewertung größer
als MinScore erreichen. Dabei werden Punkte außerhalb
des Bildes als verdeckt angesehen, d.h. sie verringern die
Bewertung. Es ist zu beachten, dass dieser Modus die Laufzeit
der Suche erhöht. Es ist weiter zu beachten, dass in seltenen
Fällen, die typischerweise nur in künstlichen Bildern auftreten,
auch dann kein Modell gefunden wird, wenn das Modell in einer
Pyramidenebene die reduzierte Bilddomäne berührt. In diesem Fall
kann es helfen, die Region der Domäne um
, z.B., mit
dilation_circle zu vergrößern.
Werteliste: 'false', 'true'
Defaultwert: 'false'
Image (input_object) (multichannel-)image → object (byte / uint2)
Eingabebild, in dem das Modell gefunden werden soll.
ShapeModel3DID (input_control) shape_model_3d → (handle)
Handle des 3D-Formmodells.
MinScore (input_control) real → (real)
Minimale Bewertung der zu findenden Instanzen des Modells.
Default: 0.7
Wertevorschläge: 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Wertebereich:
0
≤
MinScore
≤
1
Minimale Schrittweite: 0.01
Empfohlene Schrittweite: 0.05
Greediness (input_control) real → (real)
„Gierigkeit“ der Suchheuristik (0: sicher aber langsam; 1: schnell aber Matches können „übersehen“ werden).
Default: 0.9
Wertevorschläge: 0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0
Wertebereich:
0
≤
Greediness
≤
1
Minimale Schrittweite: 0.01
Empfohlene Schrittweite: 0.05
NumLevels (input_control) integer-array → (integer)
Anzahl der verwendeten Pyramidenebenen (und
unterste zu verwendende Pyramidenebene falls
|NumLevels| = 2).
Default: 0
Werteliste: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
GenParamName (input_control) attribute.name-array → (string)
Namen von (optionalen) Parametern für die Steuerung des Verhaltens des Operators.
Default: []
Werteliste: 'border_model', 'cam_roll_max', 'cam_roll_min', 'cov_pose_mode', 'dist_max', 'dist_min', 'latitude_max', 'latitude_min', 'longitude_max', 'longitude_min', 'max_overlap', 'num_matches', 'outlier_suppression', 'pose_refinement', 'recompute_score'
GenParamValue (input_control) attribute.name-array → (integer / real / string)
Die zu den optionalen generischen Parametern gehörenden Werte.
Default: []
Wertevorschläge: -0.78, -0.35, -0.17, 0.0, 0.17, 0.35, 0.78, 0.1, 0.2, 0.5, 'none', 'false', 'true', 'least_squares', 'least_squares_high', 'least_squares_very_high', 'standard_deviations', 'covariances', 'medium', 'high'
Pose (output_control) pose(-array) → (real / integer)
3D-Lage des 3D-Formmodells.
CovPose (output_control) real-array → (real)
6 Standardabweichungen bzw. 36 Kovarianzen der Poseparameter.
Score (output_control) real-array → (real)
Bewertung der gefundenen Instanzen des 3D-Formmodells.
read_object_model_3d (DXFModelFileName, 'm', [], [], ObjectModel3D, \
DxfStatus)
CamParam := ['area_scan_division',0.01221,2791,7.3958e-6,7.4e-6,\
308.21,245.92,640,480]
create_shape_model_3d (ObjectModel3D, CamParam, 0, 0, 0, 'gba', \
-rad(20), rad(20), -rad(20), rad(20), 0, \
rad(360), 0.15, 0.2, 10, [], [], ShapeModel3DID)
grab_image_async (Image, AcqHandle, -1)
find_shape_model_3d (Image, ShapeModel3DID, 0.6, 0.9, 0, [], [], \
Pose, CovPose, Score)
project_shape_model_3d (ModelContours, ShapeModel3DID, CamParam, \
Pose, 'true', rad(30))
Sind die Parameterwerte korrekt, dann liefert
find_shape_model_3d 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.
Wurde bei der Modellgenerierung mit find_shape_model_3d
für 'metric' der Wert 'ignore_part_polarity'
gewählt und in Image ein mehrkanaliges Bild übergeben,
wird die Fehlermeldung 3359 zurückgegeben.
create_shape_model_3d,
read_shape_model_3d
convert_point_3d_cart_to_spher,
convert_point_3d_spher_to_cart,
create_cam_pose_look_at_point,
trans_pose_shape_model_3d
3D Metrology