Retrieving results
- See also
Availability
Previous
- Next
To retrieve results for all occurrences of all code models (or in the case of an McodeTrain() operation, for all code models), use McodeGetResult() with M_ALL and the result type for the result that you want returned. To retrieve a result for a specific code model occurrence (or in the case of an McodeTrain() operation, for a specific code model), use McodeGetResult() with the index of the occurrence. To increase efficiency when browsing result types, use filters to limit table values to those of interest based on operation type and code type.
To retrieve the success of an McodeRead(), McodeGrade(), McodeTrain(), or McodeWrite() operation, use M_STATUS. A positive status is returned only when all conditions, set for all the code models, are met. Note that when reading multiple code occurrences and more than one McodeRead() operation fails, the error returned is the one you should probably fix first. For example, if you try to read two codes and one fails because the code was not found (M_STATUS_NOT_FOUND) and the other fails because the encoding type was unknown (M_STATUS_ENC_UNKNOWN), the latter is returned.
Every occurrence of every code model is associated with a unique index within the result buffer after a successful code operation. When using McodeGetResult(), you must specify the index of the occurrence for which to retrieve results.
The following table presents an example of a code result buffer, showing the result occurrence index, code model index, angle, and string for 6 occurrences of 4 models in a context. If, for instance, you wanted to get additional results about only one of these occurrences, you should pass the result occurrence index to McodeGetResult() along with the required result type. Results are ordered in the sequence that they are found.
|
Result type |
Result occurrence index |
|||||
|
0 |
1 |
2 |
3 |
4 |
5 |
|
|
3 |
3 |
1 |
0 |
2 |
0 |
|
|
9.0 |
7.0 |
2.0 |
4.0 |
0.0 |
0.0 |
|
|
First occurrence of code model 3 |
Second occurrence of code model 3 |
Only occurrence of code model 1 |
First occurrence of code model 0 |
Only occurrence of code model 2 |
Second occurrence of code model 0 |
|
The result occurrence index is not explicitly returned by any function in the MIL Code module, instead it must be deduced from the order in which the results are returned by McodeGetResult(); results are always indexed in ascending order starting from zero. To retrieve the number of occurrences in a code result buffer, use McodeGetResult() with M_NUMBER.
For each code occurrence read, you can retrieve the decoded string or the length of the string, using McodeGetResult() with M_STRING or M_STRING_SIZE, respectively. Combining M_ESCAPE_SEQUENCE with M_STRING will return the string with unprintable characters represented by their ASCII code (in hexadecimal notation, prefixed by \x). Combining M_ESCAPE_SEQUENCE with M_STRING_SIZE will return the length of the decoded string with the ASCII characters used to represent unprintable characters included in the count.
Drawing results
The McodeDraw() function provides several operations for drawing results in any specified image buffer or 2D graphics list. By drawing into the display's overlay buffer or associating the 2D graphics list with the display, you can also annotate an image non-destructively (see the Annotating the displayed image non-destructively section of Chapter 23: Displaying an image).
You can use a previously allocated 2D graphics context (see Chapter 24: Generating graphics) to control the drawing color, or use the default 2D graphics context (M_DEFAULT).
Supported drawing operations include drawing the bounding box of the specified code occurrence (using M_DRAW_BOX) or a cross-like symbol at the mid-point of the code occurrence (using M_DRAW_POSITION). McodeDraw() can draw the code with its quiet zone (using M_DRAW_QUIET_ZONE) and (optionally) the extended area (using M_DRAW_EXTENDED_AREA). McodeDraw() can draw the scan path (using M_DRAW_SCAN_PROFILES) or the scan reflectance profiles of the code (M_DRAW_REFLECTANCE_PROFILE), as analyzed by the grade operation. The scan reflectance profile is generated from sampling the code along a single scan path using a specific aperture. The following is an example of a scan reflectance profile of the code.
Unless otherwise specified, all scan paths will be drawn. To draw the path of a specific scan reflectance profile, specify the index of the scan reflectance profile using the ResultIndex parameter of McodeDraw(). The following is an example of 10 scan paths drawn over the existing image of the code.
When drawing composite codes, you can draw either the 2D (M_2D_COMPONENT) or the 1D (M_LINEAR_COMPONENT) component of the code.