IMAQ Read Data Matrix Barcode 3 VI

Download PDF

Updated2023-02-21
16 minute(s) read

Owning Palette: Instrument Readers
Requires: NI Vision Development Module

Locates and then reads the value encoded in a Data Matrix barcode. You can compare the decoded data to a reference string or check whether the data contains a specific pattern. Many of the options of this VI allow for automatic detection of Data Matrix barcode properties or determine which methods the VI should use to locate and decode the Data Matrix barcode. However, selecting specific properties and methods for these options will greatly increase the performance of the VI.

Examples

Supported Image Types

8-bit unsigned grayscale 16-bit unsigned grayscale 32-bit RGB 16-bit signed grayscale 64-bit RGB 32-bit HSL

IMAQ Read Data Matrix Barcode 3

Data Matrix Search Options is a cluster that contains the options to use when searching for Data Matrix codes in the image.

Rotation Mode specifies the amount of Data Matrix code rotation the VI should allow for. The following values are valid:

Unlimited (0)	The VI allows for unlimited rotation
0 Degrees (1)	The VI allows for 0 degrees of rotation
90 Degrees (2)	The VI allows for 90 degrees of rotation
180 Degrees (3)	The VI allows for 180 degrees of rotation
270 Degrees (4)	The VI allows for 270 degrees of rotation

Skip Location?, if TRUE, specifies that the VI should assume that the Data Matrix code occupies the entire image, or the entire search region. The VI skips the location phase, moving immediately to extraction and decoding. If FALSE (default), the VI does not make any assumptions about the percentage of the image occupied by the Data Matrix code.

Edge Threshold specifies the minimum contrast a pixel must have in order to be considered part of a matrix cell edge. The lower this value, the more potential edge candidates the VI will examine during the location phase. Setting this value too low will decrease the performance of the VI because the VI will examine too many potential edge candidates. Setting this value too high may also decrease the performance of the VI by removing valid edge candidates, making location more difficult. Setting this value too high may also cause the VI to fail to identify a Data Matrix barcode because all edge candidates are eliminated.

Demodulation Mode specifies the mode the VI should use to demodulate (determine which cells are ON and which cells are OFF) the Data Matrix code. The following values are valid:

Auto-detect (-2)	(Default) The VI tries each demodulation mode and use the one which decodes the Data Matrix code within the fewest iterations and utilizing the least amount of error correction.
Histogram (0)	The VI uses a histogram of all of the cells to calculate a threshold. This threshold determines if a cell is on or off. This is the fastest method, but it requires images with consistent levels of contrast in the matrix.
Local Contrast (1)	The VI examines each of the cell's neighbors to determine if the cell is on or off. This method is slower, but works with images that have inconsistent levels of contrast.
Combination (2)	The VI uses the histogram of the cells to calculate a threshold. For cells with pixel values that are sufficiently below or above this threshold, the VI will use the threshold to determine if the cell is on or off. If the cell pixel values are close to the threshold, the VI will use the Local Contrast method to determine if the cell is on or off. This method is slower, but works with Data Matrix codes that have extremely low cell fill percentages or gross print growth errors.
All (3)	The VI tries Histogram, Local Contrast, and Combination, stopping once one mode is successful.

Cell Sample Size specifies the sample size, in pixels, the VI should take to determine if each cell is ON or OFF.

Auto-detect (-2)	(Default) The VI tries each sample size and use the one which decodes the Data Matrix code within the fewest iterations and utilizing the least amount of error correction.
1×1 (1)	The VI will use a 1×1 sized sample from each cell.
2×2 (2)	The VI will use a 2×2 sized sample from each cell.
3×3 (3)	The VI will use a 3×3 sized sample from each cell.
4×4 (4)	The VI will use a 4×4 sized sample from each cell.
5×5 (5)	The VI will use a 5×5 sized sample from each cell.
6×6 (6)	The VI will use a 6×6 sized sample from each cell.
7×7 (7)	The VI will use a 7×7 sized sample from each cell.

Cell Filter Mode specifies the mode the VI uses to determine the pixel value for each cell.

Note If Cell Sample Size is 1×1, then the value of the sample pixel determines the pixel value for the cell.

The following values are valid:

Auto-detect (-2)	The VI tries all filter modes and uses the one that decodes the Data Matrix code within the fewest iterations and utilizing the least amount of error correction.
Average (0)	The VI sets the pixel value for the cell to the average of the sampled pixels.
Median (1)	The VI sets the pixel value for the cell to the median of the sampled pixels.
Central Average (2)	The VI sets the pixel value for the cell to the average of the pixels in the center of the cell sample.
High Average (3)	The VI sets the pixel value for the cell to the average value of the half of the sampled pixels with the highest pixel values.
Low Average (4)	The VI sets the pixel value for the cell to the average value of the half of the sampled pixels with the lowest pixel values.
Very High Average (5)	The VI sets the pixel value for the cell to the average value of the ninth of the sampled pixels with the highest pixel values.
Very Low Average (6)	The VI sets the pixel value for the cell to the average value of the ninth of the sampled pixels with the lowest pixel values.
All Filters (8)	The VI tries each filter mode, starting with Average and ending with Very Low Average, stopping once a filter mode decodes correctly.

