| Customize Help
| Save Settings


Function Map
Read strings from a target image.
void MstrRead(
MIL_ID ContextId, //in
MIL_ID TargetImageId, //in
MIL_ID ResultId //in

This function reads one or more strings from the specified target image using the specified String Reader context. All specifications, such as the number of strings to read in the target image, the speed and/or robustness settings, the constraints on the characters in the string, and the font used, depend on the settings of the String Reader context, which can be set using MstrControl(), MstrSetConstraint() and MstrEditFont(). All settings are taken into account by MstrRead(), and results are stored in the specified result buffer. Results can be read from the result buffer using the MstrGetResult() function.

For a string to be read, it must not only meet all of the restrictions placed on it by the String Reader context, but it must also obey the basic rules of a string. That is, it must be a linear sequence of regular characters.

The string read will be ordered in the natural Latin-based reading order. The position of a string is the position of the center of the bounding box of its first character.

You can limit the read operation to a region of the image buffer, using a rectangular ROI set with MbufSetRegion().

The target image must be 1-band 8-bit unsigned, and cannot exceed a maximum size of 65536x65536 pixels.

Note that before performing a read operation, the String Reader context must have at least one font, one character, and one string; it must also be preprocessed (MstrPreprocess()).

If your target image 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.

If your target image was associated with a camera calibration context but you want to retrieve positional and dimensional results in pixel units, use MstrControl() with the M_RESULT_OUTPUT_UNITS control type set to M_PIXEL. However, if you set M_RESULT_OUTPUT_UNITS to M_WORLD without specifying a calibrated image in which to calculate the results, MstrGetResult() generates an error.

In the presence of distortion, some results are meaningless when converted from real-world to pixel units (such as angle and scale). For example, if a string appears warped in the target image, but the camera calibration context compensates for this, the resulting angle is meaningful in the real-world coordinate system, and meaningless in the pixel coordinate system. If complex distortions exist, correct the image before using it with MstrRead().

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.

Specifies the String Reader context to use for the read operation. The String Reader context must have been previously allocated on the required system using MstrAlloc(), and preprocessed using MstrPreprocess().


Specifies the target image in which to read the strings.

This image buffer can only have a rectangular region of interest (ROI) defined using MbufSetRegion() (with or without rotation). In addition, the region must be defined in vector format from a 2D graphics list (M_VECTOR or M_VECTOR_AND_RASTER). An error will be generated if the ROI is only in raster format (M_RASTER) or a non-rectangular shape.


Specifies the result buffer in which to write the results of the read operation.

Compilation information
Header Include mil.h.
Library Use mil.lib; milstr.lib.
DLL Requires mil.dll; milstr.dll.