apply_dl_modelT_apply_dl_modelApplyDlModelApplyDlModelapply_dl_model应用深度学习模型（算子）

名称

apply_dl_modelT_apply_dl_modelApplyDlModelApplyDlModelapply_dl_model — 在一组图像上应用基于深度学习的网络进行推理。

签名

apply_dl_model( : : DLModelHandle, DLSampleBatch, Outputs : DLResultBatch)

描述

apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModelapply_dl_model 将由 DLModelHandleDLModelHandleDLModelHandleDLModelHandleDLModelHandledlmodel_handle 提供的基于深度学习的网络应用于通过字典元组 DLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchdlsample_batch 传递的输入图像批次。该算子返回 DLResultBatchDLResultBatchDLResultBatchDLResultBatchDLResultBatchdlresult_batch，这是一个元组，其中包含每个输入图像的对应结果字典 DLResultDLResultDLResultDLResultDLResultdlresult。

有关 HALCON 中深度学习模型的概念和字典的更多信息，请参阅深度学习 / 模型一章。

要将网络应用于图像，您需要通过 DLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchdlsample_batch 字典元组传递图像，其中每个字典对应一张图像。您可以通过调用函数 gen_dl_samples_from_images 方便地创建这样的字典。字典 DLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchdlsample_batch 可以包含任意数量的字典。算子 apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModelapply_dl_model 始终同时处理最多包含 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" 张图像的批次。若元组包含更多图像，apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModelapply_dl_model 会在内部迭代处理所需数量的批次。对于图像数量少于 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" 的 DLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchdlsample_batch，元组会被填充至完整批次。这意味着处理 DLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchdlsample_batch 所需的时间与批次是否填满无关，即使该批次仅包含单张图像也是如此。这也意味着，如果单次调用算子处理的图像数量少于 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size"，网络仍需占用与完整批次相同的内存。当前 'batch_size'"batch_size""batch_size""batch_size""batch_size""batch_size" 的值可通过 get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParamget_dl_model_param 获取。

请注意，在将图像输入 apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModelapply_dl_model 算子之前，可能需要对图像进行预处理以满足网络要求。您可以通过 get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParamget_dl_model_param 获取当前网络的要求，例如图像尺寸。函数 preprocess_dl_dataset 提供了如何实现此类预处理阶段的指导。

结果以 DLResultBatchDLResultBatchDLResultBatchDLResultBatchDLResultBatchdlresult_batch 的形式返回，该元组包含一个字典 DLResultDLResultDLResultDLResultDLResultdlresult，对应每张输入图像。有关 DLResultBatchDLResultBatchDLResultBatchDLResultBatchDLResultBatchdlresult_batch 中输出字典及其键的更多信息，请参阅深度学习 / 模型一章。在 OutputsOutputsOutputsOutputsoutputsoutputs 中，您可以指定哪些输出数据将返回至 DLResultDLResultDLResultDLResultDLResultdlresult。OutputsOutputsOutputsOutputsoutputsoutputs 可以是单个字符串、字符串元组，或是用于获取所有可能输出的空元组。如果在 AI² 接口中使用 apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModelapply_dl_model，可能需要在模型针对 AI² 接口优化前，将 OutputsOutputsOutputsOutputsoutputsoutputs 中所有请求层设为 'is_inference_output'"is_inference_output""is_inference_output""is_inference_output""is_inference_output""is_inference_output" = 'true'"true""true""true""true""true"，详情请参阅 optimize_dl_model_for_inferenceoptimize_dl_model_for_inferenceOptimizeDlModelForInferenceOptimizeDlModelForInferenceOptimizeDlModelForInferenceoptimize_dl_model_for_inference 和 set_dl_model_layer_paramset_dl_model_layer_paramSetDlModelLayerParamSetDlModelLayerParamSetDlModelLayerParamset_dl_model_layer_param。OutputsOutputsOutputsOutputsoutputsoutputs 的值取决于网络的模型类型：