Skew Degrees Allowed specifies the amount of skew in the code the VI should allow for. The default is 5 degrees.

Maximum Iterations specifies the maximum number of iterations before the VI stops looking for the code. The default is 500.

Initial Search Vector Width specifies the number of pixels the VI should average together to determine the location of an edge. You may need to increase this value when the Data Matrix code has cells with a low fill percentage. The default width is 5 pixels.

Data Matrix Description Options is a cluster that contains the Data Matrix code description options to use when searching for Data Matrix codes in the image.

Aspect Ratio specifies the ratio of the width of a cell of the Data Matrix code (in pixels) divided by the height of a cell of the Data Matrix code (in pixels). Set this value to 0 (default) to indicate that the VI should determine the aspect ratio.

Rows specifies the number of rows in the Data Matrix code. Set this value to 0 (default) to indicate that the VI should determine the number of rows.

Columns specifies the number of columns in the Data Matrix code. Set this value to 0 (default) to indicate that the VI should determine the number of columns.

Rectangle specifies if the Data Matrix code is square (default) or rectangular. If both Rows and Columns are non-zero, the VI ignores this setting.

ECC specifies the ECC used for the Data Matrix code. The following values are valid:

Auto-detect (-2)	(Default) Sets the VI to determine the barcode ECC automatically.
ECC 000 (0)	Sets the VI to read Data Matrix codes of ECC 000 only.
ECC 050 (50)	Sets the VI to read Data Matrix codes of ECC 050 only.
ECC 080 (80)	Sets the VI to read Data Matrix codes of ECC 080 only.
ECC 100 (10)	Sets the VI to read Data Matrix codes of ECC 100 only.
ECC 140 (14)	Sets the VI to read Data Matrix codes of ECC 140 only.
ECC 000-140 (19)	Sets the VI to read Data Matrix codes of ECC 000, ECC 050, ECC 080, ECC 100, and ECC 140 only.
ECC 200 (20)	Sets the VI to read Data Matrix codes of ECC 200 only.

Barcode Polarity specifies the data-to-background contrast for the Data Matrix code. The following values are valid:

Auto-detect (-2)	(Default) Sets the VI to determine the code polarity automatically.
Black On White (0)	Sets the VI to read codes with dark data on a bright background.
White On Black (1)	Sets the VI to read codes with bright data on a dark background.

Cell Fill Percentage specifies the fill percentage for a cell that is in the ON state. The following values are valid:

Auto-detect (-2)	(Default) Sets the VI to determine the Data Matrix code cell fill percentage automatically.
< 30% (0)	Sets the VI to read Data Matrix codes with a cell fill percentage of less than 30 percent.
>= 30% (1)	sets the VI to read Data Matrix codes with a cell fill percentage greater than or equal to 30 percent.

Minimum Border Integrity % specifies the minimum percentage of the matrix border the VI should expect in the Data Matrix code. During the location phase, the VI will ignore possible matrix candidates that do not have at least this level of border integrity.

Mirror Mode specifies if the Data Matrix code appears normally in the image or if the Data Matrix code appears mirrored in the image. The following values are valid:

Auto-detect (-2)	(Default) Sets the VI to automatically determine if the code is mirrored.
Normal (0)	Sets the VI to read codes that appear normally in the image.
Mirrored (1)	Sets the VI to read codes that appear mirrored in the image.

Image is a reference to the source image.

ROI Descriptor is a descriptor that defines the region of interest within which the Data Matrix code is located. The first contour of the ROI must be a rectangle, rotated rectangle, or convex polygon. If Skip Location? of the Data Matrix Search Options input is TRUE, a convex polygon contour has an additional constraint of being four-sided. If the ROI descriptor is empty or not connected, the entire image is considered to be the region.

Global Rectangle contains the coordinates of the bounding rectangle.

Contours are each of the individual shapes that define an ROI.

	ID refers to whether the contour is the external or internal edge of an ROI.
	Type is the shape type of the contour.
	Coordinates indicates the relative position of the contour.

Prepare for Grading? specifies if the VI should make calculations needed to prepare to grade the Data Matrix code. The following are valid values:

Do Not Prepare (0)	(Default) Does not make any preparatory calculations. Attempts to grade the Data Matrix code will generate an error.
Prepare for AIM Grading (1)	Prepares the image for grading using the AIM Print Quality metrics.

