ReadText

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

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 VerifyTextif the string is known.The string will be read faster and be more accurate.For more information, see VerifyText.
  • If speed is notneeded for your application, enable ScaleTolerance parameter, since minor variations in size can degrade results significantly.
  • If your stringis found in the wrong location or not found at all, retry with Confusing Background parameter enabled.
  • If the wrong characteris being read, switch the Reading Mode parameter from Speed to Accuracy.Accuracy is better at distinguishing between charactersand gives a more accurate score.If the character is still being misread,open your trained fontand investigate the two confusing characters; they may have been trainedpoorly.For more information, see OCV/OCR Font Training Dialog.
  • If you are readinga string that always has spaces in the same place then add spaces to theField 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 spreadsheetcell that contains a valid Image data structure.By default, the cell referenced isA0 which contains the Image data structure returned by AcquireImage.For more information, see AcquireImage.

Fixture

Specifies the image coordinate system inwhich the input region is defined.

Row

The row offset.

Column

The column offset.

Theta

The orientation.

Region

Specifies the rectangular image region thatcan 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 datastructure containing a trained font.

Field String

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

  • (A to Z)
  • (ato 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 containthe same number of positions as there are characters in the string forthe 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 positionin the string.However, an individual position in theField String can be limited toconsider only a subset of possible characters at that position.This increasesoverall performance and reliability because characters that are not possibleat 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 alphabeticaland numerical

0123456789ABCDEF

h

Hexadecimal, lowercase alphabeticaland numerical

0123456789abcdef

O

Octal

01234567
Note:
  • To restrict a positionin a Field String to a singlecharacter, simply enter that character.The character must have been trainedin the font and cannot be one of the pre-defined FieldString entries listed above, unless it has been remapped usingthe FieldDefinitions parameter.
  • To read a stringcontaining a space, include the space in the FieldString.ReadText will not read a space if the corresponding Field String entry in that positionis an asterisk (*).

ClosedField StringExample 1

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

ClosedField StringExample 2

The font contains only numeric characters0-9 and /.If the Field Stringis NN/NN/NN, only numeric characters will be considered in the first andsecond, fourth and fifth, and seventh and eighth positions.Only the forwardslash (/) character will be considered in the third and sixth positions.

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

Field Definitions
  • Optionally, the FieldDefinitions setting can be used to create user-defined entriesfor the FieldString.When included in the FieldString, these entries restrict the list of valid characters atthe positions in which they are inserted.
  • Multiple FieldDefinitions can be used, separated by a semicolon (;).
  • Characters listed for a FieldDefinitions entry must be contained in the font.For example: #=123is 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 theField Definitions parameter willremap the list of valid characters in the new definition.

ClosedField Definitions Example 1

If the value of FieldDefinitions is #=123;$=3456;%=789, and the FieldString is #$%*******, then the only characters that will be validin the first position will be 1, 2, or 3.The only valid characters inthe 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 thefourth through tenth positions.

ClosedField Definitions Example 2

If the value of FieldDefinitions is #=123;$=3456;%=789, A=A, and the FieldString is #$%******A, then the only characters that will be validin the first position will be 1, 2, or 3.The only valid characters inthe 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 thefourth through ninth positions.Onlythe 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 eachcharacter.ReadText will fail any character with a match score below Accept Thresh and fail the string.

Difference Accept

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

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

Tune

Adjusts the scale of the character modelsin the referenced Font data structure from 50% to 200%.Matchscores are maximized when the character models are as close as possibleto the size of the characters to read.Enable Tuneonly when the difference between the size of the character models andthe characters to be read exceeds ±5%.

Tuning is a one-time operation that usessignificant processing time.After running the jobonce with Tune enabled, openthe spreadsheet and disable Tuneto save processing time during subsequent job runs.

0 = OFF (default)

Does not adjust the scale.
1 = ON

Adjusts the scale of the charactermodels to maximize the match score.

Reading Mode

Specifies whether an advanced algorithm isused to improve reading accuracy.

Note: Because ofbackground variations, occasionally selecting Speed will produce higherscores than when Accuracy is selected.Base selection on application.
Tip: The AcceptThresh parameter value may need to be lowered when Accuracy is selected due to strictscoring.

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 imageare being confused with the text string.This is especially useful ifother features within the image are being mistaken for the beginning ofthe string.

0 = OFF (default)

No other features within the imageare being confused with the text string.

1 = ON

Other features within the image arebeing confused with the text string.

Scale Tolerance

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

0 = OFF (default)

Do not allow for small variationsin character scale.

1 = ON

Allow for small variations in characterscale.

Timeout

Specifies the amount of time, in milliseconds(0 to 30000), that the functionwill 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 overlaythe image.

0 = hide all (default)

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

1 = result graphics only

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

2 = input and result graphics

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

ReadTextOutputs

Returns

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

Results

When ReadText is initially inserted intoa 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 referencedText data structure.

StringPass

GetPassed(Text)

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

Char

GetChar(Text, Index0, [Index1])

Returns the indexed character in the referencedText data structure.When an optional Index1parameter is 1, returns the secondhighest scoring character.

Score

GetScore(Text, Index0, [Index1])

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

Passed

GetPassed(Text, Index)

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

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

Angle

GetAngle(Text)

Returns the angle between the text stringin 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 indexedcharacter in the referenced Text data structure.

Row

GetRow(Text,Index)

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

Wide

GetWide(Text,Index)

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

Copyright © 1999 - 2019  |  Cognex Corporation  |  All Rights Reserved.

In-Sight® Explorer Help  |  2019 May 07  |  Revision: 5.7.2.5