'type'"type""type""type""type""type"='3d_gripping_point_detection'"3d_gripping_point_detection""3d_gripping_point_detection""3d_gripping_point_detection""3d_gripping_point_detection""3d_gripping_point_detection" 的模型

OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：DLResultDLResultDLResultDLResultDLResultdlresult 包含：
- 'gripping_map'：二值图像，用于标注场景中每个像素点：模型是否预测该点为抓取点（像素值=1.0）或非抓取点（0.0）。
- 'gripping_confidence'：图像，包含场景中每个点的原始、未校准置信度值。

'type'"type""type""type""type""type"='anomaly_detection'"anomaly_detection""anomaly_detection""anomaly_detection""anomaly_detection""anomaly_detection" 的模型

OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：DLResultDLResultDLResultDLResultDLResultdlresult 包含一张图像，其中每个像素对应输入图像像素的分数。此外，它还包含整张图像的分数。

'type'"type""type""type""type""type"='counting'"counting""counting""counting""counting""counting" 的模型

此模型类型无法使用 apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModelapply_dl_model 算子运行。

'type'"type""type""type""type""type"='gc_anomaly_detection'"gc_anomaly_detection""gc_anomaly_detection""gc_anomaly_detection""gc_anomaly_detection""gc_anomaly_detection" 的模型

对于每个 OutputsOutputsOutputsOutputsoutputsoutputs 值，DLResultDLResultDLResultDLResultDLResultdlresult 包含一张图像，其中每个像素对应输入图像像素的分数。此外，它还包含整张图像的分数。

OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：每个输入图像像素的分数是通过所有可用网络的组合计算得出的。
OutputsOutputsOutputsOutputsoutputsoutputs='anomaly_image_local'"anomaly_image_local""anomaly_image_local""anomaly_image_local""anomaly_image_local""anomaly_image_local"：每个输入图像像素的分数仅由 'local'"local""local""local""local""local" 网络计算得出。若 'local'"local""local""local""local""local" 网络不可用，则会触发错误。
OutputsOutputsOutputsOutputsoutputsoutputs='anomaly_image_global'"anomaly_image_global""anomaly_image_global""anomaly_image_global""anomaly_image_global""anomaly_image_global"：每个输入图像像素的分数仅由 'global'"global""global""global""global""global" 网络计算得出。若 'global'"global""global""global""global""global" 网络不可用，则会触发错误。

'type'"type""type""type""type""type"='classification'"classification""classification""classification""classification""classification" 的模型

OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：DLResultDLResultDLResultDLResultDLResultdlresult 包含一个元组，其中置信度值按降序排列，以及按相应顺序排序的类名和类 IDs 元组。

'type'"type""type""type""type""type"='detection'"detection""detection""detection""detection""detection" 的模型

OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：DLResultDLResultDLResultDLResultDLResultdlresult 包含边界框坐标，以及所有级别推理出的类及其置信度值。
OutputsOutputsOutputsOutputsoutputsoutputs= '[bboxhead + level + _prediction, classhead + level + _prediction]'，其中 'level'"level""level""level""level""level" 表示选定级别（介于 'min_level'"min_level""min_level""min_level""min_level""min_level" 与 'max_level'"max_level""max_level""max_level""max_level""max_level" 之间）：DLResultDLResultDLResultDLResultDLResultdlresult 包含边界框坐标、特定级别下推理出的类及其置信度值。

'type'"type""type""type""type""type"='ocr_recognition'"ocr_recognition""ocr_recognition""ocr_recognition""ocr_recognition""ocr_recognition" 的模型

OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：DLResultDLResultDLResultDLResultDLResultdlresult 包含识别出的单词。此外，它还包含该单词中每个字符的候选词及其置信度。

'type'"type""type""type""type""type"='ocr_detection'"ocr_detection""ocr_detection""ocr_detection""ocr_detection""ocr_detection" 的模型

OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：DLResultDLResultDLResultDLResultDLResultdlresult 包含已定位单词的边界框坐标。

