gamedriver package¶

Submodules¶

Module contents¶

class gamedriver.Box(left: int, top: int, right: int, bottom: int)¶

Bases: NamedTuple

A rectangular region defined by two points (left, top) and (right, bottom).

bottom: int¶: Alias for field number 3

left: int¶: Alias for field number 0

right: int¶: Alias for field number 2

top: int¶: Alias for field number 1

class gamedriver.Point(x: int, y: int)¶

Bases: NamedTuple

An (x, y) coordinate.

x: int¶: Alias for field number 0

y: int¶: Alias for field number 1

exception gamedriver.ReadImageError(path: str)¶: Bases: Exception

gamedriver.get_center(box: Box) → Point¶

Gets the center of a box.

Parameters:: box (Box)
Returns:: Point

gamedriver.get_img_path(rel_path: str) → str¶

Gets the path to an image.

The argument path is relative to the base directory settings.Settings.img_path. Argument images should be without a file extension, and will be given the extension settings.Settings.img_ext.

Parameters:: rel_path (str) – Path to the image from the base directory, without a file extension
Returns:: Full path to the image
Return type:: str

Examples

# If `img_path` is "/home/user/projects/project/project/img" and
# `img_ext` is ".png"
gd.get_img_path("buttons/confirm")
# "/home/user/projects/project/project/img/buttons/confirm.png"

gamedriver.get_pixel(x: int, y: int) → tuple[int, int, int]¶

Gets a pixel from the device screen.

The pixel should be in color. Note that it should be in the BGR color space.

Parameters:

x (int)
y (int)

Returns:

Pixel in the BGR color space

Return type:

tuple[int, int, int]

Examples

# Check whether a pixel at (10, 20) is red enough
px = gd.get_pixel(10, 20)
is_red = px[0] < 25 and px[1] < 25 and px[2] > 225

gamedriver.get_screen(*, grayscale=False) → Mat | ndarray¶

Gets the device screen.

Calls the user-provided settings.Settings.get_screen function. Note that screens should be in the BGR color space.

That function is augmented by specifying whether there should be a conversion to grayscale. This is for functions with is_grayscale parameters that if set expect argument images to be grayscale.

Parameters:

grayscale (bool, optional) – Whether to return the screen in grayscale. Defaults to False.

Returns:

Array representing the screen [height, width,: channel]

Return type:

cv.typing.MatLike

Examples

Save a screenshot:

cv.imwrite("fname.png", cv.cvtColor(gd.get_screen(), cv.COLOR_BGR2RGB))

Use grayscale template matching with an already-grayscale template, and a custom full path to the template:

box = gd.match_template(
    gd.get_screen(grayscale=True),
    "my/path/buttons/confirm-gray.png",
    is_grayscale=True,
)

gamedriver.locate(img: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None) → Box | None¶

Locates an image on the screen.

Performs a template match where the haystack image is the device screen and the needle image is specified by the relative path instead of the full path.

See gamedriver.match_template().

Parameters:: img (str | cv.typing.MatLike) – Image or relative path to the image to search for with no file extension
Returns:: Box | None

Examples

box = gd.locate("buttons/confirm")

gamedriver.locate_all(img: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None) → Iterator[Box]¶

Locates all images on the screen.

See locate().

Yields:: Iterator[Box]

Gets the best match of a template in an image.

Parameters:

haystack (str | cv.typing.MatLike) – Image or path to image to be searched
needle (str | cv.typing.MatLike) – Image or path to image to search for
bounding_box (Box, optional) – Restricts the region of the haystack image to be searched. Defaults to None (search entire haystack).
convert_to_grayscale (bool, optional) – Whether color images should be converted to grayscale before matching, which improves performance at the expense of accuracy. Is fine in most cases. Defaults to True.
is_grayscale (bool, optional) – Whether the images are already grayscale. Defaults to False.
method (int, optional) – OpenCV match method. See cv.match_template. Defaults to cv.TM_SQDIFF_NORMED.
threshold (float, optional) – Threshold value specifying how good potential matches must be to be considered matches. See thresholding in OpenCV template matching. Defaults to 0.05 for sum of square differences (SSD) OpenCV match methods (e.g. cv.TM_SQDIFF_NORMED) and 0.8 for all others.

Returns:

The best match, or None if no matches were good enough.

Return type:

Box | None

Examples

Get the best match:

box = gd.match_template("haystack.png", "needle.png")

Match with stricter accuracy by using color matching and tightening the threshold value (SSD match method => closer to 0 is stricter):

box = gd.match_template(
    "haystack.png",
    "needle.png",
    convert_to_grayscale=False,
    threshold=0.01,
)

If the images are already grayscale:

box = gd.match_template(
    "haystack-gray.png",
    "needle-gray.png",
    is_grayscale=True,
)

Get the best match in a specific region:

box = gd.match_template(
    "haystack.png",
    "needle.png",
    bounding_box=gd.Box(left=0, top=0, right=540, bottom=960),
)

gamedriver.match_template_all(haystack: str | Mat | ndarray, needle: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None) → Iterator[Box]¶

Matches all instances of a template in an image.

See match_template().

Yields:: Iterator[Box] – Matches

Examples

Get a list of matches:

