read_dl_classifierT_read_dl_classifierReadDlClassifierReadDlClassifier (Operator)

Name

read_dl_classifierT_read_dl_classifierReadDlClassifierReadDlClassifier — Read a deep-learning-based classifier from a file.

Signature

read_dl_classifier( : : FileName : DLClassifierHandle)

Herror T_read_dl_classifier(const Htuple FileName, Htuple* DLClassifierHandle)

void ReadDlClassifier(const HTuple& FileName, HTuple* DLClassifierHandle)

void HDlClassifier::HDlClassifier(const HString& FileName)

void HDlClassifier::HDlClassifier(const char* FileName)

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

void HDlClassifier::ReadDlClassifier(const HString& FileName)

void HDlClassifier::ReadDlClassifier(const char* FileName)

void HDlClassifier::ReadDlClassifier(const wchar_t* FileName)   (Windows only)

static void HOperatorSet.ReadDlClassifier(HTuple fileName, out HTuple DLClassifierHandle)

public HDlClassifier(string fileName)

void HDlClassifier.ReadDlClassifier(string fileName)

Description

The operator read_dl_classifierread_dl_classifierReadDlClassifierReadDlClassifierReadDlClassifier reads a neural network written by write_dl_classifierwrite_dl_classifierWriteDlClassifierWriteDlClassifierWriteDlClassifier. As a result, the handle DLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandle is returned.

HALCON provides pretrained neural networks. These neural networks are good starting points to train a custom classifier for image classification. They have been pretrained on a large image dataset. The provided pretrained neural networks are:

'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 memory and runtime efficient.

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_classifier_paramget_dl_classifier_paramGetDlClassifierParamGetDlClassifierParamGetDlClassifierParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""image_height" of 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. But this comes at the cost of being more time and memory demanding. As a result, e.g. in comparison to the above compact network, the batch size has to be decreased network during the training, see set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParam.

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_classifier_paramget_dl_classifier_paramGetDlClassifierParamGetDlClassifierParamGetDlClassifierParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""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.

'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.

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_classifier_paramget_dl_classifier_paramGetDlClassifierParamGetDlClassifierParamGetDlClassifierParam. 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'"image_width""image_width""image_width""image_width" and 'image_height'"image_height""image_height""image_height""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 values listed above are the default image dimensions and gray value range for the networks and these are the values with which the classifiers have been trained. The network architectures allow different image sizes which can be set with set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParam. For networks with at least one fully connected layer such a change makes a retraining necessary. Networks without fully connected layers are directly applicable to different image sizes. However, images with a size differing from the size with which the classifier has been trained are likely to show a reduced classification accuracy.

The actually configured dimensions can be queried by get_dl_classifier_paramget_dl_classifier_paramGetDlClassifierParamGetDlClassifierParamGetDlClassifierParam. Every image that is fed into a network must be present according to the required dimensions. To adjust images accordingly, the procedure preprocess_dl_classifier_images is available.

Typically it is easier, faster and better to retrain a pretrained classifier for a given classification problem. A pretrained classifier has already learned good general purpose features. To retrain the network for a custom problem, the new 'classes'"classes""classes""classes""classes" of the classifier have to be set with set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParam (see HDevelop example classify_pill_defects_deep_learning.hdev)

The neural network is loaded from the file FileNameFileNameFileNameFileNamefileName. This file is hereby searched in the directory ($HALCONROOT/dl/) as well as in the currently used directory.

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

The default HALCON file extension for deep learning classifiers is '.hdl'".hdl"".hdl"".hdl"".hdl".

For an explanation of the concept of deep-learning-based classification see the introduction of chapter Deep Learning / Classification.

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*)

File name.

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: '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"

File extension: .hdl

DLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandle (output_control)  dl_classifier HDlClassifier, HTupleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the deep learning classifier.

Result

If the indicated file is available and the format is correct, the operator read_dl_classifierread_dl_classifierReadDlClassifierReadDlClassifierReadDlClassifier returns the value 2 (H_MSG_TRUE). Otherwise an exception will be raised.

Possible Successors

set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamSetDlClassifierParam, get_dl_classifier_paramget_dl_classifier_paramGetDlClassifierParamGetDlClassifierParamGetDlClassifierParam, apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierApplyDlClassifier, train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchTrainDlClassifierBatch

Alternatives

read_class_mlpread_class_mlpReadClassMlpReadClassMlpReadClassMlp, read_class_svmread_class_svmReadClassSvmReadClassSvmReadClassSvm

Module

Deep Learning Inference