Results and annotations

• See also
User Guide:
Fonts String models Working with real-world units
Reference:
MdmrControl MdmrControlStringModel MdmrDraw MdmrFree MdmrGetResult MdmrRead
Availability
Not available in MIL-Lite


Available in MIL
Previous
Next

MIL stores the results of a read operation (MdmrRead()) in a SureDotOCR result buffer. Most applications typically retrieve and draw various features of these results, using MdmrGetResult() and MdmrDraw(). For example, you can retrieve and draw the resulting string that was read.

Results

With MdmrGetResult(), you can retrieve global results, string results, or character results. Global results refer to information about the SureDotOCR result buffer itself, while string and character results refer to information about the strings and characters in the result buffer.

You can remove all results from a result buffer by calling MdmrControl() with M_RESET. This does not delete the buffer identifier, as is the case with MdmrFree(). M_RESET can be a convenient and optimal way of saving memory resources.

Strings and formatted strings

To retrieve the string that was read, use M_STRING or M_FORMATTED_STRING.

With M_STRING, you will retrieve the string that was read, according to the string model definition. This result includes the name (symbol) of all the characters in the string and the terminating null character. It also include spaces, if they correspond to a space permitted character constraint in the string model (MdmrControlStringModel() with M_SPACE).

With M_FORMATTED_STRING, you will retrieve the string that was read, according to the target string format. This result includes the name (symbol) of all the characters in the string and the terminating null character. It also includes spaces, if the target string has any that are greater than the minimum spacing (MdmrControl() with M_SPACE_SIZE_MIN) and less than the maximum spacing (M_SPACE_SIZE_MAX).

The following table shows the difference between M_STRING and M_FORMATTED_STRING, given the target string read for the string model. For simplicity, 'S' refers to space and 'L' refers to letter. Any permitted character other than space could have been used instead of a letter.

When retrieving the results of characters in strings, you must use M_INDEX_IN_STRING(n) or M_INDEX_IN_FORMATTED_STRING(n), to specify the character (one or all). The difference between these two settings is similar to the difference between M_STRING and M_FORMATTED_STRING. For M_INDEX_IN_STRING(n), spaces read in the target string are indexed as character results if they correspond to a space permitted character constraint in the string model. For M_INDEX_IN_FORMATTED_STRING(n), spaces read in the target are always indexed as character results.

For example, if the string model definition specifies to read 4 capital letters ("LLLL"), and the target string read is "AB CD", M_INDEX_IN_FORMATTED_STRING(3) refers to 'C', while M_INDEX_IN_STRING(3) refers to 'D'. If the string model definition specifies to read 4 capital letters and 1 space ("LLSLL"), and the target string read is "AB CD", M_INDEX_IN_FORMATTED_STRING(3) and M_INDEX_IN_STRING(3) both refer to 'C'.

Typical results to retrieve

In addition to retrieving the actual strings and characters read, you will also typically want to retrieve:

Size of string results

SureDotOCR returns the M_STRING, M_FORMATTED_STRING, and M_CHAR_NAME results as a string. To determine the size of the string returned, add M_STRING_SIZE to the requested result. That is, M_STRING + M_STRING_SIZE, M_FORMATTED_STRING + M_STRING_SIZE, and M_CHAR_NAME + M_STRING_SIZE.

You need this size information to establish the size of the array in which to write the results. You must specify the address of this array with the ResultArrayPtr parameter.

When retrieving multiple string results, M_STRING_SIZE returns the size of each string. To establish the total required array size, you must know the number of strings you're getting, and you must perform a summation. For example, if you read "SYLVAIN", "STEVE", and "DOMINIQUE", the content for all three strings is "SYLVAIN\0STEVE\0DOMINIQUE\0", and the string size returned (M_STRING + M_STRING_SIZE) is [8, 6, 10]. You must sum these values to get the total required array size, which is 24. M_FORMATTED_STRING requires the same summation. Differences in the resulting string size can come from how each result type manages spaces, as previously discussed.

