3.1. Region

This module defines a factory method and a class. The class is an abstract wrapper which all Region classes extend. The factory will take a <no title> object and use that information to decide on the correct type of Region concrete subclass to load.

class Region.Region(config, path)

This is the abstract parent class of every Region type. Every concrete Region class should inherit from me. A Region represents a region of a screen. The region could be the entire screen or a subset of it.

Parameters:

  • config: a <no title> object

  • path: the path to the image file to load or None for an empty Region

count_color(color)

Parameters:

  • color: the color to count

Return: the number of times that color appeared in this region

debugprint(rect=(), verbose=False)

Print a text version of the region to stdout. sys.stdout.write is used instead of print in order to have finer control of the formatting.

find_colors(colors)

This will search this region and find rectangles made of pixels containing only values from the list provided.

Parameters:

  • colors: a list of color values to be included as part of the match

Return: a list of tuples of tuples. The “outer” tuple defines the rectangle of the match, while the “inner” tuples are the upper left and lower right corners of the rectangle

find_in_region(hay, rect=(), debug_match=False)

Treating myself as the needle try to find any places in the haystack we match.

Parameters:

  • hay: a Region that should be searched for instances of myself

  • rect: the points defining a rectangle that restricts the regions for which matches will be accepted

Return: a list containg tuples of x, y coordinates that are the upper left corner of the region matching me

find_regions(needle, rect=(), debug_match=False)

Treating myself as the haystack try to find any places that match the needle.

Parameters:

  • needle: an Region that should be found within myself

  • rect: the points defining a rectangle that restricts the region that should be searched

Return: a list containing tuples of x, y coordinates that are the upper left corner of the region matching the needle

from_array(array)

Load the contents of this image from a multidimensional numpy array.

Parameters:

  • array: the 2D numpy array for this image

get_row(ind)

Parameters:

  • ind: the row index (with row 0 being the top row counting down)

Return: an entire row of pixels as a Sequence

get_size()

Return: a tuple containing the height and width of this region

get_sub_region(upper_left, lower_right)

Get a region of this region defined by the two corners of a rectangle

Parameters:

  • upper_left: a row, col (tuple-like) of the upper left corner

  • lower_right: a row, col (tuple-like) of the lower right corner

get_value_at(x, y)

Return the value (usually the color) of the pixel at the given coordinates.

Parameters:

  • x: the column to check

  • y: the row to check

Return: the value of the given pixel/location

is_black(x, y)

Parameters:

  • x: the column to check

  • y: the row to check

Return: True if the pixel at the given row and column is black

is_white(x, y)

Parameters:

  • x: the column to check

  • y: the row to check

Return: True if the pixel at the given row and column is white

match_at(needle, corner)

Check at a particular location to see if we match the given needle.

Parameters:

  • needle: a Region to look for

  • corner: a tuple containing the upper left corner to start the match (tuple is in X,Y notation, not Row,Col)

Return: True if the needle is matched there, False otherwise

save_as_png(path)

Save this Region to the given path (overwriting an existing file if there is one) as a PNG file.

Parameters:

  • path: the location of the file to create

Return: True if successful, False otherwise

show(filename='/tmp/region.png')

Display the region on the screen using a standard unix viewer

show_async(filename=None)

Display the region on the screen using a standard unix viewer

use_exact_matching()

No matter the default, this region should expect only an exact match to be accepted.

Region.get_region(config, path=None, cache=None)

Use the <no title> object to determine the correct type of Region to return. If caching is turned on a combination of config object and path will return the same object each time.

Parameters:

  • config: a <no title> object

  • path: optionally the path to the image to load, can be None to get an empty image

  • cache: a boolean whether or not it’s acceptable to store this object in the cache or return one that’s already there

Return: a concrete instance of Region