Image-Based Automation

Sometimes you need to automate a click action based on image information. For this reason, Ranorex Recorder provides an optional way to capture image related mouse actions. To activate image based recording, simply check the 'Image-Based' checkbox in the Recorder's toolbar during a recording session.

: 'Image-Based' recording activated

Now, move the mouse pointer over a certain GUI element. Ranorex highlights the last accessible UI element, and also highlights a recognized image within the GUI element.

: Image-based recording within calendar control

To turn off image-based recording, uncheck the checkbox or press the shortcut key 'I'.

Note: Hot key functionality has to be activated by first using the master hot key 'SCROLL'.
Read more about hot key use during Ranorex recording.

After stopping the recording session the actions table contains an image based mouse click action which is indicated by the 'Image' keyword. In addition the related repository item stores a snapshot at the time of recording.

Generally, the repository item saves an image to specify where to search for the image region which is specified by the image based mouse action in the recorder's actions table.

: Separation of 'where' and 'what' to search for

To alter the settings of an image-based automation action, open the property group 'Image-Based Location' within property grid.

Image-Based Location Settings
Advanced Options	Use the property group to set advanced image search options like 'Clipping' or 'Best Match' If 'Best Match' is set to true, the result position with the highest similarity is used for validation. If is set to false, the first available result position will be used of the validation. The first one is more accurate and the second one is faster.
Preprocessing	Defines preprocessing steps that can be performed on an image before search (e.g. GrayScale or DownSize)
Screenshot Name	Specifies the name of the screenshot where to search for.
Selection Rectangle	Defines the image selection region and what to search for
Similarity	Specifies the minimum similarity that the image region to search for needs to have in common with the image in order to be considered a match

To set up the default values for image based recording open the 'Settings' dialog and the 'Imaging' tab.

: Settings dialog for image based recording

Image Editor

Use the context menu item 'Edit Location ...' to open the image editor and to change the click location options.

The editor provides a more detailed view of the captured image information. In addition it offers some useful features to change the image rectangle to be searched for.

: Click location dialog to change the settings of image based mouse actions

Generally the edit mode is indicated via the yellow highlighted editor box and it allows to use the RanoreXPath expressions as a query. After indicating the completion of editiing RanoreXPath by pressing the <Enter> key, the result is shown within the spy tree as follows:

Toolbar Shortcuts
	Image Based	Specifies whether the click is based on image information or not
	Select Image Find Region	Specifies the region to search for within the image
	Select Click Location	Defines the click position related to the searched region
	Autoselect Image Find Region	Helps to specify the search region within the image
	Zoom Out	Zooms out
	Zoom 100%	Switches to 1:1 view
	Zoom In	Zooms in
	Capture New Screenshot	Captures a new screenshot from the related repository item

Use the drop-down combo boxes to specify whether a mouse action should be performed relative to the image region found or not.

: Set relative or absolute mouse action location

If the captured screenshot has to be updated click the 'Capture New Screenshot' toolbar button. Also, every newly created screenshot is automatically added to the image list of the related repository item so it's available for other image-based validation or automation actions.

: Add a new image or select an existing image to specify where to search

Online User Guide
download as: PDF (20.3MB)

Ranorex Tutorial
(PDF file, 13.5MB)

Online API Documentation