read_dl_model — Lesen eines Deep Learning-Modells aus einer Datei.
read_dl_model( : : FileName : DLModelHandle)
Der Operator read_dl_model liest ein Deep Learning-Modell.
Diese Modelle müssen im HALCON Format oder alternativ im
ONNX Format (siehe die Referenz weiter unten) vorliegen.
Im zweiten Fall gelten die unten erwähnten Einschränkungen.
Als Ergebnis wird das Handle DLModelHandle zurückgegeben.
Das Modell wird aus der Datei FileName geladen.
Die Datei wird hierbei sowohl im Verzeichnis $HALCONROOT/dl/, als
auch im aktuell genutzten Verzeichnis gesucht.
Die Standard-Dateiendung eines Deep Learning-basierten Klassifikators ist
'.hdl'.
Zu beachten ist, dass die Werte laufzeitspezifischer Parameter nicht
in der Datei abgespeichert werden, siehe write_dl_model.
Folglich werden diese Parameter beim Einlesen des Modells mit ihrem
Standardwert (siehe get_dl_model_param) initialisiert.
Für weitere Informationen zu Deep Learning-Modellen in HALCON siehe das Kapitel Deep Learning / Modell.
HALCON stellt Neuronale Netzwerke für die Klassifikation und Semantische Segmentierung bereit, welche auf einem großen Datensatz vortrainiert wurden. Diese Neuronalen Netzwerke sind gute Ausgangspunkte, um damit eigene Neuronale Netze für ein individuelles Problem zu trainieren. Für die Anomalieerkennung stellt HALCON initiale Modelle zur Verfügung.
Das folgende Netzwerk steht für die 3D Gripping Point Detection zur Verfügung:
Das Netzwerk erwartet bis zu 5 Bilder vom Typ real:
'image': Intensitätsbild (Grauwertbilder)
'x': X-Bild (Werte müssen von links nach rechts aufsteigend)
'y': Y-Bild (Werte müssen von oben nach unten aufsteigend)
'z': Z-Bild (Werte müssen von dem Sensor nahen zu fernen Punkten aufsteigen; das ist z.B. der Fall wenn die Daten bezüglich des Kamerakoordinatensystems angegeben werden)
'normals': 2D-Mappings
Zusätzlich erfordert das Netzwerk spezifische Bildeigenschaften (für alle genannten
Eingabebilder), welche über get_dl_model_param abgefragt werden können.
Hier werden die Defaultwerte gelistet:
'image_width': 640
'image_height': 480
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen.
Die folgenden Netzwerke stehen für die Anomalieerkennung zur Verfügung:
Dieses Netzwerk hat einen vergleichsweise niedrigeren Speicherverbrauch und geringere Laufzeit als 'initial_dl_anomaly_large.hdl'.
Das Netzwerk erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Netzwerk spezifische Bildeigenschaften,
welche über get_dl_model_param abgefragt werden können.
Hier werden die Defaultwerte gelistet:
'image_width': 480
'image_height': 480
'image_num_channels': 3
'image_range_min': -2
'image_range_max': 2
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen, verlangt aber, dass die Bildbreite 'image_width' und Bildhöhe 'image_height' Vielfache von 32 Pixel sind, woraus sich ein Minimalwert von 32 Pixeln ergibt.
Dieses Netzwerk ist für komplexere Aufgaben in der Regel besser geeignet als 'initial_dl_anomaly_medium.hdl'. Dafür ist es rechen- und speicheraufwändiger.
Das Netzwerk erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Netzwerk spezifische Bildeigenschaften,
welche über get_dl_model_param abgefragt werden können.
Hier werden die Defaultwerte gelistet:
'image_width': 480
'image_height': 480
'image_num_channels': 3
'image_range_min': -2
'image_range_max': 2
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen, verlangt aber, dass die Bildbreite 'image_width' und Bildhöhe 'image_height' Vielfache von 32 Pixel sind, woraus sich ein Minimalwert von 32 Pixeln ergibt.
Die folgenden Netzwerke stehen für die Global Context Anomaly Detection zur Verfügung:
Das Netzwerk erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Netzwerk spezifische Bildeigenschaften,
welche über get_dl_model_param abgefragt werden können.
Hier werden die Defaultwerte gelistet:
'image_width': 256
'image_height': 256
'image_num_channels': 3
'image_range_min': -127.0
'image_range_max': 128.0
Die folgenden vortrainierten Neuronalen Netzwerke stehen für die Klassifikation und als Backbone bei der Objektdetektion zur Verfügung:
Dieses Neuronale Netzwerk ist geeignet für einfache Klassifikationsaufgaben. Es zeichnet sich durch die Faltungskerne der ersten Faltungs-Layer aus, welche größer sind als bei Netzwerken vergleichbarer Klassifikationsleistung (z.B. 'pretrained_dl_classifier_compact.hdl'). Dies kann für das Extrahieren von Merkmalskarten von Vorteil sein.
Der Klassifikator erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Neuronale Netzwerk spezifische
Bildeigenschaften, welche über get_dl_model_param
abgefragt werden können.
Hier werden die Defaultwerte gelistet, mit welchen der Klassifikator
trainiert wurde:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127.0
'image_range_max': 128.0
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen. Bildbreite 'image_width' und Bildhöhe 'image_height' sollten dabei aber 29 Pixel nicht unterschreiten. Durch die Netzwerkarchitektur wird die Bildgröße nach oben hin nicht beschränkt, aber zunehmende Bildgrößen erhöhen den Speicher- und Laufzeitbedarf erheblich. Jede Änderung der Bildgröße führt zu einem Reinitialisieren der Gewichte in den Fully-connected Layern und macht dadurch ein Nachtrainieren notwendig.
Man kann die Laufzeit dieses Netzwerkes beschleunigen, indem man
die Faltungs- und ReLU-Layer miteinander verbindet, siehe
set_dl_model_param und den Parameter
'fuse_conv_relu'.
Dieses Neuronale Netzwerk ist besonders effizient bezüglich des Speicherverbrauchs und der Laufzeit.
Der Klassifikator erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Neuronale Netzwerk spezifische
Bildeigenschaften, welche über get_dl_model_param
abgefragt werden können.
Hier werden die Defaultwerte gelistet, mit welchen der Klassifikator
trainiert wurde:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127.0
'image_range_max': 128.0
Dieses Neuronale Netzwerk enthält keinen Fully-connected Layer. Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen. Bildbreite 'image_width' und Bildhöhe 'image_height' sollten dabei aber 15 Pixel nicht unterschreiten.
Dieses Neuronale Netzwerk hat mehr verborgene Layer als 'pretrained_dl_classifier_compact.hdl' und ist daher für komplexere Klassifikationsaufgaben in der Regel besser geeignet. Dafür ist dieses Netzwerk rechen- und speicheraufwändiger.
Der Klassifikator erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Neuronale Netzwerk spezifische
Bildeigenschaften, welche über get_dl_model_param
abgefragt werden können.
Hier werden die Defaultwerte gelistet, mit welchen der Klassifikator
trainiert wurde:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127.0
'image_range_max': 128.0
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen. Bildbreite 'image_width' und Bildhöhe 'image_height' sollten dabei aber 47 Pixel nicht unterschreiten. Durch die Netzwerkarchitektur wird die Bildgröße nach oben hin nicht beschränkt, aber zunehmende Bildgrößen erhöhen den Speicher- und Laufzeitbedarf erheblich. Jede Änderung der Bildgröße führt zu einem Reinitialisieren der Gewichte in den Fully-connected Layern und macht dadurch ein Nachtrainieren notwendig.
Dieser Klassifikator ist ein kleines, energieeffizientes Modell und daher besser für mobile und embedded Bildverarbeitungsanwendungen geeignet.
Der Klassifikator erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Neuronale Netzwerk spezifische
Bildeigenschaften, welche über get_dl_model_param
abgefragt werden können.
Hier werden die Defaultwerte gelistet, mit welchen der Klassifikator
trainiert wurde:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127.0
'image_range_max': 128.0
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen. Bildbreite 'image_width' und Bildhöhe 'image_height' sollten dabei aber 32 Pixel nicht unterschreiten. Durch die Netzwerkarchitektur wird die Bildgröße nach oben hin nicht beschränkt, aber zunehmende Bildgrößen erhöhen den Speicher- und Laufzeitbedarf erheblich.
Auf der GPU kann die Netzwerkarchitektur stark von speziellen Optimierungen profitieren, ohne welche das Netz deutlich langsamer sein kann.
Wie das Neuronale Netzwerk 'pretrained_dl_classifier_enhanced.hdl' ist dieser Klassifikator für komplexere Aufgaben geeignet. Die spezielle Struktur dieses Klassifikators bringt allerdings den Vorteil mit sich, das Training stabiler zu machen und intern robuster zu sein. Gegenüber dem Neuronalen Netzwerk 'pretrained_dl_classifier_resnet50.hdl', ist es etwas weniger komplex dafür in der Ausführung schneller.
Der Klassifikator erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Neuronale Netzwerk spezifische
Bildeigenschaften, welche über get_dl_model_param
abgefragt werden können.
Hier werden die Defaultwerte gelistet, mit welchen der Klassifikator
trainiert wurde:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127.0
'image_range_max': 128.0
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen. Bildbreite 'image_width' und Bildhöhe 'image_height' sollten dabei aber 32 Pixel nicht unterschreiten. Durch die Netzwerkarchitektur wird die Bildgröße nach oben hin nicht beschränkt, aber zunehmende Bildgrößen erhöhen den Speicher- und Laufzeitbedarf erheblich. Trotz Fully-connected Layer führt eine Änderung der Bildgröße nicht zu einem Reinitialisieren der Gewichte.
Wie das Neuronale Netzwerk 'pretrained_dl_classifier_enhanced.hdl' ist dieser Klassifikator für komplexere Aufgaben geeignet. Die spezielle Struktur dieses Klassifikators bringt allerdings den Vorteil mit sich, das Training stabiler zu machen und intern robuster zu sein.
Der Klassifikator erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Neuronale Netzwerk spezifische
Bildeigenschaften, welche über get_dl_model_param
abgefragt werden können.
Hier werden die Defaultwerte gelistet, mit welchen der Klassifikator
trainiert wurde:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127.0
'image_range_max': 128.0
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen. Bildbreite 'image_width' und Bildhöhe 'image_height' sollten dabei aber 32 Pixel nicht unterschreiten. Durch die Netzwerkarchitektur wird die Bildgröße nach oben hin nicht beschränkt, aber zunehmende Bildgrößen erhöhen den Speicher- und Laufzeitbedarf erheblich. Trotz Fully-connected Layer führt eine Änderung der Bildgröße nicht zu einem Reinitialisieren der Gewichte.
Folgende vortrainierte Netzwerke stehen für die Semantische Segmentierung zur Verfügung:
Dieses Neuronale Netzwerk ist für die Kantenextraktion konzipiert und vortrainiert. Folglich ist das Netz auch primär für Zwei-Klassen-Probleme ausgelegt, einer Klasse Kanten und einer Klasse Hintergrund.
Das Neuronale Netzwerk erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Netzwerk spezifische Bildeigenschaften, welche über
get_dl_model_param abgefragt werden können.
Hier werden die Defaultwerte gelistet, mit welchen das Modell
trainiert wurde:
'image_width': 512
'image_height': 512
'image_num_channels': 1
'image_range_min': -127.0
'image_range_max': 128.0
'num_classes': 2
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen, verlangt aber, dass die Bildbreite 'image_width' und Bildhöhe 'image_height' Vielfache von 16 Pixel sind, woraus sich ein Minimalwert von 16 Pixeln ergibt.
Dieses Neuronale Netzwerk ist besonders für feine Strukturen geeignet und ist effizient bezüglich des Speicherverbrauchs und der Laufzeit.
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen, verlangt aber eine minimale Bildbreite 'image_width' von 21 Pixeln und eine minimale Bildhöhe von 'image_height' 21 Pixeln.
Dieses Neuronale Netzwerk hat mehr verborgene Layer als 'pretrained_dl_segmentation_compact.hdl' und ist daher für Segmentierungsaufgaben in komplexeren Szenarien besser geeignet.
Die Netzwerkarchitektur erlaubt Änderungen der Bilddimensionen, verlangt aber eine minimale Bildbreite 'image_width' von 47 Pixeln und eine minimale Bildhöhe von 'image_height' 47 Pixeln.
Folgende vortrainierte Netzwerke stehen für die Deep OCR zur Verfügung:
Dieses neuronale Netzwerk ist die vortrainierte Erkennungskomponente eines Deep OCR-Modells. Es ist konzipiert um Wörter auf Bildern zu erkennen, welche auf ein einzelnes Wort zugeschnitten sind. Dies ist die Erkennungskomponente von Deep OCR, welche nachtrainiert werden kann.
Das Neuronale Netzwerk erwartet Eingabebilder vom Typ real.
Zusätzlich erfordert das Netzwerk spezifische Bildeigenschaften, welche über
get_dl_model_param abgefragt werden können. Hier werden die
Defaultwerte aufgelistet, mit welchen das Modell trainiert wurde:
'image_width': 120
'image_height': 32
'image_num_channels': 1
'image_range_min': -1.0
'image_range_max': 1.0
Die Netzwerkarchitektur erlaubt Änderungen der Bildbreite 'image_width'. Die Bildhöhe 'image_height' kann nicht verändert werden. Der Parameter 'image_width' ist sehr wichtig. Sein Wert kann verringert oder erhöht werden um sich an die zu erwartenden Wortlängen anzupassen, beispielsweise bedingt durch die durchschnittliche Zeichenbreite. Ein größerer Wert für 'image_width' führt zu erhöhtem Speicher- und Laufzeitbedarf. Die Bildbreite 'image_width' darf nach dem Training geändert werden.
ONNX Modelle können eingelesen werden, aber dabei gibt es gewisse Punkte zu beachten.
Wird ein ONNX Modell eingelesen, gelten folgende Einschränkungen:
Nur Modelle bis zur ONNX operator set version (OpSetVersion) 13 werden unterstützt. Für Operatoren, die eine höhere OpSetVersion besitzen kann keine Unterstützung garantiert werden. Für weitere Limitationen wird auf die ONNX Operatorenauflistung verwiesen.
Nur 32 Bit Gleitkommatensoren werden unterstützt.
Nur Modelle die mit einem SoftMax Layer enden, werden automatisch
als Klassifikator erkannt.
Alle anderen Modelle werden als generisches Modell betrachtet,
d.h., Modelle mit 'type' = 'generic'.
Mit set_dl_model_param kann der Typ eines solchen Modells
geändert werden.
Die Eingabeknoten des Graphen (Bilder) müssen von vierdimensionaler Form sein: Anzahl Bilder (='batch_size'), 'num_channels', 'image_height' und 'image_width'.
Nach dem Einlesen eines ONNX Modells mit read_dl_model werden
folgende Transformationen automatisch durchgeführt:
Jeder nicht globale Pooling-Layer, dessen Ausgabemerkmalskarte die
Dimension 1x1 hat, wird in einen globalen Pooling-Layer verwandelt.
Dies ermöglicht Eingabebilder variabler Größen.
Weitere Informationen zum Pooling-Layer und möglichen Modi befinden
sich im „Solution Guide on Classification“.
Layer Paare bestehend aus einem Faltungs-Layer ohne Aktivierung
und einem direkt verknüpften Activation-Layer mit Aktivierungsmodus
ReLU werden fusioniert.
Um dies zu tun, darf die Ausgabe des Faltungs-Layers nur vom
Activation-Layer als Eingabe verwendet werden.
Daraus entsteht ein Faltungs-Layer mit ReLU-Aktivierung.
Weitere Informationen zu Layern und möglichen Modi befinden
sich im „Solution Guide on Classification“.
Jeder Split-Layer wird in Slice-Layer umgewandelt. Während des Umwandlungsprozesses werden Slice-Layer erzeugt, welche die jeweiligen Datenabschnitte extrahieren, die auch bei der Split-Operation entstehen. Dadurch bleibt die ursprüngliche Funktionalität erhalten, auch wenn sie durch mehrere Slice-Operationen anstatt eines einzelnen Split-Layers dargestellt wird.
ONNX Modelle mit den folgenden Operationen können von
read_dl_model gelesen werden:
'Add':Keine Einschränkungen.
'ArgMax':Es gelten folgende Einschränkungen:
Attribut 'axis': Der Wert muss 1 sein.
Attribut 'keepdims': Der Wert muss 1 sein.
Attribut 'select_last_index': Der Wert muss 0 sein.
'AveragePool':Es gelten folgende Einschränkungen:
Attribut 'count_include_pad': Der Wert muss 0 sein.
'BatchNormalization':Keine Einschränkungen.
'Clip':Es gelten folgende Einschränkungen:
Attribut 'min': Der Wert muss 0 sein.
Attribut 'max': Der Wert muss größer als 0 und kleiner als die maximale float Zahl sein.
'Concat':Keine Einschränkungen.
'Constant':Es gelten folgende Einschränkungen:
Attribut 'sparse_value': Das Attribut wird nicht unterstützt.
Attribut 'value': Alle Einträge des Tensors müssen den gleichen Wert haben.
Attribut 'value_floats': Das Attribut wird nicht unterstützt.
Attribut 'value_ints': Das Attribut wird nicht unterstützt.
Attribut 'value_string': Das Attribut wird nicht unterstützt.
Attribut 'value_strings': Das Attribut wird nicht unterstützt.
'Conv':Es gelten folgende Einschränkungen:
Attribut 'pads': Padding Werte größer oder gleich der Kernel-Größe sind nicht unterstützt.
'DepthToSpace':Es gelten folgende Einschränkungen:
Attribut 'mode': Der Wert muss 'CRD' sein.
'Dropout':Keine Einschränkungen.
'Gemm':Es gelten folgende Einschränkungen:
Attribut 'alpha': Der Wert muss 1 sein.
Attribut 'beta': Der Wert muss 1 sein.
Attribut 'transA': Der Wert muss 0 sein.
'GlobalAveragePool':Keine Einschränkungen.
'GlobalMaxPool':Es gelten folgende Einschränkungen:
Attribut 'dilations': Der Wert muss 1 sein.
'LeakyRelu':Keine Einschränkungen.
'LogSoftmax':Es gelten folgende Einschränkungen:
Attribut 'axis': Der Wert muss 1 sein.
'LRN':Keine Einschränkungen. Hinweis: Attribut 'size' hat keinen Effekt.
'MaxPool':Keine Einschränkungen.
'Mean':Keine Einschränkungen.
'Mul':Keine Einschränkungen.
'ReduceMax':Es gelten folgende Einschränkungen:
Attribut 'axes': Der Wert muss 1 sein.
Attribut 'keepdims': Der Wert muss 1 sein.
'Relu':Keine Einschränkungen.
'Resize':Es gelten folgende Einschränkungen:
Attribut 'mode': Nur die Werte 'linear' oder 'bilinear' sind erlaubt.
Attribut 'coordinate_transformation_mode': Nur die Werte 'pytorch_half_pixel' und 'align_corners' sind erlaubt.
Inputtensor 'roi': Wenn Werte gesetzt sind haben sie keinen Effekt auf die Inferenz.
Die Attribute 'cubic_coeff_a', 'exclude_outside', 'extrapolation_value', oder 'nearest_mode' haben keinen Effekt.
'Reshape':Es gelten folgende Einschränkungen:
Wird nur dann unterstützt wenn es auf einen 'Initializer' angewandt wird und die Ausgabe direkt als Gewicht in einem Layer verwendet wird.
'Sigmoid':Keine Einschränkungen.
'Softmax':Es gelten folgende Einschränkungen:
attribute 'axis': Der Wert muss 1 sein.
'Sub':Keine Einschränkungen.
'Sum':Keine Einschränkungen.
Außerdem wird das ONNX Modellattribut 'metadata_props'
unterstützt. Dieses wird im Modellparameter 'meta_data'
gespeichert.
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.
FileName (input_control) filename.read → (string)
Dateiname
Defaultwert: 'pretrained_dl_classifier_compact.hdl'
Werteliste: 'initial_dl_anomaly_large.hdl', 'initial_dl_anomaly_medium.hdl', 'pretrained_deep_ocr_recognition.hdl', 'pretrained_dl_3d_gripping_point.hdl', 'pretrained_dl_anomaly_global_context.hdl', 'pretrained_dl_classifier_alexnet.hdl', 'pretrained_dl_classifier_compact.hdl', 'pretrained_dl_classifier_enhanced.hdl', 'pretrained_dl_classifier_mobilenet_v2.hdl', 'pretrained_dl_classifier_resnet18.hdl', 'pretrained_dl_classifier_resnet50.hdl', 'pretrained_dl_edge_extractor.hdl', 'pretrained_dl_segmentation_compact.hdl', 'pretrained_dl_segmentation_enhanced.hdl'
Dateiendung: .hdl, .onnx
DLModelHandle (output_control) dl_model → (handle)
Handle des Deep Learning-Modells.
Sind die Parameterwerte korrekt, dann liefert
read_dl_model den Wert 2 (H_MSG_TRUE). Gegebenenfalls wird eine
Fehlerbehandlung durchgeführt.
set_dl_model_param,
get_dl_model_param,
apply_dl_model,
train_dl_model_batch,
train_dl_model_anomaly_dataset
Open Neural Network Exchange (ONNX), https://onnx.ai/
Foundation. Dieser Operator verwendet dynamische Lizensierung (siehe ``Installation Guide''). Welches der folgenden Module benötigt wird hängt von der Anwendung des Operators ab:
3D Metrology, OCR/OCV, Deep Learning Inference