MclassPredict

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

Predict the class to which the target belongs or the position of objects to which each entry of a dataset belongs.

Syntax

void MclassPredict(
    AIL_ID    ContextClassId,                 //in
    AIL_ID    TargetAilObjectId,              //in
    AIL_ID    DatasetContextOrResultClassId,  //out
    AIL_INT64 ControlFlag                     //in
)

Description

This function uses a trained classifier context to predict the class to which the target belongs or the position of objects in the target. For a trained CNN, segmentation, object detection, or anomaly detection classifier context, you can specify an image or an images dataset context as the target. Image classification and segmentation support buffers with up to 1024 bands. For a trained tree ensemble classifier context, you can specify an array of features or a features dataset context as the target. For a trained ONNX classifier, you can only specify an image.

This function is typically called with a target image (for image classification, segmentation, object detection, or anomaly detection) or with a target array of features (for feature classification). In these cases, results are stored in a result buffer (DatasetContextOrResultClassId) and retrievable using MclassGetResult.

You can also call this function with a target dataset. In this case, the predicted data is stored in a dataset context (DatasetContextOrResultClassId). Calling MclassPredict with a dataset can be done, for example, to predict the class that represents the dataset's entries, which you can retrieve using MclassGetResultEntry with M_BEST_CLASS_INDEX. You can then use these predictions to help manually define the ground truth of the entries during training.

Before calling MclassPredict, the classifier context must be in a preprocessed state (MclassPreprocess) and it must be trained (MclassTrain). To inquire this information, use M_PREPROCESSED and M_CLASSIFIER_STATUS.

If your target is a dataset context, you can hook functions to prediction events, using MclassHookFunction (for example, with M_PREDICT_ENTRY). To get information about the events that caused the hook-handler function to execute, call MclassGetHookInfo.

Classification contexts and result buffers must have been previously allocated on the required system using MclassAlloc and MclassAllocResult, or restored from disk using MclassRestore.

Note, you can also call MclassPredict with an images dataset context to perform assisted labeling (that is, label images in an existing dataset).

By default, MclassPredict uses the default predict engine established by the Aurora Imaging Configurator utility. You can modify this by calling MclassControl with M_PREDICT_ENGINE or in Aurora Imaging Configurator.

Note: To take advantage of all available hardware resources, such as accelerating prediction using OpenVINO and CUDA, you should install the required Aurora Imaging Library add-on. For more information, see Aurora Imaging Library add-ons and updates.

Parameters

ContextClassId (in, AIL_ID)

Specifies the identifier of the trained classifier context to use for the prediction operation. You can specify a trained CNN classifier context (M_CLASSIFIER_CNN_PREDEFINED), a trained segmentation classifier context (M_CLASSIFIER_SEG_PREDEFINED), a trained object detection classifier context (M_CLASSIFIER_DET_PREDEFINED), a trained anomaly detection classifier (M_CLASSIFIER_ANO_PREDEFINED), a trained tree ensemble classifier context (M_CLASSIFIER_TREE_ENSEMBLE), or a trained ONNX classifier context (M_CLASSIFIER_ONNX).

TargetAilObjectId (in, AIL_ID)

Specifies the identifier of the target to classify. Set this parameter to one of the following values:

For specifying the target to classify

Value	Description
ArrayBufId	Specifies the identifier of a one-dimensional 32-bit float array that holds a list of features. In this case, the prediction operation will predict the best class to which the array of features belongs. The number of features in the array must be the same as the number of trained features in the dataset used to train the classifier context (DatasetContextOrResultClassId).

To specify an array, you must set the ContextClassId parameter to the identifier of a trained tree ensemble classifier context. | | ContextDatasetId | Specifies the identifier of a features or images dataset context. For CNN and tree ensemble classifiers, the prediction operation will predict the best class to which each dataset entry (feature list or image) belongs. For segmentation classifiers, the prediction operation will predict the best class to which each pixel belongs in a image entry. For object detection classifiers, the prediction operation will detect the positions of each object in an image entry. For anomaly detection classifiers, the prediction operation will predict the anomaly score of the target image as well as the anomaly score for each pixel within the image. Image classification and segmentation support buffers with up to 1024 bands.

For image datasets, you must set theContextClassId parameter to the identifier of a trained CNN, segmentation, object detection, or anomaly detection classifier context. For feature datasets, you must set the ContextClassId parameter to the identifier of a trained tree ensemble. | | ImageBufId | Specifies the identifier of a 1- or 3-band target image. Image classification and segmentation support buffers with up to 1024 bands. When ContextClassId is a trained CNN classifier context, the prediction operation will predict the best class to which the target image belongs. When ContextClassId is a trained segmentation classifier context, the prediction operation will predict the class of each pixel within the target image. When ContextClassId is a trained object detection classifier context, the prediction operation will detect the position of each object within the image. When ContextClassId is a trained anomaly detection classifier context, the prediction operation will predict the anomaly score of the target image as well as the anomaly score for each pixel within the image.

You must set the ContextClassId parameter to the identifier of a trained CNN, segmentation, object detection, anomaly detection or ONNX classifier context.

When predicting for image classification (using M_ICNET_...), the target image size must be the same as the training images. When predicting for segmentation (using M_CSNET_...), or if you are using a predefined legacy classifier (M_FCNET_...), the target image size can be bigger than the training images (this requires calling MclassControl with M_TARGET_IMAGE_SIZE_X and M_TARGET_IMAGE_SIZE_Y). By default, Aurora Imaging Library considers the size of the target image to be the same as the source layer size. |

DatasetContextOrResultClassId (out, AIL_ID)

Specifies the identifier of the result buffer or dataset in which to write the results of the prediction operation. Set this parameter to one of the following values:

For specifying the result buffer or dataset in which to write the results of the prediction

Value	Description
ContextDatasetId	Specifies the identifier of a features dataset context (M_DATASET_FEATURES) or images dataset context (M_DATASET_IMAGES). You must call MclassPredict with a features or images dataset context as your target (TargetAilObjectId). The dataset context specified by the DatasetContextOrResultClassId parameter must either be empty, or be the same dataset as your target.

If the destination is an images dataset context, Aurora Imaging Library might modify its root path (M_ROOT_PATH), if one is specified, to maintain the dataset's coherence. For example, dataset paths should all be either relative or absolute. | | ResultBufPredictId | Specifies the identifier of a CNN prediction result buffer (M_PREDICT_CNN_RESULT), a segmentation prediction result buffer (M_PREDICT_SEG_RESULT), an object detection prediction result buffer (M_PREDICT_DET_RESULT), an anomaly detection prediction result buffer (M_PREDICT_ANO_RESULT) a tree ensemble prediction result buffer (M_PREDICT_TREE_ENSEMBLE_RESULT), or an ONNX prediction result buffer (M_PREDICT_ONNX_RESULT). In this case, you must call MclassPredict with an image or an array of features as your target (TargetAilObjectId). |

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.