read_dl_modelT_read_dl_modelReadDlModelReadDlModel (Operator)

Name

read_dl_modelT_read_dl_modelReadDlModelReadDlModel — Read a deep learning model from a file.

Signature

read_dl_model( : : FileName : DLModelHandle)

Herror T_read_dl_model(const Htuple FileName, Htuple* DLModelHandle)

void ReadDlModel(const HTuple& FileName, HTuple* DLModelHandle)

void HDlModel::HDlModel(const HString& FileName)

void HDlModel::HDlModel(const char* FileName)

void HDlModel::HDlModel(const wchar_t* FileName)   (Windows only)

void HDlModel::ReadDlModel(const HString& FileName)

void HDlModel::ReadDlModel(const char* FileName)

void HDlModel::ReadDlModel(const wchar_t* FileName)   (Windows only)

static void HOperatorSet.ReadDlModel(HTuple fileName, out HTuple DLModelHandle)

public HDlModel(string fileName)

void HDlModel.ReadDlModel(string fileName)

Description

The operator read_dl_modelread_dl_modelReadDlModelReadDlModelReadDlModel 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 DLModelHandleDLModelHandleDLModelHandleDLModelHandleDLModelHandle is returned.

The model is loaded from the file FileNameFileNameFileNameFileNamefileName. 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'".hdl"".hdl"".hdl"".hdl".

Please note that the runtime specific parameter 'gpu'"gpu""gpu""gpu""gpu" of the model is not read from file. Instead it is initialized with its default value (see get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam).

For further explanations to deep learning models in HALCON, see the chapter Deep Learning / Model.

Reading in a model provided by \Halcon

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.

Models for Anomaly Detection

The following networks are provided for anomaly detection:

'initial_dl_anomaly_medium.hdl'"initial_dl_anomaly_medium.hdl""initial_dl_anomaly_medium.hdl""initial_dl_anomaly_medium.hdl""initial_dl_anomaly_medium.hdl"

This neural network is designed to be memory and runtime efficient.

The network expects the images to be of the type 'real'"real""real""real""real". Additionally, it requires certain image properties. The corresponding values can be retrieved with get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""image_height" have to be multiples of 32 pixles, resulting in a minimum of 32 pixels.

'initial_dl_anomaly_large.hdl'"initial_dl_anomaly_large.hdl""initial_dl_anomaly_large.hdl""initial_dl_anomaly_large.hdl""initial_dl_anomaly_large.hdl"

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'"real""real""real""real". Additionally, it requires certain image properties. The corresponding values can be retrieved with get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""image_height" have to be multiples of 32 pixles, resulting in a minimum of 32 pixels.

Models for Classification

The following pretrained neural networks are provided for classification and usable as backbones for detection:

'pretrained_dl_classifier_alexnet.hdl'"pretrained_dl_classifier_alexnet.hdl""pretrained_dl_classifier_alexnet.hdl""pretrained_dl_classifier_alexnet.hdl""pretrained_dl_classifier_alexnet.hdl":

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'"pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl"). This may be beneficial for feature extraction.

This classifier expects the images to be of the type 'real'"real""real""real""real". Additionally, the network is designed for certain image properties. The corresponding values can be retrieved with get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""image_height" should not be less than 29 pixels. 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_paramset_dl_model_paramSetDlModelParamSetDlModelParamSetDlModelParam and the parameter 'fuse_conv_relu'"fuse_conv_relu""fuse_conv_relu""fuse_conv_relu""fuse_conv_relu".

'pretrained_dl_classifier_compact.hdl'"pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl":

This neural network is designed to be more memory and runtime efficient.

The classifier expects the images to be of the type 'real'"real""real""real""real". Additionally, it requires certain image properties. The corresponding values can be retrieved with get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""image_height" should not be less than 15 pixels.

'pretrained_dl_classifier_enhanced.hdl'"pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl":

This neural network has more hidden layers than 'pretrained_dl_classifier_compact.hdl'"pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""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'"real""real""real""real". Additionally, it requires certain image properties. The corresponding values can be retrieved with get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""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.

'pretrained_dl_classifier_resnet50.hdl'"pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl":

As the neural network 'pretrained_dl_classifier_enhanced.hdl'"pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl""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'"real""real""real""real". Additionally, it requires certain image properties. The corresponding values can be retrieved with get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""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.

Models for Semantic Segmentation

The following pretrained neural networks are provided for semantic segmentation:

'pretrained_dl_segmentation_compact.hdl'"pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl":

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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""image_height" of 21 pixels.

