MbeadTrain

This function trains the templates for a verification operation and sets internal processing settings to optimize future calculations for speed and robustness. This function can also internally save or free a training image (TrainingImageBufId).

You must call this function before your first call to MbeadVerify(). Certain modifications to a bead context, such as adding, deleting, or modifying templates with MbeadTemplate(), or changing some control settings with MbeadControl(), require you to retrain the templates before any subsequent call to MbeadVerify().

To inquire the training status of the templates in the context, use MbeadInquire() with M_STATUS. Typically you should not call MbeadVerify() until all the templates in the context have been completely trained. You might have to modify your settings and retrain the templates more than once before you can perform a successful verification. To draw the templates in the context (trained or untrained), use MbeadDraw().

To train the templates, MIL must establish their trained points, which are based on the most current settings, such as the spacing between the expected position of the trained points, the template's path (polyline, circle, or segment), and width. To train the templates, MIL also uses the training image, if it is required by the template's settings.

By default, you must use a training image, since the default path a template follows is a polyline that is refined by the training image (MbeadControl() with M_TRAINING_PATH set to M_DEFAULT or M_POLYLINE_SEED). If a template follows a path that is a fixed polyline, circle, or segment (M_POLYLINE, M_CIRCLE, or M_SEGMENT), the path's position will not be refined, even if you specify a training image. Similarly, MIL uses the training image by default to establish the width of the template's path (MbeadControl() with M_WIDTH_NOMINAL_MODE set to M_DEFAULT or M_AUTO_...). If the nominal width is explicitly set, a training image is not required and is ignored if provided.

If you have associated the training image with a camera calibration context, you can specify that certain input settings for the training phase be interpreted in world units. To do so, use MbeadControl() with M_TEMPLATE_INPUT_UNITS and/or M_TRAINING_BOX_INPUT_UNITS set to M_WORLD. To use a calibrated training image, you can either pass one to this function, or you can specify the camera calibration context to associate to the training image, using MbeadControl() with M_ASSOCIATED_CALIBRATION. If both camera calibrations are available, MIL ignores the camera calibration set with M_ASSOCIATED_CALIBRATION. Note that if MIL is interpreting input settings for the training phase in world units, but you don't use a calibrated training image, MbeadTrain() will generate an error.

If you are specifying pixel units, make sure the pixel sizes are consistent across all camera calibrations (for example, pixel sizes should be the same in the training and verification images). When using different camera calibration contexts, it is recommended that you use world units.