ReadText

Reads a text string in an image region using character models in a user-trained font.

Note:
  • The TrainFont, ReadText and VerifyText functions are only available on In-Sight vision systems using In-Sight firmware 4.x.x, and are 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 OCRMax function be used instead of the ReadText, TrainFont and VerifyText functions, which are legacy functions. The OCRMax function has enhanced performance capabilities.
Tip:
  • Always use VerifyText if the string is known. The string will be read faster and be more accurate. For more information, see VerifyText.
  • If speed is not needed for your application, enable ScaleTolerance parameter, since minor variations in size can degrade results significantly.
  • If your string is found in the wrong location or not found at all, retry with Confusing Background parameter enabled.
  • If the wrong character is being read, switch the Reading Mode parameter from Speed to Accuracy. Accuracy is better at distinguishing between characters and gives a more accurate score. If the character is still being misread, open your trained font and investigate the two confusing characters; they may have been trainedpoorly. For more information, see How to Train a Font for the ReadText and VerifyText Functions.
  • If you are reading a string that always has spaces in the same place then add spaces to the Field String.

ReadTextInputs

Syntax: ReadText(Image,Fixture.Row,Fixture.Column,Fixture.Theta,Region.X,Region.Y,Region.High,Region.Wide,Region.Angle,Region.Curve,Font,Field String,FieldDefinitions,AcceptThresh,DifferenceAccept,Tune,Reading Mode,Confusing Background,Scale Tolerance,Timeout,Show)

Parameter Description

Image

This argument must reference a spreadsheet cell that contains a valid Image data structure. By default, the cell referenced is A0 which contains 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.

Column

The column offset.

Theta

The orientation.

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.

Wide

The dimension along the region's y-axis.

Angle

The orientation, in fixture coordinates.

Curve

The angular deviation between the region's x-axis and the opposing boundary line.

Font

Cell reference to a Font data structure containing a trained font.

Field String

Specifies the number of characters contained in the character string. A Field String entry can be any alphanumeric character found in the text entry dialog, including:

  • (A to Z)
  • (a to z)
  • (0 to 9)
  • dashes(-)
  • dots (.)
  • spaces ( )

Each character in the FieldString corresponds to an indexed field position between 0 and 31. The Field String must contain the same number of positions as there are characters in the string for the read to pass. By default, each position in the FieldString is represented as an asterisk (*) character, or alphanumeric"wildcard."This means that any character is valid at any position in the string. However, an individual position in the Field String can be limited to consider only a subset of possible characters at that position. This increases overall performance and reliability because characters that are not possible at a position will not be considered during a read.

The pre-defined FieldString entries are:

Field String Entry Description Valid Characters

*

Wildcard

Any trained character in the font.

N

Numeric

0123456789

A

Uppercase alphabetical

ABCDEFGHIJKLMNOPQRSTUVWXYZ

a

Lowercase alphabetical

abcdefghijklmnopqrstuvwxyz

H

Hexadecimal, uppercase alphabetical and numerical

0123456789ABCDEF

h

Hexadecimal, lowercase alphabetical and numerical

0123456789abcdef

O

Octal

01234567
Note:
  • To restrict a position in a Field String to a single character, simply enter that character. The character must have been trained in the font and cannot be one of the pre-defined FieldString entries listed above, unless it has been remapped using the Field Definitions parameter.
  • To read a string containing a space, include the space in the FieldString. ReadText will not read a space if the corresponding Field String entry in that position is an asterisk (*).

ClosedField String Example 1

If the FieldString is **********AN, any character in the font is valid in the first 10 Field String positions. But in the 11th position, only uppercase alpha characters will be considered during the read. And in the 12th position, only numeric characters will be considered.

ClosedField String Example 2

The font contains only numeric characters 0-9 and /. If the Field String is NN/NN/NN, only numeric characters will be considered in the first and second, fourth and fifth, and seventh and eighth positions. Only the forward slash (/) character will be considered in the third and sixth positions.

But if the Field String is NN/NN/AA, the read would return #ERR because the font does not contain any alpha characters.

Field Definitions
  • Optionally, the Field Definitions setting can be used to create user-defined entries for the FieldString. When included in the FieldString, these entries restrict the list of valid characters at the positions in which they are inserted.
  • Multiple Field Definitions can be used, separated by a semicolon (;).
  • Characters listed for a Field Definitions entry must be contained in the font. For example: #=123 is valid if 1, 2, and 3 are included in the user-trained font. However,#=123 would be invalid if 1, 2, and 3 are not included in the font.
Note: Using one of the predefined entries (*, A, a, N, H, h, O) in the Field Definitions parameter will remap the list of valid characters in the new definition.

ClosedField Definitions Example 1

