MstrRead

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().