Operator Reference

HALCON Operator Reference / Legacy / DL Classification

• HDevelop
• .NET
• Python
• C++
• C

ClassesClasses | | Operators

apply_dl_classifierT_apply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier (Operator)

apply_dl_classifierT_apply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier — Infer the class affiliations for a set of images using a deep-learning-based classifier.

Warning

apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier is obsolete and is only provided for reasons of backward compatibility. The operator will be removed with HALCON 25.05. New applications should use the general CNN-based operator apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelapply_dl_model instead.

Signature

apply_dl_classifier(Images : : DLClassifierHandle : DLClassifierResultHandle)

Herror T_apply_dl_classifier(const Hobject Images, const Htuple DLClassifierHandle, Htuple* DLClassifierResultHandle)

void ApplyDlClassifier(const HObject& Images, const HTuple& DLClassifierHandle, HTuple* DLClassifierResultHandle)

HDlClassifierResult HDlClassifier::ApplyDlClassifier(const HImage& Images) const

void HDlClassifierResult::HDlClassifierResult(const HImage& Images, const HDlClassifier& DLClassifierHandle)

static void HOperatorSet.ApplyDlClassifier(HObject images, HTuple DLClassifierHandle, out HTuple DLClassifierResultHandle)

HDlClassifierResult HDlClassifier.ApplyDlClassifier(HImage images)

public HDlClassifierResult(HImage images, HDlClassifier DLClassifierHandle)

def apply_dl_classifier(images: HObject, dlclassifier_handle: HHandle) -> HHandle

Description

apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier applies the deep-learning-based classifier given by DLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandledlclassifier_handle on the set of input images stored in the input object tuple ImagesImagesImagesimagesimages. It returns the results in the result handle DLClassifierResultHandleDLClassifierResultHandleDLClassifierResultHandleDLClassifierResultHandledlclassifier_result_handle. For information how to retrieve the corresponding results stored in DLClassifierResultHandleDLClassifierResultHandleDLClassifierResultHandleDLClassifierResultHandledlclassifier_result_handle, please refer to the documentation of the operator get_dl_classifier_resultget_dl_classifier_resultGetDlClassifierResultGetDlClassifierResultget_dl_classifier_result.

The tuple ImagesImagesImagesimagesimages can contain an arbitrary number of images to be processed in one operator call and is generally independent of the classifier parameter 'batch_size'"batch_size""batch_size""batch_size""batch_size". Please notice that this only holds for apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier and not for train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch. This is because apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier always classifies a batch with up to 'batch_size'"batch_size""batch_size""batch_size""batch_size" images simultaneously, whether filled up or not. So in case the number of images in the set ImagesImagesImagesimagesimages is larger than 'batch_size'"batch_size""batch_size""batch_size""batch_size", apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier iterates over the necessary number of batches internally. For a ImagesImagesImagesimagesimages tuple with less than 'batch_size'"batch_size""batch_size""batch_size""batch_size" images, it is padded to a full batch which means that the runtime of processing for a given batch is independent of whether it is filled up or just consists of a single image. Additionally, if fewer images than 'batch_size'"batch_size""batch_size""batch_size""batch_size" are classified in one operator call, the network still requires the same amount of memory as for a full batch. Therefore, it is recommended to adapt the 'batch_size'"batch_size""batch_size""batch_size""batch_size" according to the number of images to be processed in one operator call for greater efficiency. The current value of 'batch_size'"batch_size""batch_size""batch_size""batch_size" can be retrieved using get_dl_classifier_paramget_dl_classifier_paramGetDlClassifierParamGetDlClassifierParamget_dl_classifier_param.

Note that the images must be processed before feeding them into the operator apply_dl_classifierapply_dl_classifierApplyDlClassifierApplyDlClassifierapply_dl_classifier in order to have the correct size, gray value range, number of channels and type. We would like to stress the image type: the images must be of type 'real'. For a possibly necessary conversion the operator convert_image_typeconvert_image_typeConvertImageTypeConvertImageTypeconvert_image_type is available. The procedure preprocess_dl_classifier_images provides great guidance on how to implement such a preprocessing stage.

For an explanation of the concept of deep-learning-based classification see the introduction of chapter Deep Learning / Classification. The workflow involving this legacy operator is described in the chapter Legacy / DL Classification.

Attention

To run this operator, cuDNN and cuBLAS are required when 'runtime'"runtime""runtime""runtime""runtime" is set to 'gpu'"gpu""gpu""gpu""gpu", see set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param. For further details, please refer to the “Installation Guide”, paragraph “Requirements for Deep Learning and Deep-Learning-Based Methods”.

Execution Information

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Multithreading scope: global (may be called from any thread).
• Processed without parallelization.

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

ImagesImagesImagesimagesimages (input_object)  (multichannel-)image(-array) → objectHImageHObjectHObjectHobject (real)

Tuple of input images.

DLClassifierHandleDLClassifierHandleDLClassifierHandleDLClassifierHandledlclassifier_handle (input_control)  dl_classifier → HDlClassifier, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the deep-learning-based classifier.

DLClassifierResultHandleDLClassifierResultHandleDLClassifierResultHandleDLClassifierResultHandledlclassifier_result_handle (output_control)  dl_classifier_result → HDlClassifierResult, HTupleHHandleHTupleHtuple (handle) (IntPtr) (HHandle) (handle)

Handle of the deep learning classification results.

Result

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

Possible Predecessors

read_dl_classifierread_dl_classifierReadDlClassifierReadDlClassifierread_dl_classifier, train_dl_classifier_batchtrain_dl_classifier_batchTrainDlClassifierBatchTrainDlClassifierBatchtrain_dl_classifier_batch, set_dl_classifier_paramset_dl_classifier_paramSetDlClassifierParamSetDlClassifierParamset_dl_classifier_param

Possible Successors

get_dl_classifier_resultget_dl_classifier_resultGetDlClassifierResultGetDlClassifierResultget_dl_classifier_result, clear_dl_classifierclear_dl_classifierClearDlClassifierClearDlClassifierclear_dl_classifier

Alternatives

apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelapply_dl_model, classify_class_mlpclassify_class_mlpClassifyClassMlpClassifyClassMlpclassify_class_mlp, classify_class_svmclassify_class_svmClassifyClassSvmClassifyClassSvmclassify_class_svm

Module

Deep Learning Enhanced

---

ClassesClasses | | Operators