boxes = list(
    gd.match_template_all("friends.png", gd.get_img_path("buttons/add"))
)

Tap each match:

for box in gd.match_template_all(
    "friends.png", gd.get_img_path("buttons/add")
):
    gd.tap_box(box)

gamedriver.open_img(path: str, *, is_grayscale=False) → Mat | ndarray¶

Opens an image.

Parameters:

path (str) – Full path to the image
is_grayscale (bool, optional) – Whether the image is already grayscale. Defaults to False.

Returns:

Image in the BGR color space

Return type:

cv.typing.MatLike

Raises:

gamedriver.ReadImageError –

gamedriver.swipe(x1: int, y1: int, x2: int, y2: int, duration_ms=100) → None¶

Swipes from point (x1, y1) to (x2, y2).

Calls the user-provided settings.Settings.swipe function.

Parameters:

x1 (int)
y1 (int)
x2 (int)
y2 (int)
duration_ms (int, optional) – Duration of the swipe in milliseconds. Defaults to 100.

gamedriver.tap_box(box: Box) → None¶

Taps a box.

Parameters:: box (Box)

gamedriver.tap_img(img: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None) → Box | None¶

Taps the center of an image if found.

See gamedriver.locate().

gamedriver.tap_img_when_visible(img: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None, timeout_s=30) → Box | None¶

Waits until an image is visible, then taps the center of it.

See gamedriver.locate() and gamedriver.wait_until_img_visible().

gamedriver.tap_img_when_visible_after_wait(img: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None, timeout_s=30, seconds=1) → Box | None¶

Waits until an image is visible, waits for a time, then taps it.

See gamedriver.locate() and gamedriver.wait_until_img_visible().

Parameters:: seconds (int, optional) – Time to wait after the image becomes visible before tapping it. Defaults to 1.

gamedriver.tap_img_while_other_visible(img: str | Mat | ndarray, other: str | Mat | ndarray, *, bounding_box: Box = None, other_bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None, timeout_s=5, frequency_s=1) → bool¶

Taps an image while another is visible.

See gamedriver.locate() and gamedriver.wait_until_img_visible().

Parameters:

img (str | cv.typing.MatLike) – Image to tap
other (str | cv.typing.MatLike) – Image to check the visibility of
frequency_s (int, optional) – How often the image to tap should be tapped, in seconds. Defaults to 1.

Returns:

True if the image to check disappeared within the timeout and: tapping was stopped, or False if the image to check remained after the timeout and tapping was continued until the end.

Return type:

bool

gamedriver.tap_img_while_visible(img: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None, timeout_s=5, frequency_s=1) → bool¶

Taps an image while it is visible.

See tap_img_while_other_visible().

Parameters:: img (str | cv.typing.MatLike) – Image to check the visibility of and tap

gamedriver.tap_xy(x: int, y: int) → None¶

Taps a point (x, y).

Calls the user-provided settings.Settings.tap_xy function.

Parameters:

x (int)
y (int)

gamedriver.wait(seconds=1.0) → None¶

Sleeps for a time, taking wait adjustments into account.

Waits can be adjusted by settings.Settings.wait_scale and settings.Settings.wait_offset.

Parameters:: seconds (float, optional) – Base time to sleep for. Defaults to 1.

gamedriver.wait_until_img_visible(img: str | Mat | ndarray, *, bounding_box: Box = None, convert_to_grayscale=True, is_grayscale=False, method=1, threshold: float = None, timeout_s=30) → Box | None¶

Waits until an image is visible.

Polls to check whether the image is visible every settings.Settings.refresh_rate_ms milliseconds.

See gamedriver.locate().

Parameters:: timeout_s (int, optional) – Timeout in seconds. Defaults to 30.
Returns:: The match, or None if there is no match within timeout_s.
Return type:: Box | None

gamedriver.settings module¶

class gamedriver.settings.Settings¶

Bases: TypedDict

GameDriver configuration.

get_screen: Callable[[], Mat | ndarray]¶: Returns the screen [height, width, channel] in the BGR color space. Required for template matching that uses the device screen.

img_ext: str¶: File extension for template images. Defaults to “.png”.

img_path: str¶: Path to the template image directory. Recommend using an absolute path. Defaults to “”.

refresh_rate_ms: int¶: How often the screen is checked in explicit wait operations. For example when using gamedriver.wait_until_img_visible(). Defaults to 1000 (1s).

swipe: Callable[[int, int, int, int, int | None], None]¶: Swipes from (x1, y1) to (x2, y2) in duration_ms milliseconds. Required for all swipe interactions.

tap_xy: Callable[[int, int], None]¶: Taps an (x, y) coordinate. Required for all tap-based interactions.

wait_offset: float¶: How much to add to gamedriver.wait() s. Defaults to 0.

wait_scale: float¶: How much to multiply gamedriver.wait() s by. Defaults to 1.

gamedriver.settings.set_settings(s: Settings) → None¶

Sets multiple settings.

A convenient way to set multiple settings at once. Only settings set in this way will be affected - existing settings that are not set remain unaffected.

Parameters:: s (Settings) – Partial settings dictionary with the settings to be set

gamedriver package¶

Submodules¶

Module contents¶

gamedriver.settings module¶

gamedriver.logger module¶

GameDriver

Navigation

Related Topics