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 hereby 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 runtime specific parameter 'gpu' of the
model is not read from file. Instead it is initialized with its default
value (see get_dl_model_param).
For further explanations to 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 to train 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 pixles, 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 pixles, 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 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, but requires a minimum 'image_width' and 'image_height' of 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 increase 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, but requires a minimum 'image_width' and 'image_height' of 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, but requires a minimum 'image_width' and 'image_height' of 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.
As the neural network 'pretrained_dl_classifier_enhanced.hdl', this classifier is suited for more complex tasks. But its structure differs, bringing the advantage of making the training more stable and being 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, but a minimum 'image_width' and 'image_height' of 32 pixels is recommended. 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 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.5 of the ONNX specification is supported.
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 set the type of
such a model to 'classification'.
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''AveragePool':For 'pads', only values that correspond to no padding or padding equal to half the kernel size are supported. 'count_include_pad' must be 0.
'BatchNormalization''Concat':The value for 'axis' must be 1.
'Conv':The values for 'dilations', 'kernel_shape', and 'dilations' must be the same for the width and the height dimension. For 'pads', only values that correspond to no padding or padding equal to half the kernel size are supported.
'Dropout''Gemm':The dimension K must be 1.
'GlobalAveragePool''GlobalMaxPool''LRN''MaxPool':For 'pads', only values that correspond to no padding or padding equal to half the kernel size are supported.
'Relu''Reshape':Only supported if applied to an initializer and its output is used straight as a weight in a layer.
'Softmax':The value for 'axis' must be 1.
'Sum'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_resnet50.hdl', 'pretrained_dl_segmentation_compact.hdl', 'pretrained_dl_segmentation_enhanced.hdl'
File extension: .hdl
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 2 (H_MSG_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