Find image command

Finds an image (needle) on the device screen (haystack) and stores the coordinates for future commands. By default, the find image function searches for the image on the current screen.

Parameters

Name Type Possible values Description

Device ID*

Device

  

The device for this command. By default, this is the device under test (DUT).

Expected image (needle)*

Media

  

The image to search for. If you select an image from the Perfecto repository, the image must be a JPEG, PNG, or BMP file.

You can select a file that already resides in the Perfecto repository or select a file from your computer that is then uploaded to the Perfecto repository. To learn more about the Perfecto repository, see Manage the repository. Click the Select media link, browse to the file, and then click SELECT.

Search area (haystack)

String

all | body

Defines the screen region where to look for the needle.

Screen source

String

Primary | Camera

The source for retrieving the screen content, which can be a digital screen image (primary) or an analog screen image (camera).

Haystack top

String

  

The top value of the screen area where to search for the label.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

Consider reducing the resolution in very long scripts that result in large report files.
Haystack height

String

  

The height value of the screen area where to search for the label.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

Consider reducing the resolution in very long scripts that result in large report files.

Haystack left

String

  

The left value of the screen area where to search for the label.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

Consider reducing the resolution in very long scripts that result in large report files.

Haystack width

String

  

The width value of the screen area where to search for the label.

Values can be in pixels or in percentage of screen width (0-100). For percentage, use the % sign. Example: 20%

Default is to search the entire screen.

Consider reducing the resolution in very long scripts that result in large report files.

Needle top

String

  

The top value of the image area defining the needle. The value is in pixels. Default is the entire image.
Needle height

String

  

The height value of the image area defining the needle. The value is in pixels. Default is the entire image.

Needle left

String

  

The left value of the image area defining the needle. The value is in pixels. Default is the entire image.

Needle width

String

  

The width value of the image area defining the needle. The value is in pixels. Default is the entire image.

Timeout

Number

 

The time, in seconds, to wait for the label to appear.

For a dynamic screen, specify the expected waiting time for the label to appear. Example: page load time

The timeout contains the system analysis time. For this reason, consider specifying at least 20 seconds.

Timer accuracy

Number

Rough | Accurate

The timer accuracy level, where rough is normal accuracy (seconds) and accurate is sub-second (0.1 second).

To use this parameter, the Screen source parameter must be set to Camera.

Threshold

Number

  

The acceptable match level percentage, between 20 and 100.

Values that are too low can lead to a false positive result, while values that are too high can lead to a false negative result.

Duration

Number

  

The minimum time interval, in seconds, for a single analysis.

If the analysis operation takes less than the interval, wait the remaining time before the next analysis operation.

Interval

Number

 

The minimum time interval, in seconds, for a single analysis.

If the analysis operation takes less than the interval, wait the remaining time before the next analysis operation.

Backlight

String

  

The key sequence to perform the backlight operation.

Example: VOL_UP

For best practice, use a key that will not change the screen.

Scroll and search

String

False | True

Scrolls until the label is found. Scroll cannot be used together with a positive timeout value because the parameters dictate a different behavior when the needle is not found. When scrolling is enabled, the timeout must be zero.

Scroll results in a longer execution time.
Max scroll

Number

 

The maximum number of scroll actions to perform before returning.

Finding the label will stop the scrolling.

Effective values are in the range of 0-100.

Next

String

SWIPE_UP | SWIPE_DOWN | SWIPE_RIGHT | SWIPE_LEFT | UP | DOWN | RIGHT | LEFT

The key sequence to perform the scroll operation.

For more information see Swipe Gesture in Analysis Functions.

Match mode

String

Same size | Any size | Bounded size

The needle comparison method.

  • Same Size: Needle and haystack are from the same origin (device screen) and size. Matching is faster and simpler.

  • Any Size: Needle and haystack are either not from the same origin (needle is from another device or another source) or not in the same size (different ratio or size). Matching is slower and more complex.

    Selecting Any Size increases the analysis time. The timeout values should be increased accordingly.

  • Bounded Size: Same as Any Size with restrictions on possible needle sizes. This mode can decrease the Any Size analysis time by using apriori knowledge on needle sizes or by decreasing the size of a haystack.

Report

String

All | All on error | Screenshot | Screenshot on error | Text | None

The value to display in the report.

  • Screenshot: Displays screenshots.

  • Screenshot on error: Display screenshots only for actions in error.

  • Text: Displays screen text.

  • All: Displays screenshot and text.

  • All on error: Always displays text and but only displays screenshots for actions in error.

  • None: Display nothing.

Consider reducing the resolution in very long scripts that result in large report files.

Report image resolution

String

High | Medium | Low

The image resolution.

Consider reducing the resolution in very long scripts that result in large report files.

Grid label

String

  

The column name to be used for grid view in the report.

Selecting this parameter creates the grid report.

Visual relation direction

String

Left | Right | Above | Below | Left-Above | Left-Below | Right-Above | Right-Below | Inside

The direction of the related region, stored in memory from the last found needle, in relation to the searched needle.

  • Left: The related region is to the left of the searched needle.

  • Right: The related region is to the right of the searched needle.

  • Above: The related region is above the searched needle.

  • Below: The related region is below the searched needle.

  • Left-Above: The related region is to the left and above the searched needle.

  • Left-Below: The related region is to the left and below the searched needle.

  • Right-Above - The related region is to the right and above the searched needle.

  • Right-Below: The related region is to the right and below to the searched needle.

  • Inside: The searched needle is inside the related region boundaries of the related region.

For more information, see Visual Relations.

Visual relation inline

String

Horizontal | Vertical

The search area is in-line with the related region, stored in memory from the last found needle.

For more information, see the Visual Relations series.

  • Horizontal: The needle is within the height (top to button) boundaries of the related region

  • Vertical: The needle is within the width (left to right) boundaries of the related region

Needle bound

Number

  

The ratio in percentage by which the original needle width may vary. The ratio is defined as a (100 - specified percentage) / 100.

Needle sizes to be checked by the analysis will be limited to the range from original needle width multiplied by the ratio to the original needle width divided by the ratio.

To use this parameter, Match mode must be bounded size.

Haystack area

Number

  

The size of haystack to be used for the analysis. The haystack image will be scaled before being analyzed so its area does not exceed the specified value. Haystack images that do not exceed the value will stay unchanged.

To use this parameter, Match mode must be set to Bounded size.

Horizontal alignment

String

None | Left | Center | Right

The horizontal alignment, where:

  • None does not check for horizontal alignment

  • Left indicates that the needed should be left-aligned

  • Right indicates that the needle should be right-aligned

  • Center indicates that the needle should be center-aligned
Horizontal alignment accuracy

String

  

The amount of allowed accuracy to still match the required alignment. For example, if 10% is used and the target is located at position 15 out of 320, thenn the validation succeeds.

Vertical alignment

String

  

The vertical alignment, where:

  • None does not check for vertical alignment

  • Top indicates that the needed should be top-aligned

  • Bottom indicates that the needle should be bottom-aligned

  • Center indicates that the needle should be center-aligned

Vertical alignment accuracy

String

  

The amount of allowed accuracy to still match the required alignment. For example, if 10% is used and the target is located at position 15 out of 320, then the validation succeeds.

Comment

String

  

Adds a comment to the script

On-fail Result*

Condition

Ignore | Break | Continue | Abort | Catch

The behavior when the command fails.

* Mandatory parameter