error in (no error) describes the error status before this VI or function runs. The default is no error. If an error occurred before this VI or function runs, the VI or function passes the error in value to error out. This VI or function runs normally only if no error occurred before this VI or function runs. If an error occurs while this VI or function runs, it runs normally and sets its own error status in error out. Use the Simple Error Handler or General Error Handler VIs to display the description of the error code. Use error in and error out to check errors and to specify execution order by wiring error out from one node to error in of the next node.

	status is TRUE (X) if an error occurred before this VI or function ran or FALSE (checkmark) to indicate a warning or that no error occurred before this VI or function ran. The default is FALSE.
	code is the error or warning code. If status is TRUE, code is a nonzero error code. If status is FALSE, code is 0 or a warning code.
	source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning. The default is an empty string.

Data Matrix Size Options is a cluster that contains the code size options to use when searching for codes in the image.

Data Matrix Size specifies the size range (in pixels) for the code in the image. The VI will ignore potential barcode candidates that are sized outside of this range.

	Minimum Size specifies the minimum size (in pixels) of the code in the image. Setting this value to 0 (the default) indicates the VI should never exclude a barcode candidate because it is too small.
	Maximum Size specifies the maximum size (in pixels) of the code in the image. Setting this value to 0 (the default) indicates the VI should never exclude a barcode candidate because it is too large.

Quiet Zone Width specifies the expected minimum size of the quiet zone, in pixels. The VI will ignore barcode candidates whose quiet zones are smaller than this value.

Advanced Options is an array of advanced options.

Option specifies the option the VI uses when reading the data matrix. The following values are valid:

Line Detection (0)	Enables the line detection algorithm. Use Line Detection if the image has a cluttered background.
Highlight Filter (1)	Enables the highlight filter. Use the Highlight Filter if the image is blurry or has low contrast.
Aggressive (2)	Enables aggressive reading. Aggressive reading returns the decoded code immediately without minimizing detected errors.

Value specifies whether to use the selected option. A Value greater than 0 enables the option.

Image (duplicate) is the reference to the image that contains the Data Matrix code.

Data Matrix Report is a cluster of information about the code that the VI read.

	Found? indicates if the VI located (TRUE) or failed to locate (FALSE) a data matrix code in the image.
	Binary? indicates if the Data Matrix code contains encoded non-ASCII binary data (TRUE) or ASCII text (FALSE).
	Data is the encoded information that the VI read.
	Bounding Box is an array of five points that define the boundary of the Data Matrix code in the image.
	Errors Corrected is the number of erasures that the VI corrected using inherent error correction.
	Erasures Corrected is the number of erasures that the VI corrected using inherent error correction.
	Aspect Ratio indicates the aspect ratio of the data matrix code in the image.
	Rows is the number of rows in the Data Matrix code.
	Columns is the number of columns in the code.
	ECC is the type of the Data Matrix code.
	Barcode Polarity indicates the polarity of the Data Matrix code.
	Cell Fill Percentage indicates the cell fill percentage of the code.
	Border Integrity is the percentage of the Data Matrix border that appears correctly in the image.
	Mirrored? indicates if the code appeared mirrored (TRUE) or normally (FALSE) in the image.
	Minimum Edge Strength indicates the minimum strength of the edges the VI used to find the coarse location of the Data Matrix code in the image. Use this value as a guide for setting the Edge Threshold value in the Barcode Search Options control.
	Demodulation Mode indicates the demodulation mode the VI used to locate the code. If Demodulation Mode is set to Auto-Detect in Data Matrix Search Options, this output indicates the recommended demodulation mode for this image.
	Cell Sample Size indicates the cell sample size the VI used to locate the Data Matrix barcode. If Cell Sample Size is set to Auto-Detect in Data Matrix Search Options, this output indicates the recommended cell sample size for this image.
	Cell Filter Mode indicates the cell filter mode the VI used to locate the barcode. If Cell Filter Mode is set to Auto-Detect in the Data Matrix Search Options, this output indicates the recommended cell filter mode for this image.
	Iterations indicates the number of iterations the VI took in attempting to locate the Data Matrix code. If this number is equal to Maximum Iterations in Data Matrix Search Options and the VI failed to locate the code, you may be able to locate the code by increasing Maximum Iterations.

Mean Light is the mean of the light lobe from the final grid-point histogram of the symbol under test.

error out contains error information. If error in indicates that an error occurred before this VI or function ran, error out contains the same error information. Otherwise, it describes the error status that this VI or function produces. Right-click the error out indicator on the front panel and select Explain Error from the shortcut menu for more information about the error.

	status is TRUE (X) if an error occurred or FALSE (checkmark) to indicate a warning or that no error occurred.
	code is the error or warning code. If status is TRUE, code is a nonzero error code. If status is FALSE, code is 0 or a warning code.
	source describes the origin of the error or warning and is, in most cases, the name of the VI or function that produced the error or warning. The default is an empty string.

Examples

Refer to the following for an example that uses this VI.

LabVIEW\examples\Vision\Barcodes\Read Data Matrix Code.vi

NI Vision for LabVIEW

Table of Contents

IMAQ Read Data Matrix Barcode 3 VI

Supported Image Types

Examples