Wait Image

Verb: waitImage

Available from: <Standard>

It waits for the analysis and recognition of an image on the screen or in a user interface control, returning a Boolean that informs whether the image was recognized or not.

User interface control is, on Windows, elements that allow the user to interact with an application. Controls can be buttons, data entry fields, menus and various other elements.

You can use this command to leverage surface automation capabilities to your script. For more information, see Actions for surface automation.


waitImage [--searchonscreen(Boolean)] --image(Image) --similarity(Numeric) --timeout(TimeSpan) --interval(TimeSpan) [--region(Rectangle)] --selector(ControlSelectors) [--forcerefresh(Boolean)] --id(String) --name(String) --innertext(String) --tagname(String) --xpath(String) --classname(String) --elementvalue(String) --controltype(Nullable<ControlTypes>) --index(Numeric) --control(Control) [--usetable(Boolean)] [--searchbycolumn(Boolean)] --searchcolumn(String) --searchvalue(String) --returncolumn(String) --row(Numeric) (Boolean)=success (Point)=absoluteposition (Point)=relativeposition


Script Designer Required AcceptedTypes Description
--searchonscreen Search on Screen Optional Boolean When enabled, it searches for the image on the entire screen.
--image Image Required Image Image used as a reference point to be located on the screen or in the user interface control.
--similarity Similarity Degree Required Number Degree of similarity of the image recognized on the screen or in the user interface control.
The number used ranges from 0 to 100. These values correspond to the percentage of similarity in the image.
--timeout Timeout Required Time Span Maximum waiting time to find the image on the screen or in a user interface control.
If no value is defined in the parameter of type timeout, the execution uses the context time defined by the Set Timeout command. If the script does not use this command, the default time is 5 seconds.
--interval Analysis Interval Required Time Span Time interval between analyzes performed on the screen or in the user interface control.
--region Region Optional Rectangle Rectangle indicating the region to be used to analyze and recognize the image.
The rectangle type variable is composed of four numbers separated by commas: the first two corresponding to the values of the region's initial pixel and the last two, to the height and width of the rectangle.
--selector Selector Required ControlSelectors Type of selector used to identify user interface controls. There are the following options:
  • Class and value
  • Class name
  • Id
  • Id and name
  • Inner text and control type
  • Instance
  • Name
  • Name and value
  • Type and index
  • Type and name
  • Vision
  • XPath
  • It is possible to use the recorder of IBM RPA Studio to map the controls and obtain the necessary information from the “Selector” parameter, in addition to inserting commands in the autocomplete script this parameter. The recorder is available in the upper toolbar on the platform.
    --forcerefresh Update Screen Cache Optional Boolean When enabled, it reads the screen again before executing the command, to identify new elements and update the screen cache.
    This identification is necessary for the command to work, in case there is any change on the screen.
    --id Id Only whenSelector is Id, IdAndName Text User interface control id.
    --name Name Only whenSelector is Name, NameAndValue, IdAndName, TypeAndName Text Name of the user interface control.
    --innertext Text Only whenSelector is InnerTextAndTag Text Internal text of the user interface control
    --tagname Element Type Only whenSelector is InnerTextAndTag Text Type of the element or tag.
    Example: “button”, “text box”.
    --xpath XPath Only whenSelector is XPath Text XPath of the user interface control.
    --classname Class Only whenSelector is ClassAndValue, ClassName Text User interface control class.
    --elementvalue Element Value Only whenSelector is ClassAndValue, NameAndValue Text Current value of the user interface control.
    --controltype Type Only whenSelector is TypeAndIndex, TypeAndName ControlTypes User interface control type:
  • Button
  • Check box
  • Child window
  • Combo box
  • Generic
  • Image
  • Label
  • List box
  • Menu bar
  • Menu item
  • Progress bar
  • Radio button
  • Scroll bar
  • Slider
  • Spinner
  • Status bar
  • Tab page
  • Tab panel
  • Table
  • Text box
  • Toggle button
  • Tree view
  • TreeTable
  • Window
  • --index Index Only whenSelector is TypeAndIndex Number Index of the user interface control.
    --control Control Only whenSelector is Instance Control Control instance.
    This variable is obtained using the command Search Control.
    --usetable Element in Table Optional Boolean When enabled, searches for an element within the table.
    --searchbycolumn Search by Column Optional Boolean When enabled, searches for the element through the column, not the row.
    --searchcolumn Column Only whenElement in Table is True Text Name or number of the column from which the element must be obtained.
    --searchvalue Value Only whenSearch by Column is True Text Value used to find the element in the table.
    --returncolumn Return Column Only whenSearch by Column is True Text Column that contains the control.
    --row Row Only whenSearch by Column is False Number Table row from which the element is obtained.


    Script Designer AcceptedTypes Description
    success Success Boolean Returns "True", if the image was found, or "False", otherwise.
    absoluteposition Absolute Position Point Returns the central position of the image in relation to the entire control.
    relativeposition Relative Position Point Returns the image's central position of a region within the control.


    The command Launch and Attach Window opens a window with the Paint application. Then, the command Wait Image is used to recognize the specified image within that application, based on the entire screen for analysis. Finally, the command Close Window is used to close the Paint application window.

    import --name paintImage --type "Image" --content iVBORw0KGgoAAAANSUhEUgAAAGAAAAASCAYAAACkctvyAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAACySURBVFhH7dghDsIwFMbxV46AmEOScCFA9hjYWm7RSuBIyLmJOUA+6EvFRAVrlnxi3y9p1if2zF8smRMR/Z1ZVFVSSnI8nW1+3G/ivZcQgs2t8vu1vVfX2dzqokN177jb29xq2z+reyUcbP7HpjwJhAHAGACMAcAYAIwBwBgAjAHAGACMAcAYAIwBwBgATRvFGPX1/tjJ96Wsba/LL5UWs01/wy5pTXtdLlfuBMBvAJTIF8bvrVOBOrmrAAAAAElFTkSuQmCC
    defVar --name paintWindow --type Window
    defVar --name waitingResult --type Boolean
    defVar --name absoluteImagePosition --type Point
    defVar --name relativeImagePosition --type Point
    launchWindow --executablepath "mspaint.exe" paintWindow=value
    // Wait for the informed image to be found.
    waitImage --searchonscreen  --image ${asset.paintImage} --similarity 100 --timeout 00:02:00 --interval 00:00:05 --selector "Vision" --forcerefresh  waitingResult=success absoluteImagePosition=absoluteposition relativeImagePosition=relativeposition
    logMessage --message "Execution Result: ${waitingResult}\r\nAbsolute Position: ${absoluteImagePosition}\r\nRelative Position: ${relativeImagePosition}" --type "Info"
    closeWindow --window ${paintWindow}
    // After executing the script, the result is:
    // Image recognition: True
    1. For the correct functioning of the script, an imported asset is used with the Import Asset command.
    2. It is necessary that the Paint application is installed on the computer to execute this script.


    The time interval entered in the parameters: ref (waitImage.timeout) and Analysis Interval must respect the range from 100 to 2147483647.

    The types of control to access the image to be analyzed can be obtained through the resource "WinSpy ++", available in IBM RPA Studio under "Tools -> Toolkit -> Windows Spy", or through IBM RPA Studio's recorder, available in the top navigation menu of the IBM RPA Studio screen. Data from the following controls can be obtained:

  • Class;
  • Id;
  • Text;
  • Name;
  • Element Type;
  • XPath.
  • See Also

  • Click
  • Click on Value
  • Control Screenshot
  • Expand Tree
  • Find Image by Similarity
  • Find Internet Explorer Browser
  • Find Pixel
  • Focus
  • Get Bounds
  • Get Control
  • Get Interval
  • Get Options
  • Get Table
  • Get Tree Nodes
  • Get Value
  • Offset Value
  • Scale Image
  • Select Row
  • Select Tab
  • Set Value
  • Verify Enabled
  • Verify If Visible
  • Wait Control
  • Wait for Control to Enable
  • Wait for Image Change