McodeGrade

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

Grade the code occurrence(s) in an image.

Syntax

void McodeGrade(
    AIL_ID    ContextCodeId,                   //in
    AIL_ID    ImageBufId,                      //in
    AIL_ID    SrcResultCodeId,                 //in
    AIL_INT   SrcModelCodeIndexOrResultIndex,  //in
    AIL_ID    DstResultCodeId,                 //out
    AIL_INT64 ControlFlag                      //in
)

Description

This function computes different quality-grades for the code occurrences in an image, as specified in the code context, and writes the results in the destination result buffer. Retrieve results using McodeGetResult. McodeGrade can also grade code occurrences found using McodeRead.

Note: Note that McodeGrade does not support M_4_STATE, M_PHARMACODE, M_POSTNET, and M_PLANET code types.

By default, McodeGrade internally performs a code read operation before performing the code grade operation. However, you can skip this step if you pass McodeGrade the result buffer from a previous successful call to McodeRead; this is more efficient if for some reason, you need to explicitly call McodeRead prior to calling McodeGrade. In this case for all code types except 2D matrix, ensure that McodeRead was executed with the control type M_POSITION_ACCURACY set to high to avoid potential failure.

Since the global context settings are required, McodeGrade requires that you pass a code context identifier, and not a code model identifier. The code context passed to McodeGrade can contain multiple code models depending on their code type (see McodeModelfor details). McodeGrade can grade one or more occurrences of 1D and Data Matrix code models; for other types of code models, McodeGrade can grade at most one occurrence. If a target image is specified and the code context contains multiple code models, you can grade all the occurrences of a specific code model or grade all the occurrences of all the code models (M_ALL). If a source code result buffer is specified and it contains the results of several code occurrences, you can specify the index of the code occurrence to grade or grade all the occurrences (M_ALL).

Before calling McodeGrade, ensure that the following control types are set appropriately for your code occurrences.

Control type	Notes
M_FOREGROUND_VALUE	Specifies the foreground color of the code occurrence. This control type must be set if the foreground color is not black; the code occurrence will not be graded if the foreground value is not correctly set.
M_ENCODING	Specifies the type of encoding scheme for the code occurrence. This control type must be set if the default encoding scheme for the code type differs from the one used by the code occurrence or if M_ANY is not supported.
M_ERROR_CORRECTION	Specifies the type of error correction scheme for the code occurrence. This control type must be set if the default error correction scheme for the code type differs from the one used by the code occurrence or if M_ANY is not supported.
M_STRING_SIZE....	Specifies the maximum and minimum size of the string (number of characters) encoded in each code occurrence. These control types must be set if M_STRING_SIZE_MIN and/or M_STRING_SIZE_MAX cannot be set to M_ANY.
M_SEARCH_ANGLE....	Specifies the nominal search angle and angular search range. These control types must be set if the code occurrence is at an angle greater or less than 0.0 ±5 degrees.

For more information on code model and code context settings that can improve results, see Customizing read and grade operation settings.

If you have associated the target image with a camera calibration context, you can specify that certain input settings be interpreted in world units. To do so, use McodeControl with M_ABSOLUTE_APERTURE_SIZE_INPUT_UNITS, M_SCANLINE_INPUT_UNITS, M_DOT_SPACING_INPUT_UNITS, M_SEARCH_ANGLE_INPUT_UNITS, and/or M_CELL_SIZE_INPUT_UNITS set to M_WORLD. Note that if you set any of these constants to M_WORLD but you don't pass McodeGrade a calibrated target image, the function will generate an error. If you pass a source code result buffer to McodeGradeinstead of a target image, the code context should have the same settings as the context passed to McodeRead; the settings should not be changed between the two operations. A source code result buffer (passed to this function) should contain results obtained from a calibrated target image for best results.

It is strongly recommended to use a region of interest (ROI), set using MbufSetRegion, with McodeGrade, especially if your image contains more code occurrences than your context is configured to grade; otherwise, Aurora Imaging Library will randomly select the specified number of code occurrences to grade. Grading only a portion of your image is also recommended because it achieves a fast and robust McodeGrade operation if your image contains other information besides the code occurrences (for example, text). Note that, if your image has an ROI, you can have the nominal angle set to the same angle as that of the image's ROI, using McodeControl with M_SEARCH_ANGLE set to M_ACCORDING_TO_REGION.

You should note that if the code occurrence cannot be decoded by Aurora Imaging Library, all grades will be returned as F.

If you cannot read a bar code with a cell size that is size 2 or smaller, you can enlarge the image using MimResize and try again.

Parameters

ContextCodeId (in, AIL_ID)

Specifies the identifier of the code context, allocated using McodeAlloc.

ImageBufId (in, AIL_ID)

Specifies the identifier of the image buffer containing the code occurrence(s) to be graded. The image buffer must be an 8-bit, unsigned, 1-band image buffer. Note that, this image buffer should contain the same image used for the previous McodeRead operation.

SrcResultCodeId (in, AIL_ID)

Specifies a source code result buffer from which to retrieve McodeRead results. The result buffer must have been allocated using McodeAllocResult with M_CODE_READ_RESULT. Note thatM_GRADING_STANDARD and M_EXTENDED_AREA_REFLECTANCE_CHECK should have been set before the McodeRead operation. In addition for all code types except 2D matrix, the results must have been obtained from the same source image in high accuracy (McodeControl M_POSITION_ACCURACY set to M_HIGH). This parameter can be set to M_NULL.

SrcModelCodeIndexOrResultIndex (in, AIL_INT)

Specifies the index of the code model (in the code context) or the result occurrence (in the source code result buffer) to use when grading.

For specifying the model or the result containing information about the code occurrence to grade

Value	Description
M_DEFAULT
M_ALL (default)	Specifies to grade all occurrences of all code models in the code context or all occurrences of code models in the source code result buffer.
Value >= 0	Specifies which code model (from the code context) or result index (from the result buffer) to use, when grading the code occurrence.

DstResultCodeId (out, AIL_ID)

Specifies the result buffer in which to write the resulting grading information. The result buffer must have been allocated using McodeAllocResult with M_CODE_GRADE_RESULT.

ControlFlag (in, AIL_INT64)

Reserved for future expansion. This parameter must be set to M_DEFAULT.