ReadText
Reads a text string in an image region using character models in a user-trained font.
- 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.
- 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 | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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. |
|||||||||||||||||||||||||
Specifies the image coordinate system in which the input region is defined.
|
|||||||||||||||||||||||||
Specifies the rectangular image region that can be translated and rotated.
|
|||||||||||||||||||||||||
Cell reference to a Font data structure containing a trained font. |
|||||||||||||||||||||||||
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:
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:
Note:
|
|||||||||||||||||||||||||
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.
|
|||||||||||||||||||||||||
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. |
|||||||||||||||||||||||||
The minimum difference required between the match scores of the highest scoring character and the second highest scoring character (0 to 20; default = 0).
|
|||||||||||||||||||||||||
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.
|
|||||||||||||||||||||||||
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.
|
|||||||||||||||||||||||||
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.
|
|||||||||||||||||||||||||
Specifies a tolerance of ± 10% to compensate for small variations in character size.
|
|||||||||||||||||||||||||
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. |
|||||||||||||||||||||||||
Specifies which ReadText graphics overlay the image.
|
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. |