Working with Character Collections

Character collection searches in Eggplant Functional are a type of image search you can use when optical character recognition (OCR) cannot recognize text written in custom fonts on a system under test (SUT). Unusual backgrounds on the SUT can also make OCR unable to read text—even if it's written in a common font. Character collection searches work by matching text on your SUT with images of characters that you capture and save in your suite.

Use the information below to create character collections, then use those character collections in your SenseTalk scripts:

• Step by Step: Character Collection Capture
• Image Searches Using a Character Collection

Step by Step: Character Collection Capture

Complete the following steps to initiate and complete a Character Collection capture session:

1. Connect to a SUT. When you've connected, the SUT appears in the Viewer window.

2. Start a Character Collection capture session:

   • From the main menu, select Control > Start Session > Character Collection Capture Session.
   • From the Viewer window, click Start Session > Character Collection Capture Session.

3. In the Viewer window, click each individual character that you want to capture from the SUT screen.

4. After you finish capturing all of the characters, click End Session.

5. Name your session, then press Enter. The session name field is already highlighted for ease of renaming.

6. Highlight the session you just created (or a different one, if you want to generate characters from a different session), then click Open Session.

7. For each character you captured, adjust the characters using the guidelines shown below. Use the following screenshot for guidance. The list of characters collected for this session is located at the bottom of the right pane.

   

   The open session shows a magnified representation of the captured character. If OCR identifies a character at the click point, it sets the capture area around that character and automatically names the captured character. Character images are given names that identify the character they represent. For example, each image is given a name, such as lower_a, upper_A, digit_1, or char_0xAB (for characters other than letters and digits). If the character field is empty, it is labeled as NO CHARACTER. If an image for the specified character already exists in the character collection, or earlier in this capture session, the image name is shown in red (the image name is the string located next to the Character value.

   Adjust the captured characters as follows:

   • To adjust the view of the SUT window on the left to offer a better perspective for screen actions, click the Zoom In button to enlarge the screen size or the Zoom Out button to reduce the screen size. Note that this is a view change only; it does not affect your captured characters.

   • To resize the image, drag the edges or corners of the Capture Area, or press Alt + arrow (Option + arrow on Mac) keys. Add the shift key to resize the Capture Area in 10-pixel increments.

     note

     When resizing the rectangles, keep the rectangles close to the same height. For lowercase letters, do not adjust the rectangle to extend very far below the bottom of the letter.

   • Select the Search Type from the drop-down menu. The default choice for a selected character will generally work well. See The Image Viewer: Searching & Properties for complete information.

   • If the character shown next to Character does not match the view of the SUT window on the left, you can manually change that character. Note that when you change that character, it also changes the string located next to the changed Character value.

   • To move through the list of captured characters, use the arrow keys in the lower left or click the Next or Done buttons.

   • Character images are given names that identify the character they represent. For example, each image is given a name, such as lower_a, upper_A, digit_1, or char_0xAB (for characters other than letters and digits).

   • Select the Skip checkbox if you want to skip and not generate any of the collected characters.

8. Click Generate Images, name your character collection, then click Proceed after you decide your characters are named and configured correctly.

   note

   If you need to make corrections before continuing, click Cancel and make further adjustments to your characters.

   Eggplant Functional generates a character for each character captured during this Character Collection capture session. The only characters not generated are those characters marked as skipped. Eggplant Functional stores these generated images as an image collection using a file name you specify. This image collection resides in the images folder of your suite. You can always add more images to this and other character collections by creating and generating images into a new character collection, then moving images from that new collection into an existing collection. See the Images Pane for more information.

Now the characters from this Character Collection capture session are all available for you as Character Collections in the Images pane of the Suite window. You can use these characters with the ReadCharacters() Function when modifying existing scripts or adding new scripts.

Image Searches Using a Character Collection

To perform an image search using a character collection, use the characters property, which reads a list of image names from a character collection. The following examples use several SenseTalk commands with the characters property to complete character collection searches for model number #A1705.

Example:

click (characters: "#A1705", CharacterCollection: "modelnumber") // Uses the modelnumber character collection to complete the search.

Example:

If ImageFound(characters: "#A1705", CharacterCollection:"modelnumber") // Search for a specific model number.
  click (characters:"#A1705", CharacterCollection:"modelnumber") // Click the model number if the search is successful.
End If

Example:

If ImageFound(characters: "#A1705", CharacterCollection:"modelnumber") // Search for a specific model number.
  MoveTo (characters:"#A1705", CharacterCollection:"modelnumber") // Move the mouse cursor to the center of the character collection images.
End If

You can use the characters property along with the properties listed below to improve your searches. See the ReadCharacters() Function for more information.

• asList: When asList is on (asList:Yes), the ReadCharacters() function returns a list of strings, one for each group of recognized characters.
• characterPriority: This string contains priority characters, in high-to-low order. The default setting is ";:.". This setting controls which character is recognized if two character images are found in the same location. For example, using characterPriority:"OC" gives the "O" character image a higher priority than the "C"character image. The result is that the ReadCharacters function uses the letter "O" rather than the letter "C" if both the O and C images are found at the same location on the screen.
• minimumVerticalOverlap: This value sets the minimum overlap, in pixels, allowed for two characters to be considered to be on the same line. If the two characters overlap more than the minimumVerticalOverlap value, the function considers these characters to reside on the same line.
• maximumHorizontalOverlap: This value sets the maximum overlap, in pixels, allowed for adjacent characters to be considered as occupying the same space. If two adjacent characters overlap more than this setting, the ReadCharacters function considers these characters to be occupying the same space.
• maximumAdjacentGap: This value sets the maximum gap, in pixels, allowed between two adjacent characters. This setting assumes no space between characters. If two adjacent characters reside further apart than this setting, the ReadCharacters function considers these characters to be non-adjacent characters.
• maximumSpaceGap: This value sets the maximum gap, in pixels, for an implied space to exist between two characters. If two characters reside closer together than this setting, the ReadCharacters function does not consider these characters to be separated by a space.
• spaceWidth: This value sets the nominal width, in pixels, of a space character. The ReadCharacters function uses this setting to determine the number of spaces returned for wide space gaps.

You can also use other Image Properties to improve your character collection searches.