McodeTrain

This function trains the settings of the selected control types of a code context and its code models so that the settings are optimized for performing an McodeRead() or McodeGrade() operation on the specified set of sample images. The function saves the results in the specified code train result buffer; the specified code context is not directly modified.

Activate the required control types for training using McodeControl() with the combination constant M_TRAIN or with M_SET_TRAINING_STATE_ALL. The following control types are supported for training:

You can limit the code occurrences used for training to those within specific regions of the training images. If the training images have a rectangular region of interest (ROI), defined using MbufSetRegion(), McodeTrain() only uses occurrences within those regions to establish the recommended settings. The regions must be defined in vector format from a 2D graphics list (M_VECTOR or M_VECTOR_AND_RASTER). An error will be generated if any of the images have an ROI that is only in raster format (M_RASTER) or is a non-rectangular shape.

This function writes the recommended settings of the activated control types to the specified code train result buffer. You can reconfigure any code context with these results using McodeControl() with M_RESET_FROM_TRAINED_RESULTS. This control type discards any existing code models from the context, and then adds the code models used for training to the context. If a control type was not trained, it is set to its value used during training; if a control type was trained, it is set to its trained value. Prior to using M_RESET_FROM_TRAINED_RESULTS, you should ensure that the train operation was successful using McodeGetResult() with M_STATUS. If required, you can retrieve the recommended setting for a specific control type using McodeGetResult(). This is especially useful if you want to reconfigure the code context that was used during training. In this case, you can use the retrieved values to selectively change the control types of the context to their trained value. Note that some control types are inter-dependent; changing the setting of one control type to its trained value might not be optimal if the settings of other control types are not also changed. This is especially true for control types that are automatically activated for training if another control type is activated (for example, M_CELL_NUMBER_...).

You can retrieve or draw the results of the read operation that McodeTrain() internally performed on each training image. You can use this extra information to complement the status result. First, call McodeGetResult() with M_CODE_RESULT_ID. This returns the identifiers of the internal code read result buffers; there is one per training image. You can then pass one of these result buffer identifiers to McodeGetResult(), and retrieve any type of result available for an McodeRead() operation. You can also pass one of the result buffer identifiers to McodeDraw() to visualize the results for a specific training image.

The recommended control type settings for a code context and its code models are based on the code occurrences found in all the training images. McodeTrain() must find at least one occurrence of one of the code models among all the sample images; otherwise, McodeGetResult() with M_STATUS returns M_STATUS_TRAIN_FAILED. You can retrieve the buffer identifiers of images in which no code occurrence was found using M_FAILED_IMAGES_ID.