Halcon 深度学习 分类预处理

read_dl_dataset_classification 产生一个深度学习数据集算子

read_dl_dataset_classification( : : RawImageFolder, LabelSource : DLDataset)
RawImageFolder (input_control): 字符串数组，表示包含已标记图像的文件夹路径。这些文件夹中的图像应按类别组织，使得可以通过文件夹名或其他方式轻松地识别其类别标签。

LabelSource (input_control): 字符串，指定如何从图像文件夹结构中提取标签信息。默认值为 'last_folder'，意味着标签将从图像所在的最后一个文件夹名中获取。例如，如果图像位于 /path/to/class1/image1.jpg 和 /path/to/class2/image2.jpg，那么 class1 和 class2 将作为标签。

DLDataset (output_control): 返回的数据集字典。这个字典包含了从指定文件夹中读取的所有图像及其对应的标签信息。这个数据集可以用于后续的数据处理操作，比如数据增强、分割成训练集和验证集等

split_dl_dataset 将样本分为训练、验证和测试子集

split_dl_dataset( : : DLDataset, TrainingPercent, ValidationPercent, GenParam : )

DLDataset (input_control): 输入的数据集字典，该字典包含了关于数据集的信息。这个字典通常包含了所有样本的图像及其对应的标签。
TrainingPercent (input_control): 整数或实数类型，表示分配给训练数据集的样本百分比。默认值为 60%，即 60% 的数据将用于训练。该值的有效范围为 0 到 100。
ValidationPercent (input_control): 整数或实数类型，表示分配给验证数据集的样本百分比。默认值为 20%，即 20% 的数据将用于验证。该值的有效范围为 0 到 100。
GenParam (input_control): 任何类型，这里通常是一个字典，用于指定非默认的数据集划分参数。默认情况下为空字典 []，表示使用默认的划分策略。

create_dl_preprocess_param 使用预处理参数创建字典

create_dl_preprocess_param( : : DLModelType, ImageWidth, ImageHeight, ImageNumChannels, ImageRangeMin, ImageRangeMax, NormalizationType, DomainHandling, IgnoreClassIDs, SetBackgroundID, ClassIDsBackground, GenParam : DLPreprocessParam)

DLModelType (input_control): 字符串类型，用于指定预处理过程中针对的深度学习模型类型。默认值为 'segmentation'。建议值包括 'classification'、'multi_label_classification'、'detection'、'segmentation'、'3d_gripping_point_detection'、'ocr_recognition' 和 'ocr_detection'。
ImageWidth (input_control): 整数类型，表示图像被重新缩放后的宽度。有效值区间为 1 及以上。
ImageHeight (input_control): 整数类型，表示图像被重新缩放后的高度。有效值区间为 1 及以上。
ImageNumChannels (input_control): 整数类型，表示图像被重新缩放后的通道数。有效值区间为 1 及以上。
ImageRangeMin (input_control): 整数类型，默认值为 -127，表示像素灰度值范围的最小值。
ImageRangeMax (input_control): 整数类型，默认值为 128，表示像素灰度值范围的最大值。
NormalizationType (input_control): 字符串类型，用于指定预处理过程中的归一化类型。默认值为 'none'。建议值包括 'all_channels'、'first_channel'、'constant_values' 和 'none'。
DomainHandling (input_control): 字符串类型，用于指定如何处理域（如果存在）。默认值为 'full_domain'。建议值包括 'full_domain'、'crop_domain' 和 'keep_domain'。
IgnoreClassIDs (input_control): 整数或整数数组类型，默认值为 []，表示在训练期间应忽略的类别 ID。
SetBackgroundID (input_control): 整数或整数数组类型，默认值为 []，表示背景类别的类别 ID。
ClassIDsBackground (input_control): 整数或整数数组类型，默认值为 []，表示设置为背景类别的类别 ID。
GenParam (input_control): 任意类型，默认值为 []，表示通用参数的字典。
DLPreprocessParam (output_control): 输出的预处理参数字典。

preprocess_dl_dataset 预处理DLDataset中声明的整个数据集

preprocess_dl_dataset( : : DLDataset, DataDirectory, DLPreprocessParam, GenParam : DLDatasetFileName)

DLDataset (input_control): 输入的数据集字典，该字典包含了关于数据集的信息，例如图像和标签。这个字典将被预处理。
DataDirectory (input_control): 字符串类型，指定存储处理后数据的目录路径。默认值为 'dl_dataset'。
DLPreprocessParam (input_control): 字典类型，包含了预处理参数。这些参数用于指导数据预处理过程，例如图像的尺寸调整、归一化等。
GenParam (input_control): 任意类型，默认值为 []，是一个字典，用于指定一些通用参数。这些参数可以根据具体的应用场景来定义。
DLDatasetFileName (output_control): 字符串类型，表示处理后的数据集字典的文件路径。

write_dict 写入字典文件