If the value of Field Definitions is #=123;$=3456;%=789, and the FieldString is #$%*******, then the only characters that will be valid in the first position will be 1, 2, or 3. The only valid characters in the second position will be 3, 4, 5, or 6. And in the third position, only 7, 8, or 9 will be valid. Any character in the font is valid in the fourth through tenth positions.

ClosedField Definitions Example 2

If the value of Field Definitions is #=123;$=3456;%=789, A=A, and the FieldString is #$%******A, then the only characters that will be valid in the first position will be 1, 2, or 3. The only valid characters in the second position will be 3, 4, 5, or 6. And in the third position, only 7, 8, or 9 will be valid. Any character in the font is valid in the fourth through ninth positions. Only the A character will be considered in the tenth position because the Field Definition A=A remaps the predefined FieldString entry.

Accept Thresh

Specifies the minimum acceptable match score(0 to 100; default = 70) for each character. ReadText will fail any character with a match score below Accept Thresh and fail the string.

Difference Accept

The minimum difference required between the match scores of the highest scoring character and the second highest scoring character (0 to 20; default = 0).

  • To find the second-highest scoring character, use: GetChar(Text,Index, 1)
  • To find the score for the second-highest scoring character, use: GetScore(Text,Index, 1)

Tune

Adjusts the scale of the character models in the referenced Font data structure from 50% to 200%. Matchscores are maximized when the character models are as close as possible to the size of the characters to read. Enable Tune only when the difference between the size of the character models and the characters to be read exceeds ±5%.

Tuning is a one-time operation that uses significant processing time. After running the job once with Tune enabled, open the spreadsheet and disable Tune to save processing time during subsequent job runs.

0 = OFF (default)

Does not adjust the scale.
1 = ON

Adjusts the scale of the character models to maximize the match score.

Reading Mode

Specifies whether an advanced algorithm is used to improve reading accuracy.

Note: Because of background variations, occasionally selecting Speed will produce higher scores than when Accuracy is selected. Base selection on application.
Tip: The Accept Thresh parameter value may need to be lowered when Accuracy is selected due to strict scoring.

0 = Speed (default)

Do not use the advanced algorithm. Using this algorithm may increase the decode speed, but may be less accurate.

1 = Accuracy

Decode using the advanced algorithm. This algorithm is more accurate, but decode speed may decrease.

Confusing Background

Specifies if other features within the image are being confused with the text string. This is especially useful if other features within the image are being mistaken for the beginning of the string.

0 = OFF (default)

No other features within the image are being confused with the text string.

1 = ON

Other features within the image are being confused with the text string.

Scale Tolerance

Specifies a tolerance of ± 10% to compensate for small variations in character size.

0 = OFF (default)

Do not allow for small variations in character scale.

1 = ON

Allow for small variations in character scale.

Timeout

Specifies the amount of time, in milliseconds(0 to 30000), that the function will search for a valid text string 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 which ReadText graphics overlay the image.

0 = hide all (default)

All graphics will be hidden, except when the cell containing the ReadText function is highlighted in the spreadsheet.

1 = result graphics only

The character segments with their corresponding labels will be displayed at all times.

2 = input and result graphics

The image region and the character segments with their corresponding labels will be displayed at all times.

ReadTextOutputs

Returns

A Text data structure containing the character string that was read, or #ERR if any of the input parameters are invalid.

Results

When ReadText is initially inserted into a cell, a result table is created in the spreadsheet.

ReadTextVision Data Access Functions

The following Vision Data Access functions are automatically inserted into the spreadsheet to create the result table. For more information, see VerifyText.

String

GetString(Text)

Returns the text string in the referenced Text data structure.

StringPass

GetPassed(Text)

Returns the pass/fail status of the entire string in the referenced Text data structure.

Char

GetChar(Text, Index0, [Index1])

Returns the indexed character in the referenced Text data structure. When an optional Index1 parameter is 1, returns the second highest scoring character.

Score

GetScore(Text, Index0, [Index1])

Returns the match score (0 to 100) for the indexed character in the referenced Text data structure. If the optional Index1 parameter is 1, returns the score of the second highest scoring character.

Passed

GetPassed(Text, Index)

Returns the pass/fail status of the indexed character in the referenced Text data structure. If no Index parameter is specified, returns the pass/fail status of the entire string.

The following data elements can also be accessed using Text Vision Data Access functions:

Angle

GetAngle(Text)

Returns the angle between the text string in the Text data structure and the horizontal axis of the Image data structure.

Col

GetCol(Text,Index)

Returns the column coordinate (in pixels)of the indexed character in the referenced Text data structure.

High

GetHigh(Text,Index)

Returns the height (in pixels) of the indexed character in the referenced Text data structure.

Row

GetRow(Text,Index)

Returns the row coordinate (in pixels) of the indexed character in the referenced Text data structure.

Wide

GetWide(Text,Index)

Returns the width (in pixels) of the indexed character in the referenced Text data structure.