MdlocrRead

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Read strings from a target image.

Syntax

void MdlocrRead(
    AIL_ID    ContextDlocrId,    //in
    AIL_ID    TargetImageBufId,  //in
    AIL_ID    ResultDlocrId,     //out
    AIL_INT64 ControlFlag        //in
)

Description

This function uses a Deep Learning OCR read context to read one or more strings from a target image. Results are stored in a Deep Learning OCR read result buffer. To get the results, use MdlocrGetResult.

By default, MdlocrRead reads all text in an image within the default character height range. You can control global read settings using MdlocrControl. You only need to add a string model if you want to restrict the strings that are found and read. MdlocrDefineModelFromResult allows you to define the string model so that attributes are automatically set from a resulting string found using MdlocrRead. If you only want to restrict the number of characters in the string or define a string model using an anchor, you can use MdlocrDefineModel. Regardless of how you add a model, you can always constrain the characters that appear at certain positions using MdlocrControlConstraint and adjust general string model settings using MdlocrControlStringModel.

Requirements for reading strings depend on the settings of the context and if used, string model-specific positional constraints and settings. To control these settings, use MdlocrControl, MdlocrControlConstraint, and MdlocrControlStringModel. MdlocrRead takes into account all settings.

Before performing a read operation, the Deep Learning OCR context must be in a preprocessed state (MdlocrPreprocess).

To read a string, it must not only meet the context's requirements, but it must also follow the basic rules of a string. It must, for example, be a linear sequence of characters.

Strings are read randomly in an image. A string's position is the position of the center of the bounding box of its first character.

Before preprocessing, you must manually set M_TARGET_MAX_SIZE_X and M_TARGET_MAX_SIZE_Y, generally to the size of the target image. You can limit the read operation to a region of the target image buffer, using a rectangular ROI set with MbufSetRegion. To increase performance, set M_TARGET_MAX_SIZE_X and M_TARGET_MAX_SIZE_Y to the size of the ROI.

If wanted strings have a known prefix or suffix, set M_TEXT_ANCHOR_MODE to M_TEXT_PREFIX or M_TEXT_SUFFIX respectively within your string model.

If the target image is not calibrated, results are calculated in the pixel coordinate system (pixel units). If the target image is calibrated, results are calculated in the world coordinate system (real-world units), but you can retrieve them in either world or pixel units. To specify this, call MdlocrControl with M_RESULT_OUTPUT_UNITS.

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 Deep Learning OCR.

The read operation can occasionally take an unexpectedly long time to calculate. Use MdlocrControlwith M_TIMEOUT to set a maximum read time.

To improve the performance of your Deep Learning OCR read context, you can add valid read results to a Deep Learning OCR dataset, using MdlocrAddImageToDataset. You can use this dataset to fine-tune a Deep Learning OCR read context on images from your particular application, using MdlocrFinetune.

Parameters

ContextDlocrId (in, AIL_ID)

Specifies the identifier of the Deep Learning OCR context to use for the read operation. The context must have been previously allocated on the required system using MdlocrAlloc, and preprocessed using MdlocrPreprocess.

TargetImageBufId (in, AIL_ID)

Specifies the identifier of the target image buffer which contains the strings to read. The target image buffer must be a 1-band, 8-bit unsigned buffer. Its maximum size is 65536x65536 pixels, and its expeced maximum size should be set using MdlocrControl with M_TARGET_MAX_SIZE_X and M_TARGET_MAX_SIZE_Y.

ResultDlocrId (out, AIL_ID)

Specifies the identifier of the Deep Learning OCR result buffer in which to write the results of the read operation. The Deep Learning OCR result buffer must have been previously allocated on the required system using MdlocrAllocResult.

ControlFlag (in, AIL_INT64)

Specifies the string reading mode.

For specifying the string matching mode

Value	Description
M_MODEL_BASED	Specifies that strings are read using the string models added to the Deep Learning OCR context. Only strings that meet the string model settings and positional constraints are read.
M_READ_ALL	Specifies to read all strings regardless of the string models added to the Deep Learning OCR context.