write_dict( : : DictHandle, FileName, GenParamName, GenParamValue : )
    DictHandle (input_control): 字典句柄，用于标识要操作的字典。此参数需要一个句柄类型的输入，且必须包含一个元素。
    FileName (input_control): 文件名，指定要保存或读取字典的文件路径。文件扩展名为 .hdict，表明这是一种特定类型的字典文件格式。

    GenParamName (input_control): 泛型参数名称的字符串或字符串数组，用于指定一些可选的泛型参数。默认值为 []。可选值包括 'compact_json'、'file_type'、'raise_error_if_content_not_serializable' 和 'use_json_arrays'。

    GenParamValue (input_control): 泛型参数值的字符串、整数或浮点数，对应于 GenParamName 中指定的参数。默认值为 []。建议的值包括 'hdict'、'json'、'true'、'false' 和 'low_level'。

find_dl_samples 根据模式集检索包含与KeyValue匹配的KeyName的样本索引。

find_dl_samples( : : Samples, KeyName, KeyValue, Mode : SampleIndices)
   Samples (input_control): 字典或包含字典的元组数组，表示要遍历的样本集合。每个样本是一个字典。

    KeyName (input_control): 字符串类型，指定要查找的键名。默认值为 'split'。

    KeyValue (input_control): 任何类型（整数、浮点数或字符串），表示在键名 KeyName 下查找的值。默认值为 []。建议值包括 1、2.2、'string' 或 [1, 2.2, 'mixed']。

    Mode (input_control): 字符串类型，定义搜索行为。默认值为 'match'。可选值包括 'match'、'or' 和 'contain'。

    SampleIndices (output_control): 整数数组类型，表示根据设定的模式匹配到的样本索引。

tuple_shuffle 随机对元组的元素进行排序

tuple_shuffle( : : Tuple : Shuffled)
Tuple (input_control): 输入的元组，可以包含任何类型的数据（整数、浮点数、字符串等）。
Shuffled (output_control): 输出控制参数，表示经过处理（例如洗牌）后的元组。

read_dl_samples 读取样本

read_dl_samples( : : DLDataset, SampleIndices : DLSampleBatch)
    DLDataset (input_control): 输入的字典，包含了关于数据集的信息。这个字典通常包含了数据集中的所有样本及其相关信息（如图像、标签等）。

    SampleIndices (input_control): 整数或整数数组类型，表示在字典 DLDataset 中要读取的样本索引。默认值为 []。该值的有效区间为 0 及以上。

    DLSampleBatch (output_control): 输出控制参数，表示从磁盘读取的 DLSample 字典或 DLSample 字典组成的元组。

dev_display_dl_data 可视化样本的不同图像、注释和推理结果

dev_display_dl_data( : : DLSample, DLResult, DLDatasetInfo, KeysForDisplay, GenParam, WindowHandleDict : )


    DLSample (input_control): 输入的样本字典，包含了需要可视化的样本信息。默认值为 []。

    DLResult (input_control): 输入的结果字典，包含了指定样本的预测结果。默认值为 []。

    DLDatasetInfo (input_control): 输入的数据集信息字典或深度学习模型句柄，用于获取 DLResult。默认值为 []。如果为空，则尝试从 DLSample 或 DLResult 推断存在的类别 ID。如果提供了分类或检测模型的 DLResult，则还会从 DLResult 推断类别名称，否则类别名称将显示为 'unknown'。

    KeysForDisplay (input_control): 字符串或字符串数组，指定了请求的可视化类型。建议值包括 'image'、'classification_ground_truth'、'classification_result'、'classification_both'、'segmentation_weight'、'segmentation_weight_map'、'segmentation_confidence'、'segmentation_confidence_map'、'bbox_ground_truth'、'bbox_result'、'bbox_both'、'segmentation_image_ground_truth'、'segmentation_image_result'、'segmentation_image_both' 和 'segmentation_image_diff'。

    GenParam (input_control): 通用参数字典，包含了一些可选的通用参数。默认值为 []。

    WindowHandleDict (input_control): 包含窗口句柄的字典，用于指定可视化的窗口。

dev_close_window_dict 关闭数据字典

dev_close_window_dict( : : WindowHandleDict : )

案例 分类药丸

预处理 设置文件路径

* 
* This example is part of a series of examples, which summarizes
* the workflow for DL classification. It uses the MVTec pill dataset.
* 
* The four parts are:
* 1. Dataset preprocessing.
* 2. Training of the model.
* 3. Evaluation of the trained model.
* 4. Inference on new images.
* 
* Hint: For a concise version of the workflow please have a look at the example:
* dl_classification_workflow.hdev
* 
* This example contains part 1: 'Dataset preprocessing'.
* 
dev_update_off ()
* 
* In this example, the preprocessing steps are explained in graphics windows,
* before they are executed. Set the following parameter to false in order to
* skip this visualization.
ShowExampleScreens := true
* 预处理
if (ShowExampleScreens)
    * Initial example windows and parameters etc.
    dev_example_init (ShowExampleScreens, ExampleInternals)
    * 
    * Introduction text of example series.
    dev_display_screen_introduction_part_1 (ExampleInternals)
    stop ()
    dev_display_screen_introduction_part_2 (ExampleInternals)
    stop ()
    * 
    * Read the dataset.
    dev_display_screen_read_dataset (ExampleInternals)
    stop ()
    * 
    * Explain splitting the dataset.
    dev_display_screen_split_dataset (ExampleInternals)
    stop ()
    * 
    * Explain how to preprocess the dataset and run the program.
    dev_display_screen_run_program (ExampleInternals)
    stop ()
