MclassPrepareData

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Prepare images in a dataset, or individual images, for training or prediction.

Syntax

void MclassPrepareData(
    AIL_ID    PrepareDataContextClassId,      //in
    AIL_ID    SrcDatasetContextOrImageBufId,  //in
    AIL_ID    DstDatasetContextOrImageBufId,  //out
    AIL_ID    ClassifierContextClassId,       //in
    AIL_INT64 ControlFlag                     //in
)

Description

This function creates prepared (modified) versions of images in a dataset for training (MclassTrain), or an individual image for prediction (MclassPredict). You can, for example, use this function to resize or crop images, or add augmented images to a dataset. Some preparations are only available for training.

MclassPrepareData requires a data preparation context (MclassAlloc with M_PREPARE_IMAGES_CNN, M_PREPARE_IMAGES_DET or M_PREPARE_IMAGES_SEG) that is preprocessed (MclassPreprocess). To inquire the context's preprocessing state, call MclassInquire with M_PREPROCESSED. Note that MclassPrepareData does not support preparing signed images. Image classification and segmentation support buffers with up to 1024 bands.

The data preparation context (PrepareDataContextClassId) holds the settings with which to modify the specified source (SrcDatasetContextOrImageBufId). To change the data preparation context settings, call MclassControl. For example, you can use the M_SIZE_... controls to set the size of the images that MclassPrepareData produces, or you can use the M_AUGMENT_NUMBER_ABSOLUTE control to set the number of augmented entries to add to the destination dataset.

Note: You can consider data preparation as taking the specified source data (SrcDatasetContextOrImageBufId), modifying it (according to your data preparation settings), and copying the modified version into the specified destination (DstDatasetContextOrImageBufId). One image in your source can result in multiple modified images in your destination, depending on your data preparation settings. Source data is not modified. Class definitions and authors are copied from the source dataset to the destination, if they do not exist in the destination. If using a newly allocated destination dataset for segmentation, control values for M_NO_REGION_PIXEL_CLASS, M_NO_CLASS_DRAW_COLOR, and M_DONT_CARE_CLASS_DRAW_COLOR are copied to the destination; otherwise, these values must be the same for the source and destination datasets.

To prepare your data with specific, preset augmentations, you can call MclassControl and enable the M_PRESET... augmentation operation setting. Some preset augmentation settings are not available for binary (1-bit) and grayscale (1-band) images. Alternatively, you can access additional types of augmentation operations using the data preparation context's internal augmentation context. This context is automatically managed by Aurora Imaging Library (you need not allocate it or free it) and is an internal version of the image processing context for augmentation (that is, MimAlloc with M_AUGMENTATION_CONTEXT).

To specify the additional augmentations, you must first inquire the identifier of this internal augmentation context, by calling MclassInquire with M_AUGMENT_CONTEXT_ID. You can then use that augmentation context identifier with MimControl and enable the augmentation operation (M_AUG_..._OP).

Aurora Imaging Library only performs augmentations on a source dataset (SrcDatasetContextOrImageBufId); if you specify a source image buffer, augmentation settings are ignored (cropping/resizing settings are applied). MclassPrepareData only adds augmented images to the destination dataset if at least one augmentation operation is enabled; by default; no augmentations are enabled.

The modified (cropped/resized or augmented) images that this function produces are placed in the specified dataset context or image buffer (DstDatasetContextOrImageBufId), depending on the source you want to prepare (SrcDatasetContextOrImageBufId). The images are also placed in the destination folder, specified by the M_PREPARED_DATA_FOLDER control. By default, each time you call this function, a new PrepareX folder is created, where _X_ is the next available value to create a unique folder name. You can change this behavior with the M_DESTINATION_FOLDER_MODE control.

All the images that this function produces (and copies into the prepared data folder) will have a MIM file extension and be named as follows: _OriginalName___Prp___AugmentationNumber_.mim. For example, if MclassPrepareData produces three augmentations of Abyssinian.mim, they would be named Abyssinian_Prp_1.mim, Abyssinian_Prp_2.mim, and Abyssinian_Prp_3.mim. The suffix '0' is reserved for images that are prepared but not augmented (for example, Abyssinian_Prp_0.mim would be a cropped/resized copy of the original image).

To hook functions to data preparation events, call MclassHookFunction.

Parameters

PrepareDataContextClassId (in, AIL_ID)

Specifies the identifier of the data preparation context that this function uses to modify the source image data. This context must have been previously allocated on the required system using MclassAlloc with M_PREPARE_IMAGES_CNN, M_PREPARE_IMAGES_DET, or M_PREPARE_IMAGES_SEG and it must be in a preprocessed state before calling MclassPrepareData.

SrcDatasetContextOrImageBufId (in, AIL_ID)

Specifies the identifier of the source images dataset context or image buffer. You must have previously allocated the specified source on the required system using either MclassAlloc with M_DATASET_IMAGES or MbufAlloc... with M_IMAGE.

DstDatasetContextOrImageBufId (out, AIL_ID)

Specifies the identifier of the destination images dataset context or image buffer. The type of destination must be same as the source (SrcDatasetContextOrImageBufId); that is, the destination must be an image dataset context if the source is an image dataset context, and an image buffer if the source is an image buffer. You cannot specify the same dataset or image for both the SrcDatasetContextOrImageBufId and DstDatasetContextOrImageBufId parameters.

ClassifierContextClassId (in, AIL_ID)

Specifies the identifier of the predefined CNN, predefined object detection, or predefined segmentation classifier context that this function uses to prepare your image data. This context is allocated using MclassAlloc with M_CLASSIFIER_CNN_PREDEFINED, M_CLASSIFIER_DET_PREDEFINED, or M_CLASSIFIER_SEG_PREDEFINED. To not use a classifier context, or if the size mode specified by MclassControl is M_USER_DEFINED, you must set this parameter to M_NULL.

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.