For M_CHAR_NAME, the name of each letter at each position in the string is itself a string, with its own terminating null character. To perform the proper summations, you must get the number of strings, and the number of characters per string. For example, if the string "SYLVAIN" was read, and you retrieve the M_CHAR_NAME result type for all positions in that string, SureDotOCR returns "S\0Y\0L\0V\0A\0I\0N\0", which has a string size (M_CHAR_NAME + M_STRING_SIZE) of [2,2,2,2,2,2,2]. You must sum these values to get the required array size, which is 14. To get the required array size for all strings read, you must perform this summation for each string, and then you must sum all those values.

The following is an example of how to retrieve the character name result, with the proper array size, for all characters in all strings.

//Number of strings.
MdmrGetResult(MilDmrResult, M_GENERAL, M_DEFAULT, M_STRING_NUMBER + M_TYPE_MIL_INT, &NumberOfStringRead);

//Number of characters for each string.
MIL_INT* NbChar = new MIL_INT[NumberOfStringRead];
MdmrGetResult(MilDmrResult, M_ALL, M_GENERAL, M_FORMATTED_STRING_CHAR_NUMBER + M_TYPE_MIL_INT, NbChar);

//Total number of characters (summation).
MIL_INT TotalNbChar = 0;
for(MIL_INT k = 0; k < NumberOfStringRead; k++)
   {
   TotalNbChar += NbChar[k];
   }

//Size of each character name.
MIL_INT* CharNameSize = new MIL_INT[TotalNbChar];
MdmrGetResult(MilDmrResult, M_ALL, M_INDEX_IN_FORMATTED_STRING(M_ALL), M_CHAR_NAME + M_STRING_SIZE + M_TYPE_MIL_INT, CharNameSize);

//Size of all character names (summation).
MIL_INT SizoForAllName = 0;
for(MIL_INT k = 0; k < TotalNbChar; k++)
   SizoForAllName += CharNameSize[k];

//Total required array size for all character names for all strings.
MIL_TEXT_CHAR* AllName = new MIL_TEXT_CHAR[SizoForAllName];
MdmrGetResult(MilDmrResult, M_ALL, M_INDEX_IN_FORMATTED_STRING(M_ALL), M_CHAR_NAME, AllName);

Positional and dimensional results

If your target image (MdmrRead()) was associated with a camera calibration context, positional and dimensional results are, by default, returned with respect to the relative coordinate system of the image. Otherwise, these results are returned in pixels, relative to the center of top-left pixel in the target image. To specify this, call MdmrControl() with M_RESULT_OUTPUT_UNITS. For more information, see the Working with real-world units section of Chapter 26: Calibrating your camera setup.

Positional and dimensional results take into account the angle at which the result was found.

This example shows how the result for the bottom-left corner of the string box (M_STRING_BOX_BL_X and M_STRING_BOX_BL_Y) depends on the location and angle at which the string was read.

Recommendations to improve results

After performing the read operation, you might not always get the most optimal results. Typical issues include:

The following are recommendations to improve reading and get the best results possible.

Annotations

With MdmrDraw(), you can draw specific features of a SureDotOCR result buffer in the destination image buffer or 2D graphics list. In general, the drawings that you will want to perform include:

When applicable, the required information is drawn at the location that the string was read in the target, at the correct angle, scale, and aspect ratio. You can add the constraints corresponding to the different drawing operations together to perform multiple drawings simultaneously (for example, M_DRAW_STRING_BOX + M_DRAW_STRING_CHAR_BOX + M_DRAW_STRING_CHAR_POSITION + M_DRAW_MIL_FONT_STRING). You can also specify that the characters in the string appear according to how the target string is formatted (for example, with non-constrained spaces), by specifying M_DRAW_MIL_FONT_FORMATTED_STRING instead of M_DRAW_MIL_FONT_STRING.

Timeout or stop

The read operation can occasionally take an unexpectedly long time to calculate. To manage this, you can call MdmrControl() to specify a timeout value or to stop the read.

Timeout refers to the maximum time that MdmrRead() has to read all strings for a context. By default, the maximum time is 2000.0 msec. To change this, use M_TIMEOUT.

You can also explicitly halt the read operation, using M_STOP_READ. This call must be done from another thread of higher priority.

No results are returned if the read operation times out or is stopped.