ReadIDCode
Decodes information contained in 1D and 2D barcodes and symbols, optionally verifies quality.
Note:
- The ReadIDCode function is only available on In-Sight vision systems using In-Sight firmware 4.x.x, and is not available on In-Sight vision systems running In-Sight firmware 5.1.0 and later. For a complete list of models and supported firmware versions, see Firmware Versions.
- Cognex recommends that the ReadIDMax function be used instead of the ReadIDCode function, which is a legacy function. The ReadIDMax function has enhanced performance capabilities.
ReadIDCodeInputs
Syntax: ReadIDCode(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Code Type,Decode Settings.Checksum,DecodeSettings.Omnidirectional,Decode Settings.Scanning,Decode Settings.Contrast,DecodeSettings.Symbol Format,Decode Settings.Rows,Decode Settings.Columns,DecodeSettings.Scale Tolerance,Decode Settings.Color,Decode Settings.Mirror,Decode Settings.Algorithm,DecodeSettings.Mode,DecodeSettings.Perspective,Decode Settings.QRMode,Verify,Timeout,Show)
Note: The Fixture and Region parameters must be defined
within the bounds of the image; otherwise, the function will return #ERR.
| Parameter |
Description |
|
Image
|
This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell referenced is A0, the cell containing the Image data structure returned by AcquireImage. For more information, see AcquireImage.
|
|
Fixture
|
Specifies the image coordinate system in which the input region is defined.
|
Row
|
The row offset in image coordinates.
|
|
Column
|
The column offset in image coordinates.
|
|
Theta
|
The orientation in image coordinates.
|
|
|
Region
|
Specifies the rectangular image region that can be translated and rotated.
|
X
|
The X offset of the origin in fixture coordinates.
|
|
Y
|
The Y offset of the origin in fixture coordinates.
|
|
High
|
The dimension along the region’s X-axis.
Note: The ReadIDCode function supports a maximum region size of 2048 pixels High by 2048 pixels Wide. If either the High or Wide parameters are set to a value larger than 2048 pixels, the function will return #ERR.
|
|
Wide
|
The dimension along the region’s Y-axis.
Note: The ReadIDCode function supports a maximum size of 2048 pixels High by 2048 pixels Wide. If either the High or Wide parameters are set to a value larger than 2048 pixels, the function will return #ERR.
|
|
Angle
|
The orientation in fixture coordinates.
|
|
|
Code Type
|
Specifies the type of 1D and 2D symbols to read.
Note:
- Decode Settings parameters that are not applicable to the selected Code Type will be grayed out.
- The decoding algorithm uses the Region.Angle parameter value in its initial image processing stage. If the barcode is perfectly horizontal in the image, an Angle of 0 will perform best when the Omnidirectional parameter is disabled. If the barcode is perfectly vertical in the image, the Region should be rotated +/- 90 degrees for best performance.
- All GS1 codes are supported. For more information, see gs1.org.
|
255 = Auto
|
Decodes by running all symbologies in the Region and selects the first symbol that decodes successfully, on every sheet update. Subsequent spreadsheet updates will attempt to decode the last successfully decoded Code Type first, before attempting other Code Types.
 See the order in which Code Types are attempted