'type'"type""type""type""type""type"='segmentation'"segmentation""segmentation""segmentation""segmentation""segmentation" 的模型

OutputsOutputsOutputsOutputsoutputsoutputs='segmentation_image'"segmentation_image""segmentation_image""segmentation_image""segmentation_image""segmentation_image"：DLResultDLResultDLResultDLResultDLResultdlresult 包含一张图像，其中每个像素的值对应于其所属像素被分配到的类。
OutputsOutputsOutputsOutputsoutputsoutputs='segmentation_confidence'"segmentation_confidence""segmentation_confidence""segmentation_confidence""segmentation_confidence""segmentation_confidence"：DLResultDLResultDLResultDLResultDLResultdlresult 包含一张图像，其中每个像素都具有该像素分类结果的置信度值。
OutputsOutputsOutputsOutputsoutputsoutputs='[]'"[]""[]""[]""[]""[]"：DLResultDLResultDLResultDLResultDLResultdlresult 包含所有输出值。

注意

系统要求：要在 GPU 上运行此算子，需将 'device'"device""device""device""device""device" 设置为 'gpu'"gpu""gpu""gpu""gpu""gpu"（参见 get_dl_model_paramget_dl_model_paramGetDlModelParamGetDlModelParamGetDlModelParamget_dl_model_param），同时需要安装 cuDNN 和 cuBLAS。更多详细信息，请参阅 “安装指南” 中的“深度学习及基于深度学习方法的要求”一章。

执行信息

多线程类型：可重入（与非独占算子并行运行）。
多线程作用域：全局（可从任何线程调用）。
在内部数据级别上自动并行化。

此算子支持取消超时和中断。

此算子支持中断超时和中断。

参数

DLModelHandleDLModelHandleDLModelHandleDLModelHandleDLModelHandledlmodel_handle (输入控制) dl_model → (handle)

深度学习模型的句柄。

DLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchDLSampleBatchdlsample_batch (输入控制) dict-array → (handle)

输入数据。

OutputsOutputsOutputsOutputsoutputsoutputs (输入控制) string-array → (string)

请求的输出。

默认值： []

值列表： [], 'bboxhead2_prediction'"bboxhead2_prediction""bboxhead2_prediction""bboxhead2_prediction""bboxhead2_prediction""bboxhead2_prediction", 'classhead2_prediction'"classhead2_prediction""classhead2_prediction""classhead2_prediction""classhead2_prediction""classhead2_prediction", 'segmentation_confidence'"segmentation_confidence""segmentation_confidence""segmentation_confidence""segmentation_confidence""segmentation_confidence", 'segmentation_image'"segmentation_image""segmentation_image""segmentation_image""segmentation_image""segmentation_image"

DLResultBatchDLResultBatchDLResultBatchDLResultBatchDLResultBatchdlresult_batch (输出控制) dict-array → (handle)

结果数据。

结果

如果参数有效，算子 apply_dl_modelapply_dl_modelApplyDlModelApplyDlModelApplyDlModelapply_dl_model 返回值 2 ( H_MSG_TRUE )。如有必要，则抛出异常。

可能的前趋

read_dl_modelread_dl_modelReadDlModelReadDlModelReadDlModelread_dl_model, train_dl_model_batchtrain_dl_model_batchTrainDlModelBatchTrainDlModelBatchTrainDlModelBatchtrain_dl_model_batch, train_dl_model_anomaly_datasettrain_dl_model_anomaly_datasetTrainDlModelAnomalyDatasetTrainDlModelAnomalyDatasetTrainDlModelAnomalyDatasettrain_dl_model_anomaly_dataset, set_dl_model_paramset_dl_model_paramSetDlModelParamSetDlModelParamSetDlModelParamset_dl_model_param

模块

基础。此算子采用动态许可机制（详见《安装指南》）。所需模块取决于算子的具体使用场景：
三维计量、光学字符识别/光学字符验证、深度学习推理

算子