Python API


exception RPA.Images.ImageNotFoundError

Bases: Exception

Raised when template matching fails.


Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class RPA.Images.Images

Bases: object

Images is a library for general image manipulation. For image-based desktop automation, use the RPA.Desktop library.


The coordinates used in the library are pairs of x and y values that represent pixels. The upper left corner of the image or screen is (0, 0). The x-coordinate increases towards the right, and the y-coordinate increases towards the bottom.

Regions are represented as tuples of (left, top, right, bottom). For example, a 400 by 200-pixel region in the upper left corner would be (0, 0, 400, 200).

Template matching

Template matching refers to an operation where the (potential) location of a smaller image is searched from a larger image. It can be used for verifying certain conditions or locating UI elements for desktop or web automation.


The default installation depends on Pillow library, which is used for general image manipulation operations.

For more robust and faster template matching, the library can use a combination of NumPy and OpenCV. They can be installed by opting in to the cv dependency:

pip install rpaframework[cv]


Robot Framework

The Images library can be imported and used directly in Robot Framework, for instance, for capturing screenshots or verifying something on the screen.

Desktop automation based on images should be done using the corresponding desktop library, i.e. RPA.Desktop.

*** Settings ***
Library    RPA.Images

*** Keywords ***
Should show success
    [Documentation]    Raises ImageNotFoundError if success image is not on screen
    Find template on screen    ${CURDIR}${/}success.png

Save screenshot to results
    [Documentation]    Saves screenshot of desktop with unique name
    ${timestamp}=      Get current date    result_format=%H%M%S
    Take screenshot    filename=${OUTPUT_DIR}${/}desktop_${timestamp}.png


from RPA.Images import Images

def draw_matches_on_desktop(template):
    lib = Images()
    screenshot = lib.take_screenshot()

    matches = lib.find_template_in_image(screenshot, template)
    for match in matches:
        lib.show_region_in_image(screenshot, match)"matches.png")
crop_image(image, region, filename=None)

Crop an existing image.

  • image – Image to crop

  • region – Region to crop image to

  • filename – Save cropped image to filename

find_template_in_image(image, template, region=None, limit=None, tolerance=None) → List[RPA.core.geometry.Region]

DEPRECATED Use keyword Find from library RPA.Recognition instead Attempt to find the template from the given image.

  • image – Path to image or Image instance, used to search from

  • template – Path to image or Image instance, used to search with

  • limit – Limit returned results to maximum of limit.

  • region – Area to search from. Can speed up search significantly.

  • tolerance – Tolerance for matching, value between 0.1 and 1.0


List of matching regions


ImageNotFoundError – No match was found

find_template_on_screen(template, **kwargs) → List[RPA.core.geometry.Region]

DEPRECATED!! use RPA.Desktop.Find Element instead Attempt to find the template image from the current desktop. For argument descriptions, see find_template_in_image()

get_pixel_color_in_image(image, point)

Get the RGB value of a pixel in the image.

  • image – image to get pixel from

  • point – coordinates for pixel or Point object


Get the RGB value of a pixel currently on screen.


point – coordinates for pixel or Point object

show_region_in_image(image, region, color='red', width=5)

Draw a rectangle onto the image around the given region.

  • image – image to draw onto

  • region – coordinates for region or Region object

  • color – color of rectangle

  • width – line width of rectangle

show_region_on_screen(region, color='red', width=5)

Draw a rectangle around the given region on the current desktop.

  • region – coordinates for region or Region object

  • color – color of rectangle

  • width – line width of rectangle

take_screenshot(filename=None, region=None) → PIL.Image.Image

DEPRECATED Use keyword RPA.Desktop.Take Screenshot instead Take a screenshot of the current desktop.

  • filename – Save screenshot to filename

  • region – Region to crop screenshot to

wait_template_on_screen(template, timeout=5, **kwargs)

DEPRECATED!! use RPA.Desktop.Wait For Element instead Wait for template image to appear on current desktop. For further argument descriptions, see find_template_in_image()


timeout – Time to wait for template (in seconds)

class RPA.Images.RGB(red: int, green: int, blue: int)

Bases: object

Container for a single RGB value.

blue: int = None
classmethod from_pixel(value)

Create RGB value from pillow getpixel() return value.

green: int = None

Approximate (perceived) luminance for RGB value.

red: int = None
class RPA.Images.TemplateMatcher(opencv=False)

Bases: object

Container class for different template matching methods.

match(image, template, limit=None, tolerance=None)

Attempt to find the template in the given image.

  • image – image to search from

  • template – image to search with

  • limit – maximum number of returned matches

  • tolerance – minimum correlation factor between template and image


list of regions that match criteria

property tolerance
RPA.Images.chunks(obj, size, start=0)

Convert obj container to list of chunks of size.

RPA.Images.clamp(minimum, value, maximum)

Clamp value between given minimum and maximum.


Convert obj to instance of Pillow’s Image class.