- Last decoded Code Type, if any.
- Data Matrix
- RSS CC-A
- RSS CC-B
- PDF417
- QR Code
- MicroQRCode
- RSS 14 & Stacked
- RSS Limited
- UPC
- EAN
- Code 128
- POSTNET
- PLANET
- UPU-4 State
- Australia 4-State
- Japan 4-State
- USPS OneCode 4-State
- Code 39
- Code I2of5
- Code 93
- Codabar (NW-7)
Note: Auto will not decode PharmaCode barcodes.
|
|
-1 = Learn (Default)
|
Learns the code type. This parameter is re-populated with the Code Type that is first decoded.
Note: Learn will not decode PharmaCode barcodes.
Tip:
- Once a symbol is learned, the Code Type parameter displays that symbol's code type. To find out if you are running in learn mode, insert the GetLearned Vision Data Access function into an empty spreadsheet cell, referencing the ReadIDCode structure. If a 1 is returned, the function is in learn mode. For more information, see GetLearned(IDCode).
- Do not run in Learn mode if the symbol's format is expected to change - even if it is the same code type. The Learn setting remembers the format for the first symbol decoded (code type, polarity, format, module size, etc.). If any format of the new symbol changes from the learned code, even if the Code Type is the same, the read will fail. To un-learn the symbol format but keep the same code type, another code type must be selected before re-selecting the correct code type. To allow the ReadIDCode function to decode symbols with varying format, set the Code Type to Auto; choose a specific symbology if the symbol is not expected to change.
- When the Algorithm parameter is enabled, selectingLearn may increase the time to decode.
- Click herefor an example of how to allow the Code Type to relearn programmatically.
1. Create a Button in cell A1. 2. Insert the formula, If(A1,255,-1), in cell A2. 3. Create a ReadIDCode with no visible symbol in the image. 4. Reference the ReadIDCode's Code Type parameter to cell A2. 5. Click the button in cell A1 to have the ReadIDCode function relearn(unlearns then relearns).
|
|
0 = Code 39
|
Selects Code 39 reading (also known as Code 3 of 9 and BC39).
|
|
1 = Code 128
|
Selects Code 128 reading. Supports Code Sets A, B, and C barcodes.
|
|
2 = Code I2of5
|
Selects I2of5 reading (also known as Interleaved 2 of 5).
|
|
3 = UPC
|
Selects UPC (Universal Product Code)reading. Supports Version A (Regular version) and Version E (Zero-suppression version) UPC barcodes, as well as two- and five-character supplemental encodations.
|
|
4 = EAN
|
Selects EAN (European Article Numbering)reading. Supports EAN-8 and EAN-13 barcodes, as well as two- and five-character supplemental encodations.
|
|
7 = PharmaCode
|
Selects PharmaCode reading.
|
|
5 = POSTNET
|
Selects POSTNET reading.
|
|
6 = PLANET
|
Selects PLANET reading.
|
|
9 = RSS-14 & Stacked
|
Selects RSS-14 (Reduced Space Symbology)and RSS Stacked reading.
|
|
10 = RSS Limited
|
Selects RSS Limited reading.
|
|
12 = Codabar (NW-7)
|
Selects Codabar reading (also known as USD-4 and Code 2 of 7).
|
|
11 = Code 93
|
Selects Code 93 reading.
|
|
8 = UPU 4-State
|
Selects UPU 4-State reading.
|
|
13 = Australia Post 4-State
|
Selects Australia Post 4-State reading.
|
|
14 = Japan Post 4-State
|
Selects Japan Post 4-State reading.
|
|
15 = USPS OneCode 4-State
|
Selects USPS OneCode 4-State reading.
|
|
128 = Data Matrix
|
Selects Data Matrix reading.
Note:
- Use the Data Matrix Mode parameter to specify the type of Data Matrix symbol to read.
- When the Algorithm parameter is enabled, grids up to 144x144 are supported; when disabled, grids up to 48x48 are supported.
|
|
129 = QR
|
Selects QR Code reading.
Note: Use the QR Mode parameter to specify the type of QR symbol to read.
|
|
130 = RSS CC-A
|
Selects 2D CC-A (Composite Component)reading.
|
|
131 = RSS CC-B
|
Selects 2D CC-B (Composite Component)reading.
|
|
132 = PDF417
|
Selects PDF417 reading.
|
|
|
Decode Settings
|
Specifies setting to be used to decode 1D and 2D symbols.
Note: Decode Settings that are not applicable to the selected Code Type will be grayed out.
|
Checksum
|
Specifies whether the symbol will be validated to ensure reliability using an error-detection algorithm. Checksum only applies to symbols with optional checksum algorithms included in the symbol; each symbol has its own unique checksum algorithm. The type of checksum, if any, that is used depends on the code type selected.
|
0 = OFF (default)
|
Do not verify checksum.
|
|
1 = ON
|
Requires checksum to pass.
|
Note: Code 128, Code93, RSS, UPC and EAN barcodes are validated with a checksum regardless of the parameter selection. If Checksum is enabled for any other barcode, and no checksum is encoded, the read will fail.
|
|
Omnidirectional
|
Specifies the direction in which scan lines are projected within the Region in order to detect all of the elements in the barcode.An element refers to either a bar or space in a barcode. At least one scan line must project across every element of the barcode for a successful decode. For more information, see Scan Lines.
|
0 = OFF
|
Scan lines are projected in one direction to detect a barcode parallel to the Region.
|
|
1 = ON (default)
|
Scan lines are projected at various angles to detect a barcode that is rotated relative to the Region.
|
Note: Pharma Code barcodes will not decode correctly if rotated over 90° from the angle of the Region.
|
|
Scanning
|
Specifies the space, in pixels, between each scan line projected within the Region. When Fine is selected, the barcode is read with a high degree of reliability; when Coarse is selected the execution time is decreased. Any integer value between 1 and 255, up to the height of the Region, can be entered. For more information, see Scan Lines.
|
3 = Fine
|
|
12 = Medium (default)
|
|
48 = Coarse
|
Note: The Scanning parameter is disabled if Omnidirectional is ON for 1D symbols.
|
|
Contrast
|
Specifies the expected symbol contrast.
|
0 = Automatic (Default)
|
Selects an automatic contrast routine that computes a threshold level based on the grayscale image statistics.
|
|
16 = Low
|
For use with low contrast symbols.
|
|
32 = Normal
|
For use with normal contrast symbols.
|
|
64 = High
|
For use with high contrast symbols.
|
Note: The Contrast parameter is disabled for all Code Types other than Postal and RSS.
|
|
Symbol Format
|
Specifies the row and column format of the symbol. If Symbol Format is disabled (default), the symbol format will be determined automatically. When enabled, Rows and Columns must be specified.
Note: The Symbol Format parameter is not implemented.
|
|
Rows
|
Specifies the number of rows in the symbol.
Note: The Rows parameter is not implemented.
|
|
Columns
|
Specifies the number of columns in the symbol.
Note: The Columns parameter is not implemented.
|
|
Scale Tolerance
|
Specifies the percentage of scale change (0 to 50; default = 0) to tolerate while searching for the symbol.
Note: The Scale Tolerance parameter is not implemented.
|
|
Color
|
Specifies the color of the symbol.
|
0 = Black
|
The symbol is darker than the background.
|
|
1 = White
|
The symbol is lighter than the background.
|
Note: The Color parameter is only implemented for 1D RSS symbols.
|
|
Mirror
|
Specifies whether to mirror the symbol from left to right before attempting to decode it.
|
0 = No
|
Attempt to decode the symbol without mirroring it.
|
|
1 = Yes
|
Mirror the symbol before attempting to decode.
|
|
2 = Auto (default)
|
Automatically detects if the symbol needs to be mirrored before attempting to decode.
|
|
|
Algorithm
|
Specifies whether an advanced algorithm is used to improve reading accuracy.
Note: When Algorithm is enabled, 1D barcodes with minimum bar elements wider than 10 pixels may not read correctly.
|
0 = OFF
|
Do not use the advanced algorithm. When disabled, the function applies the algorithm used in the legacy ID functions. Using this algorithm may increase the decode speed, but maybe less accurate.
|
|
1 = ON (default)
|
Decode using the advanced algorithm. This algorithm is more accurate than the legacy algorithm, but decode speed may decrease. When enabled, Data Matrix and RSS symbols are decoded usingIDMax®.
|
|
|
Mode
|
Specifies the mode used to read specific symbols.
|
0 = Default
|
Do not attempt to read non-conformant Data Matrix symbols.
|
|
2 = Allow Non-Conformant Codes
|
Allow additional time to read non-conformant Data Matrix symbols, attempting additional, more robust decoding options.
Note:
- Auto. Learn or Data Matrix must be the selected Code Type to decode a Data Matrix symbol; Algorithm must also be enabled.
- Select this option if the modules in the Data Matrix symbol exhibit a halo or similar appearance.
|
|
3 = High Speed/High Contrast
|
Read high-contrast Data Matrix, RSS-14 and RSS Limited symbols. Using this selection can increase the decode speed. Do not select if the symbol is low-contrast, damaged or blurred.
Note:
- Learn must be the selected Code Type and Algorithm must be enabled.
- The High Speed/High Contrast option is designed to provide more repeatable decode times for some high-speed reading applications.Atypical use is reading high contrast ink jet codes where the mark quality varies from part-to-part.In these applications it is common to see significant variations in the amount of time necessary to decode each mark (i.e., poorly printed marks take 3-5 times longer to decode than well-printed marks).The High Speed/High Contrast option reduces the variations in decode time while still maintaining a high average speed.It is important to note that these benefits will not be seen on every application and proper testing should be performed to determine if this option is appropriate for you application.
|
|
|
Perspective
|
Specifies the decoding of Data Matrix and QR Code symbols with perspective distortion and optionally trains Data Matrix symbols for a known perspective distortion.
Note:
- Auto. Learn, Data Matrix or QR must be the selected Code Type to decode the Data Matrix or QR Code symbol with perspective distortion; Algorithm must also be enabled.
- When either Perspective or Train perspective is selected, quality verifications are not support.
|
0 = No perspective (default)
|
Decodes Data Matrix and QR Code symbols that have no perspective distortion.
|
|
3 = Perspective
|
Decodes Data Matrix and QR Code symbols with perspective distortion; the perspective distortion is estimated independently during model training and run time.
|
|
7 = Train perspective
|
Decodes Data Matrix symbols with a known perspective distortion. When Learn is the selected Code Type, the perspective is trained along with other "learned" attributes. At run time, the symbol is searched in a space where the perspective distortion in the input image is compensated using the learned attributes. This option requires that the run time symbol is placed on the same plane as that of the learn time symbol. This option allows for decoding even on severely damaged symbols with known perspective distortion. When the selected Code Type is "Auto", this option is equivalent to "3 = Perspective".
Tip: It is recommended that the sensor be mounted so the angle of incidence (the angle between the optical axis of the sensor and the normal vector of the plane on which the symbol is presented) is no more than 40 degrees and the resolution of the symbol be at least 5 pixels per cell.
|
|
|
QR Mode
|
Specifies the type of QR Code to read.
|
3 = QR Models 1 and 2
|
|
4 = MicroQR
|
|
6 = QR2 and MicroQR (Default)
|
|
7 = QR Model 1, QR Model 2 and MicroQR
|
|
|
|
Verify
|
Specifies whether the print
quality tests (also known as quality verification metrics) are performed. For more information, see ID.
|
0 = OFF (default)
|
Do not test quality.
|
|
1 = ON
|
Test quality and display the results in the spreadsheet.
|
Note:
- If the string cannot be decoded, then #ERR will be returned for all results that are automatically inserted into the spreadsheet.
- All Code Types except PharmaCode and RSS-Stacked support quality verification.
|
|
Timeout
|
Specifies the amount of time, in milliseconds(0 to 30000), that the function will search for a valid ID symbol before execution is halted and an #ERR is returned. Setting the value to 0 disables the setting and a timeout is not applied.
|
|
Show
|
Specifies the display mode for the ReadIDCode graphical overlay on the image.
|
0 = hide all (default)
|
The input region boundary will be hidden, except when the cell containing the ReadIDCode function is highlighted in the spreadsheet.
|
|
1 = result graphics only
|
The result graphics (boxes for DataMatrix and QR Code) will be displayed at all times.
|
|
2 = input and result graphics
|
The input graphics and result graphics will be displayed at all times.
Note: The Show parameter is only implemented for Data Matrix and QR Code symbols.
|
|
ReadIDCode Outputs
|
Returns
|
An IDCode data structure containing the decoded alphanumeric string, or #ERR if any of the input parameters are invalid.
|
|
Results
|
When the function is initially inserted into a cell, the decoded string will automatically appear in the adjacent cell. If the barcode or symbol cannot be decoded, then #ERR will be inserted.
|
ReadIDCodeVision Data Access Functions
If the Verify checkbox is disabled when the ReadIDCode function is initially created, then a single Vision Data Access function will be automatically inserted into the spreadsheet:
|
String
|
GetString(IDCode)
|
Returns the alphanumeric string encoded in the barcode or symbol. |
If the Verify checkbox is enabled when the ReadIDCode function is initially created, the additional Vision Data Access functions that are automatically inserted into the spreadsheet will depend on the selected Code Type.
Note: If the Verify checkbox is enabled after the ReadIDCode function is initially created, the additional Vision Data Access functions will not be automatically inserted into the spreadsheet. Also, the Verify checkbox must be enabled before the additional Vision Data Access functions will execute in the spreadsheet.
Additional data elements can be accessed using the ReadIDCode Vision Data Access functions. For more information, see IDCode.