A rectangular region on the screen, measured in pixels on the current screen axes. Scale/anchor control coordinate mapping across full-screen sizes without rotating through portrait coordinates or using the app viewport; runtime consumers clip the final region to the current screen after mapping and offsets. ScaleParam controls template matching inside this region. Region can be destructured as x, y, width, height.
Syntax
Region(x, y, width, height, /, scale="fixed", anchor="none", scale_param=ScaleParam())
**Applies to region coordinates**. Coordinate scale mode using full-screen dimensions on the current X/Y axes, without app viewport scaling or portrait rotation. Values: "fixed" keeps saved pixels unchanged; "auto" scales X by width and Y by height; "width" scales both axes by screen width; "height" scales both axes by screen height.
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
Scan inside this region until one template match is found or timeout is reached. If timeout is omitted, only one scan pass is performed. Use ScreenCapture.cache_on() to check several images in one pinned frame, then cache_off() to unpin it. For rapid recognition with the freshest available frame, also use ScreenCapture.auto_cache_off(); automatic caching otherwise reuses frames for up to 100 ms. Disabling it increases capture work and does not guarantee faster execution.
Scan this region for one target color using the same raw-frame RGB tolerance rule as UI color recognition. The best point is selected by the smallest max RGB channel delta.
Maximum wait time in milliseconds. 0 performs one scan pass.
Optional · Positional or named
Default:0
toleranceNumber
Allowed per-channel RGB delta from 0 to 255.
Optional · Positional or named
Default:0
rateNumber
Scan attempts per second while waiting.
Optional · Positional or named
Default:3
intervalNumber
Sampling step in pixels.
Optional · Positional or named
Default:10
Returns
Match — Match with point as list[Point]; one best point per found input color.
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
Scan this region for multiple sampled positions of one target color. Passing a list or tuple is rejected so this does not silently become multi-target color search.
Maximum wait time in milliseconds. 0 performs one scan pass.
Optional · Positional or named
Default:0
toleranceNumber
Allowed per-channel RGB delta from 0 to 255.
Optional · Positional or named
Default:0
rateNumber
Scan attempts per second while waiting.
Optional · Positional or named
Default:3
intervalNumber
Sampling step in pixels.
Optional · Positional or named
Default:10
Returns
Match — Match with point as list[Point]; matching sampled points are sorted with the closest color first.
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.
Draw a highlighted rectangle for this region. With movable=True, the user can drag the region and the same Region object receives the updated screen coordinates. Re-highlighting the same region instance replaces the previous one.
