A rectangular region on the screen, measured in pixels on the current screen axes.
Syntax
Region(x, y, width, height, /, scale="fixed", anchor="none", scale_param=ScaleParam())
Constructor parameters
Name
Description
xNumber
Top-left X coordinate
Required · Positional only
No default
yNumber
Top-left Y coordinate
Required · Positional only
No default
widthNumber
Region width
Required · Positional only
No default
heightNumber
Region height
Required · Positional only
No default
scaleString
**Applies to region coordinates**. Optional full-screen scale mode on the current X/Y axes. Values: "fixed", "auto", "width", "height".
Optional · Positional or named
Default:fixed
anchorString
**Applies to region coordinates**. Optional anchor mode. Values: none, center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right, auto.
Optional · Positional or named
Default:none
scale_paramScaleParam
**Applies to templates**. Template matching scale parameters.
Optional · Positional or named
Default:ScaleParam()
Returns
Region
Behavior / side effects
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.
Execution
Blocking: No
Thread safety: Use separate objects per flow
Parallel execution: Yes
Constructs or derives geometry in the calling flow without capture or recognition. Keep mutable Region builders local to each flow.
Example
region = Region(100, 200, 300, 400)
hit = region.find("img", 3000, threshold=0.8, rate=3.0)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Related APIs
None
Fields
Name
Description
xNumber
Top-left horizontal coordinate.
yNumber
Top-left vertical coordinate.
widthNumber
Region width in pixels.
heightNumber
Region height in pixels.
scaleString
**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.
Default:fixed
anchorString
**Applies to region coordinates**. Coordinate anchor. Values: none, center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right, auto.
Default:none
scale_paramScaleParam
**Applies to templates**. Template matching scale parameters used by find/wait methods on this region.
Default:ScaleParam()
middle_pointPoint
Center point of this region.
Field example
search_area = Region(120, 240, 360, 420)
left = search_area.x
top = search_area.y
w = search_area.width
h = search_area.height
scale = search_area.scale
anchor = search_area.anchor
search_area.x = 300
search_area.scale_param = ScaleParam(auto_scale=True, template_scale="LONG_EDGE")
center = search_area.middle_point
# Unpack Region into x, y, width, height
x, y, width, height = search_area
Get all regions currently highlighted by script instances.
Syntax
Region.highlighted()
Parameters
None
Returns
list[Region] — list of active highlighted regions.
Behavior / side effects
Get all regions currently highlighted by script instances.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Example
active_regions = Region.highlighted()
for area in active_regions:
area.highlight("yellow", auto_hide_ms=500)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Region — Screen-sized region from the runtime host.
Behavior / side effects
Return the full current screen region.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Example
scan = Region.full_screen()
hit = scan.find("ok", 2000)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Return the screen width of the device that created this macro, adapted to current screen orientation, when available.
Syntax
Region.macro_width()
Parameters
None
Returns
Number? — Macro source screen width, or None when unavailable.
Behavior / side effects
Return the screen width of the device that created this macro, adapted to current screen orientation, when available.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Example
macro_w = Region.macro_width()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Return the screen height of the device that created this macro, adapted to current screen orientation, when available.
Syntax
Region.macro_height()
Parameters
None
Returns
Number? — Macro source screen height, or None when unavailable.
Behavior / side effects
Return the screen height of the device that created this macro, adapted to current screen orientation, when available.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Example
macro_h = Region.macro_height()
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Template name, relative folder path, or a Template object in current macro.
Required · Positional or named
No default
timeoutNumber
Maximum wait time in milliseconds. Omit this argument to scan only once.
Optional · Positional or named
Default:0
thresholdNumber
Match threshold from 0.0 to 1.0.
Optional · Positional or named
Default:0.7
rateNumber
Scan attempts per second (1-60).
Optional · Positional or named
Default:3.0
Returns
Match — First successful match, or found=false when timed out.
Behavior / side effects
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.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Example
region = Region(80, 220, 420, 520)
hit = region.find("ok", 4000, 0.8, 4.0)
MacroPanel.notify(str(hit))
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Template name, relative folder path, or a Template object in current macro.
Required · Positional or named
No default
timeoutNumber
Maximum wait time in milliseconds. Omit this argument to scan only once.
Optional · Positional or named
Default:0
thresholdNumber
Match threshold from 0.0 to 1.0.
Optional · Positional or named
Default:0.7
rateNumber
Scan attempts per second (1-60).
Optional · Positional or named
Default:3.0
Returns
MatchList — All matches for the template, or empty list on timeout.
Behavior / side effects
Scan inside this region and return all matches for one template when at least one is found. If timeout is omitted, only one scan pass is performed.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Maximum wait time in milliseconds. Omit this argument to scan only once.
Optional · Positional or named
Default:0
thresholdNumber
Match threshold from 0.0 to 1.0.
Optional · Positional or named
Default:0.7
rateNumber
Scan attempts per second (1-60).
Optional · Positional or named
Default:3.0
Returns
MatchList — Batch match results when any template is found, or empty list on timeout.
Behavior / side effects
Scan this region and return when any template in the list is found. If timeout is omitted, only one scan pass is performed.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Maximum wait time in milliseconds. Omit this argument to scan only once.
Optional · Positional or named
Default:0
thresholdNumber
Match threshold from 0.0 to 1.0.
Optional · Positional or named
Default:0.7
rateNumber
Scan attempts per second (1-60).
Optional · Positional or named
Default:3.0
Returns
MatchList — Batch match results when all templates are found, or empty list on timeout.
Behavior / side effects
Scan this region and return only when every template in the list is found. If timeout is omitted, only one scan pass is performed.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
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]; find_color returns at most one point.
Behavior / side effects
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.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
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)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
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.
Behavior / side effects
Scan this region for multiple target colors. Each input color contributes at most one best point, ordered by the input color list.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Example
colors = ["#FF0000", "#00FF00", "#0000FF"]
hit = Region.full_screen().find_any_color(colors, tolerance=6)
if hit.found:
click(hit, random=0)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
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.
Behavior / side effects
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.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
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)
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Template name, relative folder path, or a Template object in current macro.
Required · Positional or named
No default
timeoutNumber
Maximum wait time in milliseconds. Omit this argument to scan only once.
Optional · Positional or named
Default:0
thresholdNumber
Match threshold from 0.0 to 1.0.
Optional · Positional or named
Default:0.7
rateNumber
Scan attempts per second (1-60).
Optional · Positional or named
Default:3.0
Returns
Match — Latest match state when the template disappears or timeout is reached.
Behavior / side effects
Wait until the template disappears from this region. If timeout is omitted, only one scan pass is performed.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Example
region = Region(0, 0, 1080, 2400)
result = region.wait("loading", 8000)
MacroPanel.notify(str(result))
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Maximum wait time in milliseconds. Omit this argument to scan only once.
Optional · Positional or named
Default:0
thresholdNumber
Match threshold from 0.0 to 1.0.
Optional · Positional or named
Default:0.7
rateNumber
Scan attempts per second (1-60).
Optional · Positional or named
Default:3.0
Returns
MatchList — Batch match states when at least one template is no longer found.
Behavior / side effects
Wait until any template in the list disappears from this region. If timeout is omitted, only one scan pass is performed.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Example
watch = ["loading", "syncing"]
result = region.wait_any(watch, 10000)
MacroPanel.notify(str(result))
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Maximum wait time in milliseconds. Omit this argument to scan only once.
Optional · Positional or named
Default:0
thresholdNumber
Match threshold from 0.0 to 1.0.
Optional · Positional or named
Default:0.7
rateNumber
Scan attempts per second (1-60).
Optional · Positional or named
Default:3.0
Returns
MatchList — Batch match states when all templates are no longer found.
Behavior / side effects
Wait until all templates in the list disappear from this region. If timeout is omitted, only one scan pass is performed.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Example
watch = ["loading", "syncing"]
result = region.wait_all(watch, 10000)
MacroPanel.notify(str(result))
Errors / limitations
No additional limitations documented; follow the parameter and behavior contract above.
Capture the screen and crop to this region, then return the result as a Template.
Syntax
region.capture(name=None)
Parameters
Name
Description
nameString?
Optional template name to save into current macro immediately.
Optional · Positional or named
Default:None
Returns
Template — Captured template object.
Behavior / side effects
Capture the screen and crop to this region, then return the result as a Template.
Execution
Blocking: Yes
Thread safety: Limited
Parallel execution: Conditional
Recognition runs in the caller and uses shared capture. find operations search for appearance; wait operations wait for disappearance. Even a single scan takes capture and recognition time; a timeout or polling rate does not make the call asynchronous.
Auto-hide after N milliseconds. 0 disables auto-hide.
Optional · Positional or named
Default:0
movableBoolean
Allow dragging the highlighted region and write the moved coordinates back into this Region.
Optional · Positional or named
Default:False
Returns
Region — Returns the same region after drawing highlight.
Behavior / side effects
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.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
Region — Returns the same region after turning highlight off.
Behavior / side effects
Turn off highlight for this region instance.
Execution
Blocking: Conditional
Thread safety: Not guaranteed
Parallel execution: Conditional
Execution cost and waits depend on the documented operation. Keep mutable values in their owning flow; sharing arbitrary objects between flows has no general thread-safety guarantee.