endif
* 
* *********************************
* **   Set Input/Output paths   ***
* *********************************
* 
* Get the path to the examples.
* 获取系统路径
get_system ('example_dir', PathExample)
* Folder with ground truth classification image data.
* 获取文件路径
RawImageBaseFolder := PathExample + '/images/pill/'
* 
* All example data is written to this folder.
* 写入文件夹数据名称
ExampleDataDir := 'classify_pill_defects_data'
* Dataset directory basename for any outputs written by preprocess_dl_dataset.
* 由preprocess_dl_Dataset编写的任何输出的数据集目录基名。
DataDirectoryBaseName := ExampleDataDir + '/dldataset_pill'
* 
* *************************
* **   Set parameters   ***
* *************************
* 
* LabelSource for reading in the dataset.
LabelSource := 'last_folder'
* 
* Percentages for splitting the dataset.
* 训练集 70% 验证集15%
TrainingPercent := 70
ValidationPercent := 15
* 
* Some models may have limitations regarding the image properties,
* see read_dl_model () for the model of your choice.
* Image dimensions the images are rescaled to during preprocessing.
* 图片的宽高，轨道数量
ImageWidth := 300
ImageHeight := 300
ImageNumChannels := 3
* 
* Further parameters for image preprocessing.
NormalizationType := 'none'
DomainHandling := 'full_domain'
* 
* In order to get a reproducible split we set a random seed.
* This means that re-running the script results in the same split of DLDataset.
* 随机种子
SeedRand := 42
* 
* *****************************************************************************
* **   Read the labeled data and split it into train, validation and test   ***
* *****************************************************************************
* 
* Set the random seed.
* 设置随机种子
set_system ('seed_rand', SeedRand)

产生数据集进行预处理

* 产生深度学习数据集
read_dl_dataset_classification (RawImageBaseFolder, LabelSource, DLDataset)
* Generate the split.
* 产生数据分类
split_dl_dataset (DLDataset, TrainingPercent, ValidationPercent, [])
* 
* 
* *********************************
* **   Preprocess the dataset   ***
* *********************************
* 
* Create the output directory if it does not exist yet.
file_exists (ExampleDataDir, FileExists)
if (not FileExists)
    make_dir (ExampleDataDir)
endif
* 
* Create preprocess parameters.
* 创建预处理数据字典
create_dl_preprocess_param ('classification', ImageWidth, ImageHeight, ImageNumChannels, -127, 128, NormalizationType, DomainHandling, [], [], [], [], DLPreprocessParam)
* 
* Dataset directory for any outputs written by preprocess_dl_dataset.
*preprocess_dl_Dataset编写的任何输出的数据集目录。
DataDirectory := DataDirectoryBaseName + '_' + ImageWidth + 'x' + ImageHeight
* 
* Preprocess the dataset. This might take a few seconds.
* 对数据字典预处理
GenParam := dict{overwrite_files: 'auto'}
preprocess_dl_dataset (DLDataset, DataDirectory, DLPreprocessParam, GenParam, DLDatasetFileName)
* 
* Store preprocess parameters separately in order to use it, e.g., during inference.
* 存储预处理参数
PreprocessParamFileBaseName := DataDirectory + '/dl_preprocess_param.hdict'
write_dict (DLPreprocessParam, PreprocessParamFileBaseName, [], [])
* 
* *******************************************
* **   Preview the preprocessed dataset   ***
* *******************************************
* 显示预处理数据
* Before moving on to training, it is recommended to check the preprocessed dataset.
* 
* Display the DLSamples for 10 randomly selected train images
* 显示
find_dl_samples (DLDataset.samples, 'split', 'train', 'match', SampleIndices)
tuple_shuffle (SampleIndices, ShuffledIndices)
read_dl_samples (DLDataset, ShuffledIndices[0:9], DLSampleBatchDisplay)
* 
WindowHandleDict := dict{}
for Index := 0 to |DLSampleBatchDisplay| - 1 by 1
    * Loop over samples in DLSampleBatchDisplay.
    dev_display_dl_data (DLSampleBatchDisplay[Index], [], DLDataset, 'classification_ground_truth', [], WindowHandleDict)
    Text := 'Press Run (F5) to continue'
    dev_disp_text (Text, 'window', 'bottom', 'right', 'black', [], [])
    stop ()
endfor
* 
* Close windows that have been used for visualization.
dev_close_window_dict (WindowHandleDict)
* 
if (ShowExampleScreens)
    * Hint to the DL classification training process example.
    dev_display_screen_next_example (ExampleInternals)
    stop ()
    * Close example windows.
    dev_close_example_windows (ExampleInternals)
endif