A rectangular screen area for finding images or colors, capturing an image, or drawing an outline. Coordinates use pixels on the current horizontal/vertical axes; after scaling and offsets, only the part inside the screen is used. Read its dimensions with x, y, width, height = region.
Syntax
Region(x, y, width, height, /, scale="fixed", anchor="none", scale_param=ScaleParam())
How coordinates adapt between full screens: fixed keeps pixels; auto scales X by width and Y by height; width or height scales both axes by that dimension. Uses the macro's source screen size, without rotating axes or using app window size.
Reference position for adapting coordinates: none (top-left), center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right. auto chooses the nearest edge or center.
How coordinates adapt between full screens: fixed keeps pixels; auto scales X by width and Y by height; width or height scales both axes by that dimension. Uses the macro's source screen size, without rotating axes or using app window size.
Reference position for adapting coordinates: none (top-left), center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right. auto chooses the nearest edge or center.
Return the screen width of the device that created this macro, adapted to current screen orientation, when available.
Syntax
Region.macro_width()
Returns
Number? — Macro source screen width, or None when unavailable.
Example
macro_w = Region.macro_width()
Region.macro_height
Static Method
Return the screen height of the device that created this macro, adapted to current screen orientation, when available.
Syntax
Region.macro_height()
Returns
Number? — Macro source screen height, or None when unavailable.
Example
macro_h = Region.macro_height()
Region.find
Method
Find one occurrence of the template in this region. Retry until found or timeout; timeout=0 scans once. Screen capture must be ready. ScreenCapture.cache_on() makes searches reuse one captured image until cache_off(); automatic reuse otherwise lasts up to 100 ms. Use auto_cache_off() for the newest available image, at the cost of more capture work.
Requested scans per second while waiting, limited to 1-60. Actual speed depends on recognition time.
Optional · Positional or named
Default:3.0
Returns
MatchList — One Match per input template, in input order, when any is found; some may have found=False. An empty MatchList if none is found before timeout.
Find one sampled pixel closest to the target color in this region. Each red, green and blue channel must differ by no more than tolerance; the smallest largest-channel difference wins. Retry until found or timeout; timeout=0 scans once. Requires ready screen capture.
Maximum wait in milliseconds. Omitted, zero or negative values scan once. A scan already running may finish after this time.
Optional · Positional or named
Default:0
toleranceNumber
Allowed per-channel RGB delta from 0 to 255.
Optional · Positional or named
Default:0
rateNumber
Requested scans per second while waiting, limited to 1-60. Actual speed depends on recognition time.
Optional · Positional or named
Default:3
intervalNumber
Requested distance in pixels between tested positions; at least 1. Smaller values inspect more pixels and may take longer. The distance may increase automatically for large areas.
Optional · Positional or named
Default:10
Returns
Match — A Match with at most one Point in point, or found=False and an empty point list if no sampled pixel matches or capture is unavailable.
Example
scan = Region(80, 220, 420, 520)
hit = scan.find_color("#FF4CAF50", tolerance=8, interval=4)
if hit.found:
click(hit.point[0], random=0)
Region.find_any_color
Method
Find any of the target colors in this region using the RGB tolerance rule of find_color. Return at most one best sampled point per found color, in input order. Retry until any color is found or timeout; timeout=0 scans once. Requires ready screen capture.
Maximum wait in milliseconds. Omitted, zero or negative values scan once. A scan already running may finish after this time.
Optional · Positional or named
Default:0
toleranceNumber
Allowed per-channel RGB delta from 0 to 255.
Optional · Positional or named
Default:0
rateNumber
Requested scans per second while waiting, limited to 1-60. Actual speed depends on recognition time.
Optional · Positional or named
Default:3
intervalNumber
Requested distance in pixels between tested positions; at least 1. Smaller values inspect more pixels and may take longer. The distance may increase automatically for large areas.
Optional · Positional or named
Default:10
Returns
Match — A Match with one best Point per found color in point, in input order. found=False and an empty point list if none matches or capture is unavailable.
Example
colors = ["#FF0000", "#00FF00", "#0000FF"]
hit = Region.full_screen().find_any_color(colors, tolerance=6)
if hit.found:
click(hit, random=0)
Region.find_multi_color
Method
Find all sampled pixels matching one target color using the RGB tolerance rule of find_color. A list or tuple of colors raises an error. Retry until at least one point is found or timeout; timeout=0 scans once. Requires ready screen capture.
Maximum wait in milliseconds. Omitted, zero or negative values scan once. A scan already running may finish after this time.
Optional · Positional or named
Default:0
toleranceNumber
Allowed per-channel RGB delta from 0 to 255.
Optional · Positional or named
Default:0
rateNumber
Requested scans per second while waiting, limited to 1-60. Actual speed depends on recognition time.
Optional · Positional or named
Default:3
intervalNumber
Requested distance in pixels between tested positions; at least 1. Smaller values inspect more pixels and may take longer. The distance may increase automatically for large areas.
Optional · Positional or named
Default:10
Returns
Match — A Match with matching sampled Points in point, closest color first. found=False and an empty point list if none matches or capture is unavailable.
Example
hit = Region(80, 220, 420, 520).find_multi_color("red", tolerance=4, interval=3)
if hit.found:
first = hit.point[0]
hit.highlight(color="yellow", auto_hide_ms=800)
Region.wait
Method
Wait until the template disappears from this region. If timeout is omitted, only one scan pass is performed.
Requested scans per second while waiting, limited to 1-60. Actual speed depends on recognition time.
Optional · Positional or named
Default:3.0
Returns
Match — The latest Match: found=False means the image is absent; found=True means it was still present when waiting ended. Never None. Requires ready screen capture; unavailable capture can also report found=False.
Example
region = Region(0, 0, 1080, 2400)
result = region.wait("loading", 8000)
MacroPanel.notify(str(result))
Region.wait_any
Method
Wait until any template in the list disappears from this region. If timeout is omitted, only one scan pass is performed.
Requested scans per second while waiting, limited to 1-60. Actual speed depends on recognition time.
Optional · Positional or named
Default:3.0
Returns
MatchList — The latest Match for each input template, in input order, on disappearance or timeout. Check each found value; False means that image is absent. Requires ready screen capture; unavailable capture can also report found=False.
Example
watch = ["loading", "syncing"]
result = region.wait_any(watch, 10000)
MacroPanel.notify(str(result))
Region.wait_all
Method
Wait until all templates in the list disappear from this region. If timeout is omitted, only one scan pass is performed.
Requested scans per second while waiting, limited to 1-60. Actual speed depends on recognition time.
Optional · Positional or named
Default:3.0
Returns
MatchList — The latest Match for each input template, in input order, on disappearance or timeout. All found values are False only when every image is absent. Requires ready screen capture; unavailable capture can also report found=False.
Example
watch = ["loading", "syncing"]
result = region.wait_all(watch, 10000)
MacroPanel.notify(str(result))
Region.capture
Method
Capture this screen area as a Template. Requires an active screen capture session with user consent. Unavailable capture or a region entirely outside the screen raises an error.
Shrink horizontally toward the center by moving both left and right edges inward.
Syntax
region.horizontal(value=0.5)
Parameters
Name
Description
valueNumber
Total width to remove, split equally between both sides: 0-1 is a fraction, above 1 is pixels. Capped at the full width; negative values raise an error.
Shrink vertically toward the center by moving both top and bottom edges inward.
Syntax
region.vertical(value=0.5)
Parameters
Name
Description
valueNumber
Total height to remove, split equally between both sides: 0-1 is a fraction, above 1 is pixels. Capped at the full height; negative values raise an error.
Amount removed from each dimension: 0-1 is a fraction of that dimension; above 1 is pixels. Split equally between opposite edges, capped at each dimension. Negative values raise an error.
Draw a rectangular outline around this region. Calling again on the same Region replaces its outline. Returns before drawing finishes; only the latest update before the next screen refresh is shown.
