| Customize Help
| Save Settings


Function Map
Read the code occurrence(s) in an image.
void McodeRead(
MIL_ID ContextCodeId, //in
MIL_ID ImageBufId, //in
MIL_ID ResultCodeId //in

This function searches for code occurrences in an image, as specified in the code context, and writes the results in the specified result buffer. The code context's control settings determine how to perform the operation. Retrieve results using McodeGetResult().

Since the global context settings are required, McodeRead() requires that you pass a code context identifier, and not a code model identifier. The code context passed to McodeRead() can contain multiple code models depending on their code type (see McodeModel() for details). McodeRead() can read one or more occurrences of 1D and Data Matrix code models; for other types of code models, McodeRead() can read at most one occurrence.

It is strongly recommended to use a region of interest (ROI), set using MbufSetRegion(), with read operations, especially if your image contains more code occurrences than your context is configured to read; otherwise, MIL will randomly select which code occurrences to read, up to the specified number, from among all the code occurrences in the image. Reading only a portion of your source image is also recommended because it achieves a fast and robust read operation if your image contains other information besides the code occurrences. Note that, if your target image has an ROI, you can have the nominal angle set to the same angle of the target image's ROI, using McodeControl() with M_SEARCH_ANGLE set to M_ACCORDING_TO_REGION.

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_SCANLINE_INPUT_UNITS, M_DOT_SPACING_INPUT_UNITS, M_FINDER_PATTERN_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 McodeRead() a calibrated target image, the function will generate an error.

Before performing a read operation, certain control types might have to be set globally for the entire code context or individually for each code model in McodeControl(). When reading multiple occurrences of a Data Matrix code model, setting one or more of these values and reducing the search speed (using McodeControl() with M_SPEED) will produce more robust results.

Control type



For 2D code types only, improves the robustness of the operation.


To improve the robustness of the read operation for some code types, especially Data Matrix and Maxicode.

Note that MIL might have difficulty reading code occurrences if the cell size is less than 2 pixels, even if the size is specified.


For code types where M_ANY is not supported.


For code types where M_ANY is not supported.


This control type is essential for all code types, and the image will not be decoded if the foreground value is not correctly set.


If the code occurrences to read are not within 5° of the horizontal axis, and/or if the code occurrences have bearer bars.


For the M_BC412 code type, the string size must be specified.


For M_COMPOSITECODE and M_GS1_DATABAR code type, specifying the code sub-type can help increase the speed of read operations.

Note that if the image contains Structured Append sequence of separate but logically linked ECC 200 code occurrences, MIL will treat the code occurrences as separate, independent code occurrences.

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 identifier of the code context.


Specifies the 8-bit unsigned 1-band image buffer in which to search.

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.

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