read_dl_model — Read a deep learning model from a file.
read_dl_model( : : FileName : DLModelHandle)
The operator read_dl_model reads a deep learning model.
Such models have to be in the HALCON format or in the ONNX format
(see the reference below). Restrictions apply to the latter.
As a result, the handle DLModelHandle is returned.
The model is loaded from the file FileName.
This file is thereby searched in the directory $HALCONROOT/dl/
as well as in the currently used directory.
The default HALCON file extension for deep learning networks is
'.hdl'.
Please note that the values of runtime specific parameters are not written
to file, see write_dl_model.
As a consequence, when reading a model, these parameters are initialized
with their default value, see get_dl_model_param.
For further explanations on deep learning models in HALCON, see the chapter Deep Learning / Model.
HALCON provides pretrained neural networks for classification and semantic segmentation. These neural networks are good starting points when training a custom network. They have been pretrained on a large image dataset. For anomaly detection, HALCON provides initial models.
The following networks are provided for anomaly detection:
This neural network is designed to be memory and runtime efficient.
The network expects the images to be of the type 'real'.
Additionally, it requires certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values:
'image_width': 480
'image_height': 480
'image_num_channels': 3
'image_range_min': -2
'image_range_max': 2
The network architecture allows changes concerning the image dimensions, but the sizes 'image_width' and 'image_height' have to be multiples of 32 pixels, resulting in a minimum of 32 pixels.
This neural network is assumed to be better suited for more complex anomaly detection tasks. This comes at the cost of being more time and memory demanding.
The network expects the images to be of the type 'real'.
Additionally, it requires certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values:
'image_width': 480
'image_height': 480
'image_num_channels': 3
'image_range_min': -2
'image_range_max': 2
The network architecture allows changes concerning the image dimensions, but the sizes 'image_width' and 'image_height' have to be multiples of 32 pixels, resulting in a minimum of 32 pixels.
The following pretrained neural networks are provided for classification and usable as backbones for detection:
This neural network is designed for simple classification tasks. It is characterized by its convolution kernels in the first convolution layers, which are larger than those in other networks with comparable classification performance (e.g., 'pretrained_dl_classifier_compact.hdl'). This may be beneficial for feature extraction.
This classifier expects the images to be of the type 'real'.
Additionally, the network is designed for certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values with
which the classifier has been trained:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127
'image_range_max': 128
The network architecture allows changes concerning the image dimensions. 'image_width' and 'image_height' should not be less than 29 pixels. There is no maximum image size, but large image sizes will increase the memory demand and the runtime significantly. Changing the image size will reinitialize the weights of the fully connected layers and therefore makes a retraining necessary.
Note that one can improve the runtime for this network
by fusing the convolution and ReLU layers, see
set_dl_model_param and the parameter
'fuse_conv_relu'.
This neural network is designed to be more memory and runtime efficient.
The classifier expects the images to be of the type 'real'.
Additionally, it requires certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values with
which the classifier has been trained:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127
'image_range_max': 128
This network does not contain any fully connected layer. The network architecture allows changes concerning the image dimensions. 'image_width' and 'image_height' should not be less than 15 pixels.
This neural network has more hidden layers than 'pretrained_dl_classifier_compact.hdl' and is therefore assumed to be better suited for more complex classification tasks. This comes at the cost of being more time and memory demanding.
The classifier expects the images to be of the type 'real'.
Additionally, it requires certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values with
which the classifier has been trained:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127
'image_range_max': 128
The network architecture allows changes concerning the image dimensions. 'image_width' and 'image_height' should not be less than 47 pixels. There is no maximum image size, but large image sizes will increase the memory demand and the runtime significantly. Changing the image size will reinitialize the weights of the fully connected layers and therefore makes a retraining necessary.
This classifier is a small and low-power model, for what reason it is more suitable for mobile and embedded vision applications.
The classifier expects the images to be of the type 'real'.
Additionally, it requires certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values with
which the classifier has been trained:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127
'image_range_max': 128
The network architecture allows changes concerning the image dimensions. 'image_width' and 'image_height' should not be less than 32 pixels. There is no maximum image size, but large image sizes will increase the memory demand and the runtime significantly.
On the GPU, the network architecture can benefit greatly from special optimizations, without which the network can be significantly slower.
As the neural network 'pretrained_dl_classifier_enhanced.hdl', this classifier is suited for more complex tasks. However, due to its special structure, it provides the advantage of making the training more stable and internally more robust.
The classifier expects the images to be of the type 'real'.
Additionally, it requires certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values with
which the classifier has been trained:
'image_width': 224
'image_height': 224
'image_num_channels': 3
'image_range_min': -127
'image_range_max': 128
The network architecture allows changes concerning the image dimensions. 'image_width' and 'image_height' should not be less than 32 pixels. There is no maximum image size, but large image sizes will increase the memory demand and the runtime significantly. Despite the fully connected layer a change of the image size does not lead to a reinitialization of the weights.
The following pretrained neural networks are provided for semantic segmentation:
This neural network is designed and pretrained for edge extraction. As a consequence this model is meant for two class problems with one class for edges and one for background.
This network expects the images to be of the type 'real'.
Additionally, it is designed for certain image properties.
The corresponding values can be retrieved with
get_dl_model_param. Here we list the default values with
which the model has been trained:
'image_width': 512
'image_height': 512
'image_num_channels': 1
'image_range_min': -127
'image_range_max': 128
'num_classes': 2
The network architecture allows changes concerning the image dimensions, but the sizes 'image_width' and 'image_height' have to be multiples of 16 pixels, resulting in a minimum of 16 pixels.
This neural network is designed to handle segmentation tasks with detailed structures and uses only few memory and is runtime efficient.
The network architecture allows changes concerning the image dimensions, but requires a minimum 'image_width' and 'image_height' of 21 pixels.
This neural network has more hidden layers than 'pretrained_dl_segmentation_compact.hdl' and is therefore better suited for segmentation tasks including more complex scenes.
The network architecture allows changes concerning the image dimensions, but requires a minimum 'image_width' and 'image_height' of 47 pixels.
You can read in an ONNX model, but there are some points to consider.
Reading in ONNX models with read_dl_model, some restrictions
apply:
Version 1.8.1 of the ONNX specification is supported. This means only operators until ONNX operator set version (OpSetVersion) 13 are supported. For operators with a higher OpSetVersion there is no guarantee that it can be supported. Further limitations are listed above.
Only 32 bit floating point tensors are supported.
Only models ending with a SoftMax layer are automatically recognized
as classifiers.
All other models are considered as generic model, thus
models of 'type' = 'generic'.
set_dl_model_param can be used to change the model type.
The input graph nodes (images) must be of shape dimension 4: Number of images (='batch_size'), 'num_channels', 'image_height', and 'image_width'.
After reading an ONNX model with read_dl_model, some network
transformations are executed automatically:
Every non-global pooling layer with a resulting
feature map of size 1x1 is converted to a global pooling layer.
Doing so enables resizable input images.
For more information about pooling layer and possible modes of
operation, see the “Solution Guide on Classification”.
Layer pairs consisting of a convolution layer without activation
and a directly connected activation layer with ReLU activation are
fused.
In order to so do, the output of the convolution layer is only used
as input for the activation layer.
As a result a convolution layer with activation mode ReLU is obtained.
For more information about layers and possible modes of operation,
see the “Solution Guide on Classification”.
ONNX models with the following operations can be read by
read_dl_model:
'Add':No restrictions.
'ArgMax':The following restrictions apply:
attribute 'axis': The value must be 1.
attribute 'keepdims': The value must be 1.
attribute 'select_last_index': The value must be 0.
'AveragePool':The following restrictions apply:
attribute 'count_include_pad': The value must be 0.
'BatchNormalization':No restrictions.
'Clip':The following restrictions apply:
attribute 'min': The value must be 0.
attribute 'max': The value must be greater than 0 and less than maximum float number.
'Concat':No restrictions.
'Conv':The following restrictions apply:
attribute 'pads': Padding values greater than or equal to kernel size are not supported.
'Dropout':No restrictions.
'Gemm':The following restrictions apply:
attribute 'alpha': The value must be 1.
attribute 'beta': The value must be 1.
attribute 'transA': The value must be 0.
'GlobalAveragePool':No restrictions.
'GlobalMaxPool':The following restrictions apply:
attribute 'dilations': The value must be 1.
'LeakyRelu':No restrictions.
'LogSoftmax':The following restrictions apply:
attribute 'axis': The value must be 1.
'LRN':No restrictions. Hint: Attribute 'size' has no effect.
'MaxPool':No restrictions.
'ReduceMax':The following restrictions apply:
attribute 'axes': The value must be 1.
attribute 'keepdims': The value must be 1.
'Relu':No restrictions.
'Resize':The following restrictions apply:
attribute 'mode': Only the values 'linear' or 'bilinear' are supported.
attribute 'coordinate_transformation_mode': Only the values 'pytorch_half_pixel' and 'align_corners' are supported.
input tensor 'roi': If values are set they have no effect on the inference.
The attributes 'cubic_coeff_a', 'exclude_outside', 'extrapolation_value', or 'nearest_mode' have no effect.
'Reshape':The following restrictions apply:
Only supported if applied to an initializer and its output is used straight as a weight in a layer.
'Sigmoid':No restrictions.
'Softmax':The following restrictions apply:
attribute 'axis': The value must be 1.
'Sum':No restrictions.
Moreover the ONNX 'metadata_props' field is supported. It is written to
the model parameter 'meta_data'.
This operator returns a handle. Note that the state of an instance of this handle type may be changed by specific operators even though the handle is used as an input parameter by those operators.
FileName (input_control) filename.read → (string)
Filename
Default value: 'pretrained_dl_classifier_compact.hdl'
List of values: 'initial_dl_anomaly_large.hdl', 'initial_dl_anomaly_medium.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_resnet50.hdl', 'pretrained_dl_edge_extractor.hdl', 'pretrained_dl_segmentation_compact.hdl', 'pretrained_dl_segmentation_enhanced.hdl'
File extension: .hdl, .onnx
DLModelHandle (output_control) dl_model → (handle)
Handle of the deep learning model.
If the parameters are valid, the operator read_dl_model
returns the value TRUE. If necessary, an exception is raised.
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/
Deep Learning Inference