Một vùng chữ nhật trên màn hình để tìm ảnh hoặc màu, chụp ảnh hoặc vẽ khung đánh dấu. Tọa độ dùng pixel theo trục ngang/dọc hiện tại; sau khi điều chỉnh kích thước và độ lệch, chỉ phần trong màn hình được sử dụng. Đọc kích thước bằng x, y, width, height = region.
Cú pháp
Region(x, y, width, height, /, scale="fixed", anchor="none", scale_param=ScaleParam())
Cách điều chỉnh tọa độ giữa các màn hình: fixed giữ pixel; auto đổi X theo tỉ lệ chiều rộng, Y theo tỉ lệ chiều cao; width hoặc height đổi cả hai trục theo kích thước đó. Dùng kích thước màn hình nguồn của macro, không xoay trục và không dùng kích thước cửa sổ app.
Vị trí làm mốc khi điều chỉnh tọa độ: none (góc trên trái), center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right. auto chọn cạnh hoặc tâm gần nhất.
Cách điều chỉnh tọa độ giữa các màn hình: fixed giữ pixel; auto đổi X theo tỉ lệ chiều rộng, Y theo tỉ lệ chiều cao; width hoặc height đổi cả hai trục theo kích thước đó. Dùng kích thước màn hình nguồn của macro, không xoay trục và không dùng kích thước cửa sổ app.
Vị trí làm mốc khi điều chỉnh tọa độ: none (góc trên trái), center, top, bottom, left, right, top_left, top_right, bottom_left, bottom_right. auto chọn cạnh hoặc tâm gần nhất.
Trả về chiều rộng màn hình của thiết bị đã tạo macro này theo hướng xoay màn hình hiện tại, nếu có.
Cú pháp
Region.macro_width()
Giá trị trả về
Number? — Chiều rộng màn hình nguồn của macro, hoặc None nếu không có.
Ví dụ
macro_w = Region.macro_width()
Region.macro_height
Static Method
Trả về chiều cao màn hình của thiết bị đã tạo macro này theo hướng xoay màn hình hiện tại, nếu có.
Cú pháp
Region.macro_height()
Giá trị trả về
Number? — Chiều cao màn hình nguồn của macro, hoặc None nếu không có.
Ví dụ
macro_h = Region.macro_height()
Region.intersection
Method
Trả Region mới là phần giao có diện tích dương, hoặc None. Hai cạnh chỉ chạm nhau không giao nhau. Dùng tọa độ đã lưu trong cùng hệ tọa độ, không chụp, đổi tỉ lệ hay cắt; giữ scale, anchor và scale_param của Region này, không thay đổi đối tượng gốc.
Boolean — Tọa độ và các cạnh sau tính toán phải hữu hạn; nếu không sẽ báo lỗi.
Ví dụ
# Kiểm tra hai vùng có giao nhau
print(Region(0, 0, 100, 100).intersects(Region(50, 50, 20, 20)))
Region.contains
Method
Kiểm tra bao chứa bằng tọa độ đã lưu trong cùng hệ tọa độ, không chụp, đổi tỉ lệ hay cắt. Point được tính ở cạnh trái và trên, không tính ở cạnh phải và dưới. Region có thể trùng cạnh; kích thước rỗng hoặc âm trả False.
Boolean — Tọa độ và các cạnh sau tính toán phải hữu hạn; nếu không sẽ báo lỗi.
Ví dụ
# Kiểm tra điểm có nằm trong vùng
print(Region(0, 0, 100, 100).contains(Point(10, 10)))
Region.find_text
Method
Tìm chữ bằng OCR trong vùng này theo pixel màn hình. Kết quả phải khớp từ hoặc cụm từ trọn vẹn, không cắt giữa chữ cái, chữ số hoặc dấu gạch dưới. Chức năng chụp màn hình phải sẵn sàng. Thử lại đến khi tìm thấy hoặc hết thời gian, có hỗ trợ tạm dừng và dừng; bộ nhớ đệm ảnh chụp hoạt động như các phép nhận diện khác. Lỗi OCR hoặc chụp màn hình sẽ được báo lỗi.
Hệ chữ OCR: latin, chinese, devanagari, japanese hoặc korean. Giá trị khác, kể cả bí danh ngôn ngữ theo vùng, sẽ gây lỗi.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:"latin"
preserve_caseBoolean
Phân biệt chữ hoa và chữ thường khi là True; mặc định không phân biệt.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:False
Giá trị trả về
Match — Match tìm thấy có bounds và point theo pixel toàn màn hình, confidence từ 0 đến 1 và name là chữ mục tiêu đã khớp. Nếu không tìm thấy, found=False. Các vị trí riêng biệt cùng đạt điểm cao nhất sẽ gây lỗi mơ hồ; hãy thu hẹp vùng tìm kiếm. Các kết quả chồng nhau được tính là một vị trí.
Ví dụ
# Tìm và nhấn nút OK trong cửa sổ bật lên
hit = Region(500, 100, 400, 300).find_text("OK", timeout=3000)
if hit.found:
click(hit)
Region.find
Method
Tìm một vị trí khớp ảnh mẫu trong vùng này. Thử lại đến khi tìm thấy hoặc hết thời gian; timeout=0 quét một lần. Cần sẵn sàng chụp màn hình. ScreenCapture.cache_on() cho các lần tìm dùng lại một ảnh chụp đến khi gọi cache_off(); nếu không, ảnh vẫn được tự động dùng lại tối đa 100 ms. Dùng auto_cache_off() để lấy ảnh mới nhất hiện có, nhưng sẽ cần chụp nhiều hơn.
Tên ảnh mẫu hoặc đường dẫn thư mục tương đối không kèm đuôi ảnh trong macro hiện tại, hoặc đối tượng Template. Tên không tồn tại sẽ gây lỗi.
Bắt buộc · Theo vị trí hoặc tên
Không có giá trị mặc định
timeoutNumber
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
thresholdNumber
Ngưỡng khớp từ 0.0 đến 1.0.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0.7
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3.0
Giá trị trả về
Match — Match có found=True khi tìm thấy; nếu không, found=False sau lượt quét hoặc khi hết thời gian. Không trả None.
Ví dụ
region = Region(80, 220, 420, 520)
hit = region.find("ok", 4000, 0.8, 4.0)
MacroPanel.notify(str(hit))
Region.find_multi
Method
Quét trong region này và trả về tất cả kết quả khớp cho một template khi tìm thấy ít nhất một kết quả. Nếu bỏ qua timeout, hệ thống chỉ quét đúng một lần.
Tên ảnh mẫu/đường dẫn thư mục tương đối không kèm đuôi ảnh, hoặc đối tượng Template. Tên không tồn tại sẽ gây lỗi.
Bắt buộc · Theo vị trí hoặc tên
Không có giá trị mặc định
timeoutNumber
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
thresholdNumber
Ngưỡng khớp từ 0.0 đến 1.0.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0.7
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3.0
Giá trị trả về
MatchList — Một Match cho mỗi ảnh mẫu theo thứ tự đầu vào khi tìm thấy ít nhất một ảnh; một số mục có thể có found=False. MatchList rỗng nếu không tìm thấy ảnh nào trước khi hết thời gian.
Tìm một pixel được kiểm tra có màu gần mục tiêu nhất trong vùng này. Sai lệch của từng kênh đỏ, xanh lá và xanh dương không được vượt tolerance; chọn điểm có sai lệch lớn nhất giữa các kênh nhỏ nhất. Thử lại đến khi tìm thấy hoặc hết thời gian; timeout=0 quét một lần. Cần sẵn sàng chụp màn hình.
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
toleranceNumber
Sai số RGB cho phép trên từng kênh từ 0 đến 255.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3
intervalNumber
Khoảng cách yêu cầu theo pixel giữa các vị trí được kiểm tra; tối thiểu 1. Giá trị nhỏ kiểm tra nhiều pixel hơn và có thể lâu hơn. Khoảng cách có thể tự tăng khi vùng lớn.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:10
Giá trị trả về
Match — Match có tối đa một Point trong point, hoặc found=False và danh sách point rỗng nếu không có pixel được kiểm tra nào khớp hoặc không thể chụp.
Ví dụ
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
Tìm bất kỳ màu mục tiêu nào trong vùng này theo quy tắc sai số RGB của find_color. Mỗi màu tìm thấy trả tối đa một điểm được kiểm tra tốt nhất, theo thứ tự đầu vào. Thử lại đến khi tìm thấy ít nhất một màu hoặc hết thời gian; timeout=0 quét một lần. Cần sẵn sàng chụp màn hình.
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
toleranceNumber
Sai số RGB cho phép trên từng kênh từ 0 đến 255.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3
intervalNumber
Khoảng cách yêu cầu theo pixel giữa các vị trí được kiểm tra; tối thiểu 1. Giá trị nhỏ kiểm tra nhiều pixel hơn và có thể lâu hơn. Khoảng cách có thể tự tăng khi vùng lớn.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:10
Giá trị trả về
Match — Match có một Point tốt nhất cho mỗi màu tìm thấy trong point, theo thứ tự đầu vào. found=False và danh sách point rỗng nếu không có màu khớp hoặc không thể chụp.
Ví dụ
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
Tìm mọi pixel được kiểm tra khớp một màu mục tiêu theo quy tắc sai số RGB của find_color. Danh sách hoặc tuple màu sẽ gây lỗi. Thử lại đến khi tìm thấy ít nhất một điểm hoặc hết thời gian; timeout=0 quét một lần. Cần sẵn sàng chụp màn hình.
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
toleranceNumber
Sai số RGB cho phép trên từng kênh từ 0 đến 255.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3
intervalNumber
Khoảng cách yêu cầu theo pixel giữa các vị trí được kiểm tra; tối thiểu 1. Giá trị nhỏ kiểm tra nhiều pixel hơn và có thể lâu hơn. Khoảng cách có thể tự tăng khi vùng lớn.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:10
Giá trị trả về
Match — Match chứa các Point được kiểm tra khớp màu trong point, màu gần nhất đứng trước. found=False và danh sách point rỗng nếu không có điểm khớp hoặc không thể chụp.
Ví dụ
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
Chờ cho đến khi template biến mất khỏi region này. Nếu bỏ qua timeout, hệ thống chỉ quét đúng một lần.
Tên ảnh mẫu hoặc đường dẫn thư mục tương đối không kèm đuôi ảnh trong macro hiện tại, hoặc đối tượng Template. Tên không tồn tại sẽ gây lỗi.
Bắt buộc · Theo vị trí hoặc tên
Không có giá trị mặc định
timeoutNumber
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
thresholdNumber
Ngưỡng khớp từ 0.0 đến 1.0.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0.7
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3.0
Giá trị trả về
Match — Match mới nhất: found=False nghĩa là không thấy ảnh; found=True nghĩa là vẫn thấy ảnh khi kết thúc chờ. Không trả None. Cần sẵn sàng chụp màn hình; không thể chụp cũng có thể trả found=False.
Ví dụ
region = Region(0, 0, 1080, 2400)
result = region.wait("loading", 8000)
MacroPanel.notify(str(result))
Region.wait_any
Method
Chờ đến khi có ít nhất một template trong danh sách biến mất khỏi region này. Nếu bỏ qua timeout, hệ thống chỉ quét đúng một lần.
Tên ảnh mẫu/đường dẫn thư mục tương đối không kèm đuôi ảnh, hoặc đối tượng Template. Tên không tồn tại sẽ gây lỗi.
Bắt buộc · Theo vị trí hoặc tên
Không có giá trị mặc định
timeoutNumber
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
thresholdNumber
Ngưỡng khớp từ 0.0 đến 1.0.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0.7
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3.0
Giá trị trả về
MatchList — Match mới nhất của mỗi ảnh mẫu theo thứ tự đầu vào khi có ảnh biến mất hoặc hết thời gian. Kiểm tra found của từng mục; False nghĩa là không thấy ảnh đó. Cần sẵn sàng chụp màn hình; không thể chụp cũng có thể trả found=False.
Ví dụ
watch = ["loading", "syncing"]
result = region.wait_any(watch, 10000)
MacroPanel.notify(str(result))
Region.wait_all
Method
Chờ đến khi tất cả template trong danh sách đều biến mất khỏi region này. Nếu bỏ qua timeout, hệ thống chỉ quét đúng một lần.
Tên ảnh mẫu/đường dẫn thư mục tương đối không kèm đuôi ảnh, hoặc đối tượng Template. Tên không tồn tại sẽ gây lỗi.
Bắt buộc · Theo vị trí hoặc tên
Không có giá trị mặc định
timeoutNumber
Thời gian chờ tối đa theo mili giây. Bỏ qua, 0 hoặc số âm thì quét một lần. Lượt quét đang chạy có thể kết thúc sau thời gian này.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0
thresholdNumber
Ngưỡng khớp từ 0.0 đến 1.0.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:0.7
rateNumber
Số lượt quét yêu cầu mỗi giây khi chờ, giới hạn từ 1 đến 60. Tốc độ thực tế phụ thuộc thời gian nhận diện.
Tùy chọn · Theo vị trí hoặc tên
Mặc định:3.0
Giá trị trả về
MatchList — Match mới nhất của mỗi ảnh mẫu theo thứ tự đầu vào khi ảnh biến mất hoặc hết thời gian. Mọi giá trị found đều False chỉ khi không thấy ảnh nào. Cần sẵn sàng chụp màn hình; không thể chụp cũng có thể trả found=False.
Ví dụ
watch = ["loading", "syncing"]
result = region.wait_all(watch, 10000)
MacroPanel.notify(str(result))
Region.capture
Method
Chụp vùng màn hình này thành Template. Cần phiên chụp màn hình đang hoạt động đã được người dùng cho phép. Báo lỗi nếu không thể chụp hoặc vùng nằm hoàn toàn ngoài màn hình.
Vẽ khung chữ nhật quanh vùng này. Gọi lại trên cùng Region sẽ thay khung cũ. Hàm trả về trước khi vẽ xong; chỉ cập nhật mới nhất trước lần làm mới màn hình kế tiếp được hiển thị.