VTRAIN.FINDER (cam, mode, dmode, arg, arg2, arg3)
$model_name, ibr = value, value2, value3

Function

Initiate training of the specified ObjectFinder model.

Usage Considerations

This instruction requires that all virtual cameras be idle (that is, no VPICTURE or VWINDOW operation can be executing).

Training is sensitive to camera calibration. Before training begins, mount, focus, and securely fix your cameras and lenses. Then calibrate the camera(s) that will be used to train and recognize the prototypes. The same camera(s) with the same calibration and position used for training must also be used for recognition.

Adept recommends the following settings for the symmetry override parameter (mode 1, arg3):

• For most cases, allow model disambiguation for all models by leaving the symmetry override parameter at its default value (0).
• If a model has perfect n-way symmetry and the ObjectFinder is being programmed in V+, set the symmetry override parameter to (1) and adjust the orientation returned by the ObjectFinder using V+ code so that gripper motion is optimized.
• If the object is perfectly circularly symmetric, then set the symmetry override parameter to -1 to disable disambiguation.

Parameter s

cam Optional integer specifying the virtual camera (and associated calibration, switches, and parameters) to use when acquiring an image for defining a prototype. This camera will also be the default camera associated with the prototype (see the AdeptVision User's Guide for details on associating cameras with a prototype).

mode Optional integer specifying the operating mode for this instruction. See below for details.

dmode Optional real-valued expression that specifies the display mode to use when displaying the border of the window:
-1 No draw
0 Erase
1 Default. Draw solid
2 Complement
3 Draw dashed
4 Complement dashed

arg, arg2, arg3
Integers whose meaning depends on the value of the mode parameter. See below for details.

$model_name String containing the name for the model (up to 15 characters).

ibr Integer value specifying the image buffer region for training a model. Image buffer regions specify both a size and a frame store (see the description of VDEF.AOI). The image buffer region's AOI must specify a nonrotated rectangular shape. For ObjectFinder, the AOI width is reduced, if necessary, to a multiple of four pixels.

value Floating-point expressions whose meaning depends on the value of the mode parameter. See below for details.

Description of the mode parameter:

This section describes the meanings of the different values used with the mode parameter, and the meanings of other input parameters used with a particular mode. If an input parameter is not shown, it cannot be used for that mode.

Mode 1: Train first instance (new model)
arg Hierarchical level (0 - 2) is the result of the subsampled image
0 Full resolution
1 One-half resolution
2 One-quarter resolution
arg2 Verify percent
arg3 Symmetry override
0 Enable model disambiguation (default)
1 Disable model disambiguation
n>1 Disable model disambiguation and specify that the model
has n-way symmetry. The angle of a model instance is
reported by the ObjectFinder modulo 360/n degrees.
-1 Disable disambiguation and specify that the model has
circular symmetry. The angle of a model instance reported by
the ObjectFinder is always zero degrees.

Mode 2: Display features only
arg Hierarchical level (0 - 2) is the result of the subsampled image
0 Full resolution
1 One-half resolution
2 One-quarter resolution
arg2 Edges only (0,1)
0 Features are fit to the edges and the features are displayed
1 Only the results of edge detection are displayed

Mode 3: Set ObjectFinder model parameters (after last instance)
To train new instances during multi-instance training, use VFINDER
with mode=2.
arg Indicates the value:
1 Symmetry of model
2 Auto-add instances is okay (value=0 turns it OFF;
value=non-0 turns it ON)
3 Verify percent to assign to model
value The value to assign to the designated parameter

NOTE: VisionWare uses the Mode 3/arg=2/value flag to control when to stop adding instances when in learning mode. It checks the convergence count in the model (using VSHOW/VFEATURE) and stops adding instances after the features in the model have converged sufficiently. See the AdeptVision Reference Guide for details on VSHOW/VFEATURE.

Mode 4: Feature weight setting (also feature deletion)
arg Feature number (1 to num_features)
(-1 means all features)
value New weight to assign
0 deletes the feature (deletion means that the feature is not
used)
1 - 100 relative weighting for verification (the feature is still
used to form feature-pairs).

Mode 5: Object instance offsets

value x coordinate of offset in pixels
value2 y coordinate of offset in pixels
value3 angular offset in degrees

Mode 6: Display a model feature
arg Number of the feature to display

Mode 7: Display a model feature in RED
arg Number of the feature to display

Mode 8: Accept the last-trained additional instance
arg Low weight cutoff (used for multi-instance training and is the
threshold on feature weights [on a scale of 0 - 100]; feature
weights below the low weight cutoff are set to zero)

Mode 9: Do not accept the additional instance last trained
arg Low weight cutoff

Mode 10: Clear all multi-instance training statistics. Leave the first instance.
arg Low weight cutoff

Mode 11: Apply low-weight filtering
arg Low weight cutoff

Mode 12: Undo the last accepted instance
arg Low weight cutoff

Mode 14: Position and orientation limits
arg Coordinate being limited
0 Remove all limits
1 Limits specified for X (pixels)
2 Limits specified for Y (pixels)
6 Limits specified for rotation (degrees)
value If value2 is not provided, then the limit is +value1 and -value1,
otherwise the limit is +value1 and -value2.

Mode 15: ObjectFinder image type
arg Indicates the type
0 Run-length binary
1 Gray-value image (default)
2 Edge image

Details

When normal (initial) training is performed, a new model is created and assigned the given input values. Additionally, the ibr is processed to create edge pixels, and these are further processed to extract lines and arcs. The lines and arcs are paired up in various ways to form intrinsic "feature pairs". These can be later used to match with similar pairs formed from recognition images to make proposals of instances of the model. These lines, arcs, and pairs define the geometric portion of the model.

There are three system parameters (described below) that control the processing.

1. The system parameter V.EDGE.STRENGTH[vc] controls the threshold for edge points extracted during preprocessing.

2. The system parameter V.MAX.PIXEL.VAR[vc] controls the primary fitting of lines and arcs. A secondary operation performs a least-squares fitting to the edge points, which greatly improves the accuracy.

3. The system parameter V.MIN.LEN[vc] restricts the pairs by setting a minimum length for the features allowed to be used to make pairs.

The system switch V.FIT.ARCS[vc] should normally be enabled but can be disabled to some advantage in certain difficult cases. If an object is mostly lines but contains some segments that occasionally fit as arcs due to noise in the image, you can force the system to fit only lines and avoid the additional computation time required to fit arcs.

Input parameters using virtual cameras

All switches and parameters should be at the default settings, except as noted here.

The following settings are required:

PARAMETER V.MIN.AREA[vc] = 4

PARAMETER V.MIN.HOLE.AREA[vc] = 4

The following settings are suggested:

ENABLE V.FIT.ARCS[vc] (May be disabled if the image consists of mostly lines. See the description above for details.)

V.MIN.LEN[vc] = 10 (See the description above for details.)

V.MAX.PIXEL.VAR[vc] = 2.5 (See the description above for details.)

V.EDGE.STRENGTH[vc] = 9 (See the description above for details.)

Object Instance Offsets

Mode 5 of the VTRAIN.FINDER instruction can be used to specify position and orientation offsets:

VTRAIN.FINDER (cam, 5) $model_name = x, y, angle

The x and y coordinates of the position offset are specified in units of pixels. Since the x and y coordinates are specified in floating-point, the offsets can be given with subpixel resolution. Currently, the offsets are stored in the finder model with an accuracy of 1/4 pixel. The angle offset is specified in degrees. The position and orientation offsets are added to the position and orientation of a recognized model in the image. The position offset is a vector from the model reference point chosen by the ObjectFinder at the time that the model is trained. The position offset is applied in the coordinate system of the model. After the position offset is applied, the orientation offset is added to the orientation of the model instance to rotate the reference frame by the specified amount. Any component of the position offset that is omitted defaults to zero. Likewise, if the orientation offset is omitted, it defaults to zero. The position and orientation offsets can be changed, at any time after the model has been changed, using VTRAIN.FINDER mode 5. The model does not have to be retrained for the new offsets to be used. The position and orientation offsets are saved when the model is saved using the VSTORE instruction.

ObjectFinder Image Type

Mode 15 of VTRAIN.FINDER is used to set the source type used for training and recognition. Versions of the ObjectFinder prior to 12.4 accepted a gray-value image and performed the appropriate edge-detection operations automatically before training or recognition. The ObjectFinder can accept a run-length binary image or an edge image as the source for training and recognition. The syntax of the instruction for setting the source is

VTRAIN.FINDER (cam, 15,, type)

where the type parameter has the following values (similar to the VRULER and VFIND.LINE instructions) that specify the type of source image for processing:

Type	Source
0	Run-length binary
1	Gray-value image (default)
2	Edge image

For type equal 0, training and recognition are performed with features (line segments and circular arcs) computed from the boundaries of regions in the run-length binary image using the image processing algorithms that are used in the prototype finder. For type equal 1, training and recognition are performed with features that are computed from the gray-value image using image processing algorithms that are built into the ObjectFinder. For type equal 2, training and recognition are performed with features that are computed from an edge image that is provided by the user.

NOTE: The edge image should contain chains of edges that are one pixel wide.

The object finder normally subsamples the input image before extracting features (usually 1 level of subsampling). When the object finder input is a binary image or an edge image, training and recognition must be performed at level 0, unless the program itself has subsampled the input image.

Position and Orientation Limits

Mode 14 of the VTRAIN.FINDER instruction can be used to specify position and orientation limits on use of the model during recognition. The instruction syntax is

VTRAIN.FINDER (, 14,, coordinate) $model = value1 {, value2 }

The coordinate parameter specifies the coordinate that will be constrained, as shown below. The translational limits are in units of (uncalibrated) pixels; the orientation limits are in units of degrees.

Coordinate	Meaning
0	Remove all limits
1	Specifies the limits in X
2	Specifies the limits in Y
6	Specifies the limits on orientation

Specifying value1 = 0 means no variation will be allowed in that coordinate. For example,

VTRAIN.FINDER (, 14,, 6) $model = 0

means no rotation of the model (from the orientation at which it was trained) will be allowed when making proposals.

If value2 is not provided, then the limit is +value1 and -value1, otherwise the limit is +value1 and -value2.