'pretrained_dl_segmentation_enhanced.hdl'"pretrained_dl_segmentation_enhanced.hdl""pretrained_dl_segmentation_enhanced.hdl""pretrained_dl_segmentation_enhanced.hdl""pretrained_dl_segmentation_enhanced.hdl":

This neural network has more hidden layers than 'pretrained_dl_segmentation_compact.hdl'"pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl""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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""image_height" of 47 pixels.

Reading in a Model in the ONNX Format

You can read in an ONNX model, but there are some points to consider.

Restrictions

Reading in ONNX models with read_dl_modelread_dl_modelReadDlModelReadDlModelReadDlModel, some restrictions apply:

Automatic transformations

After reading an ONNX model with read_dl_modelread_dl_modelReadDlModelReadDlModelReadDlModel, some network transformations are executed automatically:

Supported operations

ONNX models with the following operations can be read by read_dl_modelread_dl_modelReadDlModelReadDlModelReadDlModel:

'Add'
'AveragePool':

'count_include_pad'"count_include_pad""count_include_pad""count_include_pad""count_include_pad" must be 0.

'BatchNormalization'
'Concat':

The value for 'axis'"axis""axis""axis""axis" must be 1.

'Conv'
'Dropout'
'Gemm':

The dimension K must be 1.

'GlobalAveragePool'
'GlobalMaxPool'
'LogSoftmax':

The value for 'axis'"axis""axis""axis""axis" must be 1.

'LRN'
'MaxPool'
'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'"axis""axis""axis""axis" must be 1.

'Sum'

Execution Information

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.

Parameters

FileNameFileNameFileNameFileNamefileName (input_control)  filename.read HTupleHTupleHtuple (string) (string) (HString) (char*)

Filename

Default value: 'pretrained_dl_classifier_compact.hdl' "pretrained_dl_classifier_compact.hdl" "pretrained_dl_classifier_compact.hdl" "pretrained_dl_classifier_compact.hdl" "pretrained_dl_classifier_compact.hdl"

List of values: 'initial_dl_anomaly_large.hdl'"initial_dl_anomaly_large.hdl""initial_dl_anomaly_large.hdl""initial_dl_anomaly_large.hdl""initial_dl_anomaly_large.hdl", 'initial_dl_anomaly_medium.hdl'"initial_dl_anomaly_medium.hdl""initial_dl_anomaly_medium.hdl""initial_dl_anomaly_medium.hdl""initial_dl_anomaly_medium.hdl", 'pretrained_dl_classifier_alexnet.hdl'"pretrained_dl_classifier_alexnet.hdl""pretrained_dl_classifier_alexnet.hdl""pretrained_dl_classifier_alexnet.hdl""pretrained_dl_classifier_alexnet.hdl", 'pretrained_dl_classifier_compact.hdl'"pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl""pretrained_dl_classifier_compact.hdl", 'pretrained_dl_classifier_enhanced.hdl'"pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl""pretrained_dl_classifier_enhanced.hdl", 'pretrained_dl_classifier_resnet50.hdl'"pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl""pretrained_dl_classifier_resnet50.hdl", 'pretrained_dl_segmentation_compact.hdl'"pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl""pretrained_dl_segmentation_compact.hdl", 'pretrained_dl_segmentation_enhanced.hdl'"pretrained_dl_segmentation_enhanced.hdl""pretrained_dl_segmentation_enhanced.hdl""pretrained_dl_segmentation_enhanced.hdl""pretrained_dl_segmentation_enhanced.hdl"

File extension: .hdl

DLModelHandleDLModelHandleDLModelHandleDLModelHandleDLModelHandle (output_control)  dl_model HDlModel, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the deep learning model.

Result

If the parameters are valid, the operator read_dl_modelread_dl_modelReadDlModelReadDlModelReadDlModel returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.

Possible Successors

set_dl_model_paramset_dl_model_paramSetDlModelParamSetDlModelParamSetDlModelParam, get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParam, apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModel, train_dl_model_batchtrain_dl_model_batchTrainDlModelBatchTrainDlModelBatchTrainDlModelBatch, train_dl_model_anomaly_datasettrain_dl_model_anomaly_datasetTrainDlModelAnomalyDatasetTrainDlModelAnomalyDatasetTrainDlModelAnomalyDataset

Alternatives

create_dl_model_detectioncreate_dl_model_detectionCreateDlModelDetectionCreateDlModelDetectionCreateDlModelDetection

References

Open Neural Network Exchange (ONNX), https://onnx.ai/

Module

Deep Learning Inference