create_shape_model
— Vorbereiten eines Formmodells für das Matching.
create_shape_model(Template : : NumLevels, AngleStart, AngleExtent, AngleStep, Optimization, Metric, Contrast, MinContrast : ModelID)
create_shape_model
bereitet ein Muster, das als Bild
Template
übergeben wird, als Formmodell für das Matching
vor. Die ROI des Modells wird als der Definitionsbereich von
Template
übergeben.
Der Ausgabeparameter ModelID
ist ein Handle für dieses Modell, der
in nachfolgenden Aufrufen von find_shape_model
verwendet wird.
Als Ursprung (Referenzpunkt) des Modells wird der Schwerpunkt der
Region des Modellbildes Template
verwendet. Falls ein
anderer Ursprung gewünscht wird, kann dieser mit
set_shape_model_origin
gesetzt werden.
Das Modell wird auf mehreren Pyramidenebenen generiert und im
Speicher abgelegt. Falls eine vollständige Vorabgenerierung des
Modells gewählt wird (siehe unten), wird das Modell in mehreren
Rotationen auf jeder Ebene generiert. Das Modell kann mit
set_shape_model_clutter
um Störparameter erweitert werden.
Die Anzahl der Pyramidenebenen wird mit NumLevels
festgelegt. Sie sollte so groß wie möglich gewählt werden, da
hierdurch das Auffinden des Modells erheblich beschleunigt wird.
Bei der Wahl von NumLevels
ist aber darauf zu achten, dass
das Modell auf der obersten Pyramidenstufe noch erkennbar ist und
genügend viele Punkte besitzt (mindestens vier). Dies kann anhand
der Ausgabe von inspect_shape_model
überprüft werden. Falls
nicht genügend Modellpunkte erzeugt werden, wird die Anzahl der
Pyramidenstufen intern solange reduziert, bis auf der obersten
Pyramidenstufe genügend Modellpunkte vorhanden sind. Falls durch
diese Anpassung ein Modell mit keiner Pyramidenstufe entstehen
würde, d.h. falls schon auf der untersten Pyramidenstufe zu wenige
Modellpunkte vorhanden sind, liefert create_shape_model
eine
Fehlermeldung zurück.
Falls für NumLevels
'auto' (oder 0 für
Rückwärtskompatibilität) übergeben wird, wählt
create_shape_model
die Anzahl der Pyramidenstufen
automatisch. Die automatisch gewählte Anzahl von Pyramidenstufen
kann mit get_shape_model_params
abgefragt werden. In
seltenen Fällen kann es vorkommen, dass create_shape_model
die Anzahl der Pyramidenstufen zu hoch oder zu niedrig
bestimmt. Falls die Anzahl der Pyramidenstufen zu hoch gewählt wird,
kann das dazu führen, dass das Modell im Bild nicht erkannt wird
oder dass sehr niedrige Parameter für MinScore
oder
Greediness
in find_shape_model
selektiert werden müssen,
damit das Modell gefunden wird. Falls die Anzahl der Pyramidenstufen zu
niedrig gewählt wird, kann es zu erhöhten Laufzeiten in
find_shape_model
kommen. In diesen Fällen sollte die Anzahl
der Pyramidenstufen mit Hilfe der Ausgabe von
inspect_shape_model
gewählt werden.
Die Parameter AngleStart
und AngleExtent
legen den
Winkelbereich für die möglichen Rotationen des Modells im Bild fest.
Das Modell kann also mit find_shape_model
nur in diesem
Winkelbereich gefunden werden. Der Parameter AngleStep
gibt die Schrittweite der Winkel in dem gewählten Winkelbereich an.
Falls bei find_shape_model
keine Subpixelgenauigkeit
spezifiziert wird, gibt AngleStep
also die erreichbare
Winkelgenauigkeit an. AngleStep
sollte aufgrund der Größe
des Objektes gewählt werden. Kleinere Modelle besitzen nur eine
kleine Anzahl von verschiedenen diskreten Rotationen im Bild.
Deshalb sollte AngleStep
für kleinere Modelle größer
gewählt werden. Falls AngleExtent
kein ganzzahliges
Vielfaches von AngleStep
ist, wird AngleStep
entsprechend angepasst.
Um sicherzustellen, dass find_shape_model
für Modellinstanzen
ohne Rotation Winkel von exakt 0.0 zurückgibt, wird der
Winkelbereich der möglichen Rotationen folgendermaßen angepasst: Wenn
kein positiver ganzzahliger Wert n existiert, für den
AngleStart
plus n mal AngleStep
genau Null ergibt,
wird AngleStart
um höchstens AngleStep
verringert,
und AngleExtent
wird um AngleStep
vergrößert.
Bei besonders großen Modellen kann es auch sinnvoll sein, die Anzahl
der Modellpunkte durch Setzen des Parameters Optimization
auf einen Wert ungleich 'none' zu setzen. Falls
Optimization
= 'none' , werden alle Modellpunkte
abgespeichert. Ansonsten wird die Anzahl der Punkte entsprechend
dem Parameter Optimization
reduziert. Falls die Anzahl der
Punkte reduziert wird, kann es bei find_shape_model
notwendig werden, den Parameter Greediness
auf einen
kleineren Wert, z.B. 0.7 oder 0.8, zu setzen. Bei kleineren
Modellen bewirkt die Reduktion der Anzahl der Punkte keine
Beschleunigung, da dadurch typischerweise wesentlich mehr
potentielle Instanzen des Modells untersucht werden müssen.
Falls für Optimization
'auto' übergeben wird, wählt
create_shape_model
die Reduktion der Punkte automatisch.
Der Parameter Metric
legt fest, unter welchen Bedingungen
das Muster im Bild noch erkannt wird.
Falls Metric
= 'use_polarity' , muss das Objekt im Bild
dieselben Kontrasteigenschaften aufweisen wie das Modell. Wenn z.B. das
Modell ein helles Objekt auf dunklem Hintergrund ist, wird das
Objekt im Bild nur dann gefunden, wenn es auch heller als der
Hintergrund ist.
Falls Metric
= 'ignore_global_polarity' , wird das
Objekt auch dann im Bild gefunden, wenn sich der Kontrast global umkehrt.
Im obigen Beispiel würde das Objekt also auch dann gefunden, wenn es dunkler
als der Hintergrund ist. Die Laufzeit von find_shape_model
erhöht
sich in diesem Fall geringfügig.
Falls Metric
= 'ignore_local_polarity' , wird das Modell
auch dann gefunden, wenn sich die Kontrastverhältnisse lokal ändern. Dieser
Modus kann z.B. dann sinnvoll sein, wenn das Objekt aus einem Teil
mittleren Grauwerts besteht, auf dem entweder dunkle oder helle
Unterobjekte liegen können. Da sich in diesem Fall die Laufzeit von
find_shape_model
aber wesentlich erhöht, ist es in solchen
Fällen meist sinnvoller, mehrere Modelle mit
create_shape_model
zu erzeugen und mit
find_shape_models
zu suchen.
Die obigen drei Metriken können nur auf einkanalige Bilder angewendet werden. Falls im Modellbild oder in den Suchbildern ein mehrkanaliges Bild übergeben wird, wird stillschweigend nur der erste Kanal des Bildes verwendet.
Falls Metric
= 'ignore_color_polarity' , wird das
Modell auch dann gefunden, falls sich die Farbkontraste lokal ändern
können. Dies ist z.B. der Fall, wenn Teile des Objektes ihre Farbe
ändern können, z.B. von rot auf grün. Dieser Modus ist insbesondere
dann sinnvoll, wenn nicht vorab bekannt ist, in welchen Kanälen das
Objekt zu erkennen ist. Auch hier kann sich die Laufzeit von
find_shape_model
erheblich erhöhen. Die Metrik
'ignore_color_polarity' kann auf Bilder mit einer
beliebigen Anzahl von Kanälen angewendet werden. Falls sie mit
einkanaligen Bildern verwendet wird, hat sie dieselbe Wirkung wie
'ignore_local_polarity' . Es ist zu beachten, dass für
Metric
= 'ignore_color_polarity' die Anzahl der
Kanäle bei der Modellgenerierung mit create_shape_model
und
bei der Suche mit find_shape_model
verschieden sein können.
Dies erlaubt z.B. die Modellgenerierung aus einem einkanaligen
synthetisch generierten Bild. Es ist auch zu beachten, dass die
Kanäle nicht einer spektralen Unterteilung des Lichtes (wie z.B. bei
einem RGB-Bild) entsprechen müssen. Die Kanäle können z.B. auch
durch Beleuchtung des Objektes aus unterschiedlichen Richtungen
entstanden sein.
Der Parameter Contrast
legt fest, welchen Grauwertkontrast
die Punkte des Modells besitzen müssen. Der Kontrast ist ein Maß
für die lokalen Grauwertdifferenzen zwischen dem Objekt und dem
Hintergrund und zwischen verschiedenen Teilen des Objektes.
Contrast
sollte so gewählt werden, dass nur die
signifikanten Merkmale des Musters für das Modell verwendet werden.
Contrast
kann auch ein Tupel mit zwei Werten enthalten. In
diesem Fall wird bei der Segmentierung des Modells ein Verfahren,
das ähnlich zum Hysterese-Schwellwert-Verfahren in
edges_image
ist, eingesetzt. Dabei ist der erste Wert des
Tupels der untere Schwellwert und der zweite Wert der obere
Schwellwert. Für weitere Informationen über das
Hysterese-Schwellwert-Verfahren siehe hysteresis_threshold
.
Optional kann in Contrast
auch ein dritter Wert als letztes
Element des Tupels übergeben werden. Dieser Wert dient zur
Selektion von signifikanten Komponenten des Modells basierend auf
der Größe der Komponenten, d.h. Komponenten, deren Anzahl von
Punkten kleiner ist als diese Mindestgröße, werden unterdrückt.
Dieser Schwellwert wird pro Pyramidenstufe halbiert. Falls eine
Unterdrückung von kleinen Modellkomponenten gewünscht ist, aber
keine Hysterese-Schwellwert-Operation, müssen dennoch drei Werte in
Contrast
übergeben werden, von denen die ersten zwei auf
denselben Wert gesetzt werden. Die Wirkung von Contrast
kann auch vorab mit inspect_shape_model
überprüft werden.
Wird Contrast
auf 'auto' gesetzt, dann bestimmt
create_shape_model
die beschriebenen drei Werte automatisch.
Es besteht die Möglichkeit, nur den Kontrast
('auto_contrast' ), die Hysterese-Schwellwerte
('auto_contrast_hyst' ) oder die Mindestgröße
('auto_min_size' ) automatisch bestimmen zu lassen.
Die übrigen, nicht automatisch zu bestimmenden Größen, können dann
zusätzlich als Tupel übergeben werden. Dabei sind auch Kombinationen
zulässig: Wird z.B. ['auto_contrast','auto_min_size']
übergeben, wird sowohl der Kontrast als auch die Mindestgröße
bestimmt. Bei ['auto_min_size',20,30 ] wird die Mindestgröße
automatisch ermittelt, während die Hysterese-Schwellen auf
20 und 30 gesetzt werden, etc. In bestimmten
Fällen kann es vorkommen, dass die automatische Bestimmung der
Kontrast-Schwellwerte nicht zum gewünschten Ergebnis führt. So ist
eine manuelle Parameterwahl zu bevorzugen, wenn anwendungsbedingt
bestimmte Modellkomponenten ausgeschlossen oder ins Modell
integriert werden sollen oder wenn das Objekt mehrere
unterschiedliche Kontraststufen umfasst. Daher ist es sinnvoll, die
Kontrastwerte vor der Modellgenerierung mit
determine_shape_model_params
automatisch zu ermitteln und
das Ergebnis mit inspect_shape_model
zu überprüfen. Es ist zu
beachten, dass MinContrast
die Bestimmung
der Kontrast-Schwellwerte beeinflusst, und daher auch die Schätzung
der Mindestgröße.
Mit MinContrast
wird festgelegt, welchen Grauwertkontrast
das Modell später bei der Erkennung mit find_shape_model
im
Bild mindestens besitzen muss. Mit anderen Worten stellt dieser
Parameter somit eine Abgrenzung des Musters von Rauschen im Bild
dar. Eine gute Wahl ist deshalb der Bereich von Grauwertänderungen,
der durch das Rauschen im Bild verursacht wird. Falls die Grauwerte
z.B. in einem Bereich von 10 Graustufen durch Rauschen schwanken,
sollte MinContrast
auf 10 gesetzt werden. Falls
mehrkanalige Bilder für das Modell und für die Suchbilder verwendet
werden, und falls der Parameter Metric
auf
'ignore_color_polarity' gesetzt wird (siehe oben), muss
das Rauschen in einem Kanal noch mit der Wurzel der Anzahl der
Kanäle multipliziert werden, um MinContrast
zu bestimmen.
Falls die Grauwerte in einem Kanal z.B. in einem Bereich von 10
Graustufen schwanken, sollte MinContrast
bei einem
dreikanaligen Bild auf 17 gesetzt werden. Offensichtlich muss
MinContrast
kleiner als Contrast
sein. Falls das
Modell später in sehr kontrastarmen Bildern erkannt werden soll,
muss MinContrast
entsprechend klein gewählt werden. Falls
das Modell mit erheblichen Verdeckungen erkannt werden soll, sollte
MinContrast
etwas größer als der Grauwertbereich, der durch
das Rauschen verursacht wird, gewählt werden, um eine robuste und
genaue Lageschätzung des verdeckten Modells zu gewährleisten.
Wird MinContrast
auf 'auto' gesetzt, wählt
create_shape_model
den Mindestkontrast basierend auf dem
Rauschen im Modellbild automatisch. Eine automatische Bestimmung
ergibt demzufolge nur Sinn, wenn das bei der Erkennung zu erwartende
Bildrauschen dem Rauschen im Modellbild entspricht. Außerdem kann es
in manchen Fällen sinnvoll sein, den automatisch ermittelten Wert zu
erhöhen, um eine höhere Robustheit gegenüber Verdeckungen zu
erzielen (siehe oben). Der automatisch bestimmte Mindestkontrast
kann mit get_shape_model_params
abgefragt werden.
Optional kann in Optimization
ein zweiter Wert übergeben
werden. Dieser Wert legt fest, ob das Modell vollständig vorab
generiert wird oder nicht. Der zweite Wert von
Optimization
ist hierzu auf 'pregeneration' oder
'no_pregeneration' zu setzen. Falls der zweite Wert nicht
angegeben wird, wird der mit
set_system('pregenerate_shape_models',...)
eingestellte
Modus verwendet. Mit der Standardeinstellung
('pregenerate_shape_models' = 'false' ) wird das
Modell nicht vollständig vorab generiert. Die vollständige
Vorabgenerierung des Modells führt im Normalfall zu leicht
geringeren Laufzeiten in find_shape_model
, da das Modell
nicht zur Laufzeit transformiert werden muss. Allerdings sind in
diesem Fall der Speicherbedarf und die Zeit, die zur Modellerzeugung
benötigt wird, wesentlich höher. Zu beachten ist auch, dass in den
zwei Modi nicht dieselben Ergebnisse erwartet werden können, da
intern bei der Transformation zur Laufzeit notwendigerweise andere
Daten für die transformierten Modelle entstehen, als bei der
Vorabgenerierung. Falls das Modell nicht vorab generiert wird,
werden z.B. in find_shape_model
typischerweise leicht
niedrigere Bewertungen (Scores) zurückgeliefert, so dass es unter
Umständen notwendig sein kann, einen niedrigeren Wert für MinScore
als bei vollständiger Vorabgenerierung zu verwenden. Außerdem
können sich die durch Interpolation gewonnenen Subpixelpositionen
geringfügig unterscheiden. Falls höchste Genauigkeit gewünscht
wird, sollte die Lage des Modells mittels Ausgleichsrechnung
(Least-Squares Adjustment) bestimmt werden.
Falls eine vollständige Vorabgenerierung des Modells gewählt wird,
wird das Modell in dem gewählten Winkelbereich vorab
generiert und im Speicher abgelegt. Der Speicherbedarf zur
Speicherung des Modells ist also proportional zur Anzahl der
Winkelschritte und zur Anzahl der Punkte im Modell. Wenn also
AngleStep
zu klein bzw. AngleExtent
zu groß
gewählt wird, kann es vorkommen, dass das Modell nicht mehr in den
(virtuellen) Speicher passt. In diesem Fall muss entweder
AngleStep
größer oder AngleExtent
kleiner gewählt
werden. In jedem Fall ist es aus Laufzeitgründen vorteilhaft, wenn
das Modell komplett in den Hauptspeicher passt und somit ein Paging
durch das Betriebssystem vermieden werden kann. Da die Möglichkeit
zur subpixelgenauen Winkelbestimmung in find_shape_model
gegeben ist, kann bei Modellen mit einem Durchmesser von ca. 200
Pixeln AngleStep
>= 1
gewählt werden.
Falls AngleStep
=
'auto' (oder 0 für Rückwärtskompatibilität) übergeben
wird, wählt create_shape_model
automatisch eine Schrittweite
basierend auf der Größe des Modells aus. Die automatisch gewählte
Schrittweite kann mit get_shape_model_params
abgefragt
werden.
Falls eine vollständige Vorabgenerierung des Modells nicht gewählt
wird, wird das Modell nur in einer Referenzlage auf jeder Ebene
erzeugt. In diesem Fall muss das Modell zur Laufzeit in
find_shape_model
auf die verschiedenen Winkel transformiert
werden. Dadurch kann es vorkommen, dass das Auffinden des Modells
etwas mehr Zeit benötigt.
Es ist zu beachten, dass vorabgenerierte Modelle für eine spezifische Bildgröße bestimmt sind. Aus Laufzeitgründen ist die Verwendung von Bildern mit verschiedenen Größen während der Suche mit dem gleichen Modell nicht parallel möglich. In diesem Fall müssen Kopien des gleichen Modells verwendet werden. Anderenfalls kann das Programm abstürzen.
Dieser Operator liefert ein Handle zurück. Es ist zu beachten, dass der Zustand einer Instanz dieses Handletyps durch bestimmte Operatoren geändert werden kann, obwohl das Handle als Eingabeparameter in diesen Operatoren verwendet wird.
Template
(input_object) (multichannel-)image →
object (byte / uint2)
Eingabebild, dessen Definitionsbereich zum Aufbau des Modells verwendet wird.
NumLevels
(input_control) integer →
(integer / string)
Maximale Anzahl von Pyramidenebenen.
Defaultwert: 'auto'
Werteliste: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 'auto'
AngleStart
(input_control) angle.rad →
(real)
Kleinste auftretende Rotation des Musters.
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
Restriktion: AngleExtent >= 0
AngleStep
(input_control) angle.rad →
(real / string)
Schrittweite der Winkel (Auflösung).
Defaultwert: 'auto'
Wertevorschläge: 'auto' , 0.0175, 0.0349, 0.0524, 0.0698, 0.0873
Restriktion: AngleStep >= 0 && AngleStep <= pi / 16
Optimization
(input_control) string(-array) →
(string)
Art der Optimierung und optional Methode der Modellgenerierung.
Defaultwert: 'auto'
Werteliste: 'auto' , 'no_pregeneration' , 'none' , 'point_reduction_high' , 'point_reduction_low' , 'point_reduction_medium' , 'pregeneration'
Metric
(input_control) string →
(string)
Art der zum Matchen verwendeten Metrik.
Defaultwert: 'use_polarity'
Werteliste: 'ignore_color_polarity' , 'ignore_global_polarity' , 'ignore_local_polarity' , 'use_polarity'
Contrast
(input_control) number(-array) →
(integer / string)
Schwellwert bzw. Hystereseschwellwerte für den Kontrast des Objektes im Musterbild und optional Mindestgröße der Objektteile.
Defaultwert: 'auto'
Wertevorschläge: 'auto' , 'auto_contrast' , 'auto_contrast_hyst' , 'auto_min_size' , 10, 20, 30, 40, 60, 80, 100, 120, 140, 160
MinContrast
(input_control) number →
(integer / string)
Minimaler Kontrast des Objektes in den Suchbildern.
Defaultwert: 'auto'
Wertevorschläge: 'auto' , 1, 2, 3, 5, 7, 10, 20, 30, 40
Restriktion: MinContrast < Contrast
ModelID
(output_control) shape_model →
(handle)
Handle des Modells.
Sind die Parameterwerte korrekt, dann liefert
create_shape_model
den Wert 2 (H_MSG_TRUE). Gegebenenfalls wird eine
Fehlerbehandlung durchgeführt. Wenn die Parameter
NumLevels
und Contrast
so gewählt worden sind,
dass das Modell zu wenige Punkte besitzt, wird die Fehlermeldung
8510 zurückgeliefert.
draw_region
,
reduce_domain
,
threshold
find_shape_model
,
find_shape_models
,
get_shape_model_params
,
clear_shape_model
,
write_shape_model
,
set_shape_model_origin
,
set_shape_model_clutter
create_scaled_shape_model
,
create_aniso_shape_model
Matching