|
V+ 12.4 Release Notes |
 |
 |
 |
 |
VFEATURE (index)
Return specified information about the object most recently VLOCATEd or the ObjectFinder or prototype model most recently displayed by the VSHOW program instruction.
The VFEATURE function refers to the object most recently VLOCATEd or VSHOWed, regardless of which program task executed the VLOCATE or VSHOW instruction. Consequently, for predictable operation, only one program should execute VLOCATE and VSHOW instructions.
The VSHOW monitor command has no effect on the data available with this function.
index Real value specifying the desired information item. The value must be in the range 1 to 50, inclusive (see below).
The VFEATURE indexes, corresponding values, and units of measure are listed in VFEATURE Function Data for ObjectFinder (after VLOCATE), VFEATURE Function Data for ObjectFinder (after VSHOW), and VFEATURE Function Data (Except ObjectFinder). All are explained in detail in the following sections.
VFEATURE Function Data for ObjectFinder (following VLOCATE)
VFEATURE Function Data for ObjectFinder (after VLOCATE) lists the VFEATURE function data for the ObjectFinder when that function is used following a VLOCATE program instruction. There is a detailed description for each item after the table.
ITEM 1. VFEATURE(1) has the value TRUE when the ObjectFinder information is valid; otherwise, it is FALSE.
The information is valid when a VLOCATE succeeds in locating an object in an image or VSHOW succeeds in getting an ObjectFinder model from the loaded list.
The information is invalid when a no-wait VLOCATE fails to locate an object or a VSHOW instruction fails to find a loaded ObjectFinder model. An error occurs if the object information is invalid and a VFEATURE is executed with an index other than 1.
ITEMS 2 to 7. X, Y, Z, RX, RY, and RZ are the components of the object or ObjectFinder model transformation. (Note that the complete transformation is optionally returned by the VLOCATE and VSHOW instructions.) Z, RX, and RY are not used. (The default value for RX is always 0 and for RY, always 180. However, you should not rely on the default values that fill these unused variables.) RZ is the orientation of the object in the horizontal plane, the image plane.
After VLOCATE, the coordinates are in the reference frame of the camera. After a VSHOW instruction, the coordinates are in the reference frame of the ObjectFinder model (origin of the coordinate system is the model's centroid). Note that VSHOW draws the model in the Vision display window so that the center of its bounding box is at the center of the window.
ITEM 8. This VFEATURE item is the belt encoder value at the time the strobe light fired (see the V.STROBE system switch). (This value is also available from the V+ DEVICE real-valued function.)
ITEM 9. Verify percentage is a recognition certainty value. The verify percentage is 0 if the region VLOCATEd is unknown. Otherwise, it is the percentage of the weighted boundary of the ObjectFinder model that was verified. If following a VSHOW instruction, this is the verify percentage required for recognition of an instance of the model.
ITEM 11. (After VLOCATE only) The model number is the number of the ObjectFinder model used in the planning list (1 - 10) specified in the VPLAN.FINDER instruction.
ITEM 12. (After VLOCATE only) Instance ID is a count of the number of objects recognized. These ID numbers start at 1 and count up.
ITEMS 13 to 16. Min_X, Max_X, Min_Y, and Max_Y define a bounding box for the region VLOCATEd or the ObjectFinder model last VSHOWed. The bounding box is an orthogonal rectangle that encloses the region, with the four corners: (Min_X, Min_Y), (Min_X, Max_Y), (Max_X, Max_Y), (Max_X, Min_Y). One application of a bounding box definition is for finding clear space for placing things on a conveyor belt or a pallet. For a region, the bounding box coordinates are in the reference frame of the camera. For an ObjectFinder model (following a VSHOW instruction), the coordinates are given with respect to the reference frame of the model.
ITEM 18. This is the elapsed time (in seconds) spent to acquire and analyze the image and to perform recognition. Since it is elapsed time, it includes the time spent to update the display and to respond to any commands such as VSTATUS and VQUEUE. The detailed procedure for keeping time is as follows.
ITEM 23. After a VLOCATE, this is the number of the virtual camera with which the object was located. After a VSHOW, this is the number of a virtual camera associated with the ObjectFinder model.
ITEM 27. The number of features in the ObjectFinder model VLOCATEd. All of the line segments and circular arcs in the model are counted, even if the weight (after multiple-instance training) is zero.
VFEATURE Function Data for ObjectFinder (following VSHOW)
VFEATURE Function Data for ObjectFinder (after VSHOW) lists the VFEATURE function data for the ObjectFinder when that function is used following a VSHOW program instruction. There is a detailed description for each item after the table.
See the descriptions following VFEATURE Function Data for ObjectFinder (after VLOCATE) for each item in VFEATURE Function Data for ObjectFinder (after VSHOW). Exceptions and items not contained in VFEATURE Function Data for ObjectFinder (after VLOCATE) are shown below.
ITEM 11. Shows the add instances ok field of the model. Following VSHOW, indicates that it is okay to add instances during multi-instance training.
ITEM 12. Minimum verify percentage is a recognition certainty value. The verify percentage following a VSHOW instruction is the minimum verify percent found when matching instances during multi-instance training. Adept recommends using a minimum verify percent that is 10 percentage points less than this value.
ITEM 17. Number of pairs. Following VSHOW, this is the number of pairs in the ObjectFinder model.
ITEM 19. Average verify percentage is a recognition certainty value. When following a VSHOW instruction, this is the average verify percent found when matching instances during multi-instance training.
ITEM 20. Max verify percentage is a recognition certainty value. When following a VSHOW instruction, this is the maximum verify percent found when matching instances during multi-instance training.
ITEM 21. Hierarchical level. This is the image processing level (0 - 2). See VTRAIN.FINDER (cam, mode, dmode, arg, arg2, arg3) $model_name, ibr = value, value2, value3 for details.
ITEM 22. Following a VSHOW, the parent number is always -1.
ITEM 23. After a VLOCATE, this is the number of the virtual camera with which the object was located. After a VSHOW, this is the number of a virtual camera associated with the ObjectFinder model.
ITEM 24. (After VSHOW only) The effort level assigned to an ObjectFinder model during training.
ITEM 25. Convergence measure. This is a measure of the convergence of the feature weights during multi-instance training. Higher means more convergence (i.e., higher confidence that the weights are really converging to some set of constant values). This would mean that the model is stabilizing. In most cases, the value should be at least 3. However, a value of 2 may be sufficient for some applications.
ITEM 26. The number of ObjectFinder samples taught during training. This is a measure of the reliability of the model.
ITEM 27. The number of features in the ObjectFinder model VSHOWed. All of the line segments and circular arcs in the model are counted, even if the weight (after multiple-instance training) is zero.
ITEM 28. Maximum pixel variation (measured in units of pixels). This parameter controls the fitting of features to edges in the edge segmentation stage. Final fitting is done via a least-squares fit and is not affected by this number.
ITEM 29. Maximum location distance (measured in units of pixels). This parameter controls the distance between proposals. It is used in a strategy that attempts to prevent too many proposals from being made in the same location.
VFEATURE Function Data for Prototypes
VFEATURE Function Data (Except ObjectFinder) lists the VFEATURE function data for prototypes. There is a detailed description for each item after the table.
ITEM 1. VFEATURE(1) has the value TRUE when the object or prototype information is valid; otherwise, it is FALSE.
The information is valid when a VLOCATE succeeds in locating an object in an image or VSHOW succeeds in getting a prototype from the loaded prototype list.
The information is invalid when a no-wait VLOCATE fails to locate an object or a VSHOW instruction fails to find a loaded prototype. An error occurs if the object information is invalid and a VFEATURE is executed with an index other than 1.
ITEMS 2 to 7. X, Y, Z, RX, RY, and RZ are the components of the object or prototype transformation. (Note that the complete transformation is optionally returned by the VLOCATE and VSHOW instructions.) Z, RX, and RY are not used. (The default value for RX is always 0 and for RY, always 180. However, you should not rely on the default values that fill these unused variables.) RZ is the orientation of the object in the horizontal plane, the image plane.
The setting of the V.CENTROID switch may affect the location components. If the region is unknown (that is, the object name is ?) and the V.CENTROID switch is enabled, the X,Y location is for the region centroid and RZ is 0. If the V.CENTROID switch is disabled, the location is the center of the bounding box for the unknown region. The setting of the V.CENTROID switch has the same effect on the location components after a VLOCATE in find-hole mode. However, after a VSHOW instruction in get-hole mode, the X,Y location is always the centroid of the prototype.
After VLOCATE, the coordinates are in the reference frame of the camera. After a VSHOW instruction, the coordinates are in the reference frame of the prototype (origin of the coordinate system is the prototype centroid). Note that VSHOW draws the prototype in the Vision display window so that the center of its bounding box is at the center of the window.
ITEM 8. This VFEATURE item is the belt encoder value at the time the strobe light fired (see the V.STROBE system switch). (This value is also available from the V+ DEVICE real-valued function.)
ITEM 9. Verify percentage is a recognition certainty value. The verify percentage is 0 if the region VLOCATEd is unknown. Otherwise, it is the percentage of the weighted boundary of the prototype that was verified. Following a VSHOW instruction, this is the verify percentage required for recognition of an instance of the prototype.
ITEM 10. Following a VLOCATE, this is the area of the region in camera pixels. If the V.SUBTRACT.HOLE system switch has been enabled, the region area has the areas of holes subtracted from it. Otherwise, they are included. In either case, the total area of the holes is available as VFEATURE item #40.
Note that this is the area of the region, not the area of the prototype instance. Following a VSHOW, this feature is the area of the prototype.
ITEMS 11 and 12. (After VLOCATE only) Region ID is a count of the number of regions encountered. Instance ID is a count of the number of objects recognized and regions not recognized. These ID numbers start at 1 and count up.
The distinction between region and instance is for touching and overlapping parts. If two objects touch and both are recognized, they account for 1 region ID increment and 2 instance ID increments. If a region consists of multiple objects and the objects are not recognized, the vision system has no way of knowing how many objects there are, so the region ID and instance ID counts are both incremented by 1.
If the vision V.DISJOINT system switch has been enabled, there may be more regions than instances, because a single prototype may span two or more regions.
ITEMS 13 to 16. Min_X, Max_X, Min_Y, and Max_Y define a bounding box for the region VLOCATEd or the prototype last VSHOWed. The bounding box is an orthogonal rectangle that encloses the region, with the four corners: (Min_X, Min_Y), (Min_X, Max_Y), (Max_X, Max_Y), (Max_X, Min_Y). One application of a bounding box definition is for finding clear space for placing things on a conveyor belt or a pallet. For a region, the bounding box coordinates are in the reference frame of the camera. For a prototype (following a VSHOW instruction), the coordinates are given with respect to the reference frame of the prototype.
ITEM 17. Following VLOCATE, this is the number of holes detected in the region. Following VSHOW, this is the number of holes in the prototype.
ITEM 18. This is the elapsed time (in seconds) spent to acquire and analyze the image and to perform recognition. Since it is elapsed time, it includes the time spent to update the display and to respond to any commands such as VSTATUS and VQUEUE. The detailed procedure for keeping time is as follows.
Timekeeping starts when the VPICTURE or VWINDOW command is received. A time record is kept for each object recognized (or region analyzed and not recognized) in the image. As each object is entered in the queue, making it ready to be VLOCATEd, the elapsed time is noted. Timekeeping is reset as the search begins for the next object in the image. Consequently, the elapsed time associated with the first object includes the time spent to acquire the image.
Other consequences of this timekeeping procedure are as follows. If multiple objects are recognized in one region, the time spent performing boundary analysis is attributed only to the first object located. Furthermore, if the V.DISJOINT switch has been enabled, the time spent analyzing the boundaries of all regions is attributed to the first object recognized. The elapsed time reported for subsequent objects is only the time spent in the recognition algorithm.
ITEM 19. Flags is a bit field. Bit #1 is reserved for future use.
Bit #2 is defined when the V.HOLES switch has been enabled. If set, the bit indicates that the region (or hole) VLOCATEd helped to verify the recognition of the object. The boundary of a region helps to verify the recognition if the region boundary coincides with the prototype boundary. Only part of the hole boundary must coincide in order to help.
The other bits in the bit field are reserved for future use.
ITEM 20. Following a VLOCATE, this is the number of the grip position that is clear. This VFEATURE entry is zero if no grippers have been defined via VDEFGRIP, or if none of the grip positions are clear. Otherwise, it is the number of the first grip that is clear. Grips are tested in the order of their numbering, 1 to 4.
ITEMS 21 and 22. Hole number and parent number provide a numbering of holes for determining parent, child, and sibling relationships. Following a VLOCATE in the normal find-object mode or a VSHOW instruction in get-prototype mode, the hole number is always 0 and the parent number is always -1. The parent in this case is the background. Following a VLOCATE in the special find-hole mode or a VSHOW in get-hole mode, the hole number is an integer value, 1 or greater. All of the holes in the object are numbered, including holes in holes. The parent number of a hole is the parent's hole number. Thus, if an object has one hole and the hole has one hole in it, the first hole's hole number is 1 and its parent number is 0. The innermost hole has a hole number of 2, with a parent number of 1.
ITEM 23. After a VLOCATE, this is the number of the virtual camera with which the object was located. After a VSHOW, this is the number of a virtual camera associated with the prototype. (VFEATURE items #30 and #31 are bit masks representing all cameras associated with the prototype.)
ITEM 24. (After VSHOW only) The effort level assigned to a prototype during training.
ITEM 25. (After VSHOW only) The color (black or white) that the prototype had during training.
ITEM 26. (After VSHOW only) The number of prototype samples taught during training. This is a measure of the reliability of the prototype.
ITEM 27. The number of bounds in the prototype VSHOWed or region VLOCATEd. If a prototype, the count includes holes. If a region, the count does not include holes. The bounds counted are lines and arcs. A solid disk has one bound, a rectangular plate has four bounds, etc. In get-hole mode, it is the number of bounds in the region for the hole.
ITEMS 28 and 29. (After VSHOW only) These are the minimum and maximum areas associated with the prototype. The values are assigned to the prototype during training.
ITEMS 30 and 31. (After VSHOW only) These two items are bit masks representing the virtual cameras associated with the prototype. Both items are 16-bit fields, with each bit representing a different virtual camera. Item #30 represents virtual cameras 1 through 16. The least-significant bit of item #30 represents camera number 1, and the highest bit represents camera number 16. Item #31 represents cameras 17 through 32, with the ordering similar to that of item #30.
The prototype is associated with those cameras whose corresponding bits are set to 1. For example, the value 6 in item #30 means that cameras 2 and 3 are associated with the prototype (^B10+^B100 = 6).
ITEMS 32 and 33. (After VSHOW only) After VSHOW of a prototype, item #32 is 1 and item #33 is the number of bounds in the prototype's main region (not counting holes). These items define the range of edge numbers for the main region. After VSHOW in get-subproto or get-hole mode, items #32 and #33 contain the range of edge numbers for the subprototype or hole's region. The subprototype numbers are relative to the prototype, not the subprototype (otherwise, item #32 would always be 1 in get-subproto mode).
ITEMS 34 to 36. (After VSHOW only) During prototype training, constraints can be defined that limit recognition to a specific area and rotation relative to the defined prototype. These items return the x, y, and angular constraints defined during training.
ITEM 40. (After VLOCATE only) This is the total area of all holes in the region last located with a VLOCATE instruction.
ITEM 41. (After VLOCATE only) If the V.PERIMETER system switch has been enabled, this is the outer perimeter of the region in millimeters.
ITEMS 42 and 43. (After VLOCATE only) If the V.CENTROID system switch has been enabled, these are the X,Y coordinates of the region centroid. These items are undefined if V.CENTROID has not been enabled. The positions and areas of holes are not considered in the centroid computation. (The V.SUBTRACT.HOLE system switch does not affect this.)
ITEMS 44 to 47. (After VLOCATE only) If the switches V.MIN.MAX.RADII and
V.CENTROID have been enabled, these VFEATURE items indicate the points on the boundary of the region that are closest to and farthest from the region centroid. Items #44 and #45 indicate the direction of the closest and farthest points relative to the region centroid. Items #46 and #47 are the distances from the centroid to the points, measured in millimeters.ITEMS 48 to 50. (After VLOCATE only) These are the dimensions of the best-fit ellipse to the region. System switches V.2ND.MOMENTS and V.CENTROID must have been enabled for this computation. Item #48 is the direction of the region major axis (axis of least inertia), in the range -90 to +90 degrees. Items #49 and #50 are the radii of the best-fit ellipse for the region. The ellipse is centered at the region centroid, and its major axis coincides with the region major axis. (See the description of the V.2ND.MOMENTS switch for an explanation of the derivation.)
IF VFEATURE(1) THEN TYPE "Recognition time = ", VFEATURE(18) END
|
Please submit comments to: techpubs@adept.com |
|
|
