| Customize Help

Predicting


MclassPredict() uses a trained classifier context to predict the class to which the target belongs. For a trained CNN classifier context, your target is typically an image. For a trained tree ensemble classifier context, your target is typically an array of features.

For either classifier, you can also specify its corresponding dataset as the target and predict the class to which unlabeled entries belong. For more information, see the Assisted labeling subsection of this section.

Steps to predict

The following steps provide a basic methodology for predicting with the trained classifier context:

  1. Allocate a classification result buffer to hold the prediction results, using MclassAllocResult() with M_PREDICT_CNN_RESULT or M_PREDICT_TREE_ENSEMBLE_RESULT.

  2. Modify prediction settings, using MclassControl().

  3. Preprocess the trained classifier context, using MclassPreprocess().

  4. Perform the prediction operation with the trained classifier context and the target data that you want to classify (a target image or a set of target features), using MclassPredict().

    Optionally, perform the prediction operation with the test dataset as your target. If the predicted classes are not what you expect, when compared to the actual classes in the test dataset (the ground truth), you can adjust your training setup, and continue the training process. Note, when performing the prediction operation with a dataset as your target, you can hook functions to prediction events, using MclassHookFunction().

  5. Retrieve the required results from the classification result buffer, using MclassGetResult(). You can also draw prediction results, using MclassDraw().

Timeout and stop

To prevent the classification process from taking too long, you can set a maximum calculation time for MclassPredict(), by calling MclassControl() with M_TIMEOUT. You can also stop the current execution of MclassPredict() (from another thread of higher priority), by specifying M_STOP_PREDICT.

Results

Typically, the most important prediction results to retrieve are the best predicted class (M_BEST_CLASS_INDEX) and its score (M_BEST_CLASS_SCORE). The score is a measure, in percentage, of how well a class represents the target. Therefore, the class with the highest score is the class to which the target belongs.

You can also retrieve the status result of the prediction operation (M_STATUS), allowing you to determine if MclassPredict() is currently predicting, has completed successfully, or was terminated because of a timeout limit or a memory issue. To clear the prediction results, call MclassControl() with M_RESET and the identifier of the prediction result buffer.

Note, if you have a testing dataset, you should predict with it, using MclassPredict(). As previously discussed, predicting with a testing dataset serves as a quarantined final check for your trained classifier. If the results are what you expect (they should be approximately the same as your training results), you can continue with prediction using your trained classifier. If the results are not what you expect, it is a sign that you should continue training.

Drawing

To draw prediction results, call MclassDraw(). You can perform drawing operations to, for example, illustrate the best class result (M_DRAW_BEST_INDEX_IMAGE or M_DRAW_BEST_INDEX_CONTOUR_IMAGE) or the resulting class scores (M_DRAW_BEST_SCORE_IMAGE and M_DRAW_CLASSIFICATION_SCORE).

To draw the icon image related to the class, use M_DRAW_CLASS_ICON. Note, this image is not a result; you specify it using MclassControl() with M_CLASS_ICON_ID, and you draw it from a classifier context or a dataset context (not a result buffer). By drawing the class' icon image, you are able to visually identify the class for which you are getting results. Similarly, you can also specify and draw a color related to a class, to help visually identify it (M_DRAW_CLASS_COLOR_LUT).

In general, drawing operations for prediction results can prove particularly useful when performing an image classification prediction with a child buffer or a buffer with a region, or when performing a coarse segmentation prediction. For more information, see the Drawing coarse segmentation results subsection of the Advanced techniques section later in this chapter.

Note, if you are performing feature classification (tree ensemble), you can only specify drawing operations for a dataset context (for example, M_DRAW_CLASS_ICON).

Assisted labeling

You can call MclassPredict() with a trained classifier context and a dataset context (rather than a target image or a set of features) to label (predict) the class to which each dataset entry belongs. Typically this is done to label unlabeled dataset entries and then add those entries to the datasets for training, using the predicted label as the ground truth. This process is known as assisted labeling or active learning.

Using MclassPredict() this way is typically done when you have so much data with which to train (hundreds of thousands of images or features), that it is unrealistic to manually label all of it (unless the data gathering process naturally sorts out the classes). To assist the labeling, a random subset of the entries (images or sets of features), such as a few hundred per class, can be labeled by prediction, and then used in the dataset to continue training the classifier.

You should only accept the predicted label as the ground truth if you are very confident in the predicted label result; for example, when you conclude that the score is robust and above an extremely high value, such as 99%.

Adding this new labeled data to the training dataset is known as exploitation. In general, you would have an expert label a new subset of the remaining data which is known as exploration. This entire process, iterated until a satisfactory performance, assumes that the data picked and labeled by the expert constitutes a dataset of good quality and quantity.

When performing the prediction operation on a target dataset, you can hook functions to prediction events, using MclassHookFunction(). To get information about the prediction events that caused the hook-handler function to execute, call MclassGetHookInfo().