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.
Syntax
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
Inputs
| 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:
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:
|
| --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. |
Outputs
| 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. |
Example
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.
Remarks
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: