* 
* 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.
*生成一个保存数据的文件夹，这个文件夹在此.hdev相同的目录
ExampleDataDir := 'classify_pill_defects_data'
* Dataset directory basename for any outputs written by preprocess_dl_dataset.
*根据处理数据不同的方式，另外生成一个文件夹保存
DataDirectoryBaseName := ExampleDataDir + '/dldataset_pill'
* 
* *************************
* **   Set parameters   ***
* *************************
* 
* LabelSource for reading in the dataset.
LabelSource := 'last_folder'
* 
* Percentages for splitting the dataset.
*训练验证的比例
TrainingPercent := 70
ValidationPercent := 15
* 
* 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 the dataset with the procedure read_dl_dataset_classification.
* Alternatively, you can read a DLDataset dictionary
* as created by e.g., the MVTec Deep Learning Tool using read_dict().
*在这个目录下搜索子文件夹，以最后一个文件夹的名字作为标签（LabelSource := 'last_folder' ）
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.
*预处理后数据集的输出都会保存到此文件夹下
DataDirectory := DataDirectoryBaseName + '_' + ImageWidth + 'x' + ImageHeight
* 
* Preprocess the dataset. This might take a few seconds.
*创建一个空字典
create_dict (GenParam)
*往这个字典里面加入一个键值对
set_dict_tuple (GenParam, 'overwrite_files', true)
*下面这句话是对数据做实际处理的
*参数包括：
*DLDataset--已被拆分训练和测试的数据集
*DataDirectory--预处理后数据集的保存目录
*DLPreprocessParam--预处理时所用到的参数
*GenParam--一个字典，里面放键值对
*DLDatasetFileName--为输出，（好像是记录了数据的索引之类的玩意）
preprocess_dl_dataset (DLDataset, DataDirectory, DLPreprocessParam, GenParam, DLDatasetFileName)
* 
* Store preprocess params 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.
*在数据集里面搜索'samples'，返回具体的样本句柄（这里有2850个）
get_dict_tuple (DLDataset, 'samples', DatasetSamples)
*根据条件挑选句柄中符合的
find_dl_samples (DatasetSamples, 'split', 'train', 'match', SampleIndices)
*打乱排序
tuple_shuffle (SampleIndices, ShuffledIndices)
*从数据集中读取打乱后的前9个
read_dl_samples (DLDataset, ShuffledIndices[0:9], DLSampleBatchDisplay)
* 
create_dict (WindowHandleDict)
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