Find Image (Tìm ảnh)
Chờ một ảnh template đã lưu xuất hiện trên màn, rồi rẽ theo việc có tìm thấy không.
Find Image là ngựa thồ của automation thị giác. Đa số flow là chuỗi "tìm cái này, rồi hành động trên nó".
Mục đích
Tìm một hoặc nhiều ảnh template đã chụp trên màn hình sống và báo vị trí khớp tốt nhất.
Dùng để chờ nút hay biểu tượng xuất hiện, xác nhận màn đã tải, hay cấp tọa độ khớp cho một Click. Nó liên tục kiểm các ảnh chụp mới cho đến khi khớp hoặc hết timeout — nên nó kiêm luôn vai trò chờ thông minh.
Khi nào dùng
- Chờ nút, biểu tượng, hay màn hình xuất hiện.
- Xác nhận hành động đã ăn, bằng cách phát hiện màn nó lẽ ra tạo ra.
- Định vị thứ có vị trí thay đổi, để Click chạm được.
- Phân biệt giữa nhiều màn khả dĩ, bằng branch-by-template.
Khi nào không dùng
- Đọc một giá trị — số, đồng hồ, tọa độ. Dùng Read Text.
- Phát hiện trạng thái không có biểu tượng riêng — thanh máu cạn, màn mờ dần. Dùng Check Region.
- Làm trễ cố định. Chỉ cần nghỉ thì Wait rõ hơn.
Điều kiện
Ít nhất một asset template đã chụp. Template chụp từ Live Preview và lưu cùng flow.
Cách nó chạy
Ít nhất một lần chụp và so luôn chạy, kể cả timeout rất nhỏ.
Khi timeout mà không khớp, node rẽ Failure nhưng status là success. Phép phát hiện đã chạy; ảnh đơn giản không có đó.
Nghĩa là một lần không-thấy không bao giờ kích retry policy và không bao giờ tính vào rào chắn lỗi liên tiếp. Xem status với route.
Thiết lập
| Thiết lập | Kiểu | Khoảng | Mặc định | Tác dụng |
|---|---|---|---|---|
| Template(s) | tham chiếu asset | 1–16 | — | Ảnh đã chụp cần tìm |
| Template name | string | ≤ 120 ký tự | — | Nhãn thân thiện cho bản chụp |
| Threshold | number | 0.5–0.99 | mặc định flow (0.88) | Độ tin cậy khớp tối thiểu; cao hơn = ngặt hơn |
| Search region | hình chữ nhật | phần trăm màn | cả màn | Giới hạn phép tìm — nhanh hơn, tránh khớp giả |
| Timeout | integer | 1–120000 ms | mặc định flow | Tìm trong bao lâu |
| Poll interval | integer | 50–120000 ms | mặc định flow (250) | Chụp lại thường xuyên cỡ nào |
| Multi-template | boolean | — | false | So một tập template; điểm cao nhất thắng |
| Branch by template | boolean | — | false | Mỗi template một port thay vì một Success |
| Colour mode | lựa chọn | color, grayscale | color | So màu hay xám |
| Scale mode | object | none hoặc multiScale | none | So ở dải kích thước |
| Ambiguity mode | lựa chọn | requireUnique, best, all | best | Làm gì khi nhiều chỗ khớp |
| Min best/second-best delta | number | ≥ 0 | — | Kẻ thắng phải rõ hơn bao nhiêu, cho requireUnique |
| Max matches | integer | 1–100 | — | Trần cho chế độ all |
| Save results to variables | danh sách | ≤ 16 | — | Gán trường output vào tên biến |
Threshold
Thiết lập tác động lớn nhất.
- 0.88 là điểm khởi đầu tốt và là mặc định sản phẩm.
- 0.95+ thường trượt các khớp hợp lệ — lệch một pixel hay khác khử răng cưa nhẹ đã tụt điểm.
- Dưới 0.75 bắt đầu khớp nhiễu.
Chỉnh bằng thử nghiệm, không bằng đoán: dùng Test Node xem độ tin cậy thật template đạt.
Search region
Đặt search region là cú tăng tốc rẻ nhất hiện có: bộ so làm việc trên mảnh cắt thay vì cả khung. Nó cũng chặn dương tính giả nơi khác trên màn.
Biết đại khái thứ đó ở đâu thì hãy giới hạn lại.
Multi-template và branch-by-template
Hai công tắc riêng xếp chồng:
| Cấu hình | Hành vi | Port |
|---|---|---|
| Một template | So một ảnh | success / failure |
| Multi-template bật | So một tập, giữ điểm cao nhất | success / failure |
| Multi-template + Branch by template | So một tập, rẽ theo cái nào khớp | mỗi template một port + notFound |
Branch-by-template là cách xử lý "màn này có thể ở một trong bốn trạng thái" trong một node. Id template chính là khóa port, nên đổi tên template giữ nhánh; x óa template gỡ port.
Save results to variables
Gán các trường output vào tên biến node sau dùng được:
centerX, centerY, confidence, matched, matchedTemplate, x / y / width / height của khớp, scale
Biến được tự khai khi khớp thành công.
Muốn chạm thứ vừa tìm, không cần biến — đặt coordinate source của Click là node Find Image này. Dùng biến khi cần con số để tính toán hay log.
Chính sách nhập nhằng
| Chế độ | Ý nghĩa |
|---|---|
best | Lấy khớp điểm cao nhất (mặc định) |
requireUnique | Hỏng nếu á quân quá sát — dùng khi chọn nhầm là đắt |
all | Báo mọi khớp trên ngưỡng, tối đa maxMatches |
Port
| Port | Đi vào khi | Bắt buộc |
|---|---|---|
| Success | Template được tìm thấy | Có (chế độ đơn/multi) |
| Failure | Không thấy trước timeout (status vẫn success), hoặc lỗi phát hiện phục hồi được — khớp nhập nhằng, lỗi engine, template kém | Không |
| Cancelled | Lần chạy dừng giữa tìm | Không — không bao giờ được đi |
| Fatal | Chụp hỏng, mất kết nối, hoặc tham số sai | Không — không bao giờ được đi |
| theo-template | Chế độ branch: port mang id template khớp | Không |
| notFound | Chế độ branch: không template nào khớp | Không |
Ví dụ cơ bản
Chờ một nút rồi chạm:
- Template: nút Start, cắt sát
- Threshold:
0.88 - Timeout:
5000ms
Nối Success → Click (coordinate source = node này), Failure → Stop: failure.
Ví dụ thực tế — popup tùy chọn
Popup thưởng ngày có ngày không. Cả hai đều bình thường:
Timeout ngắn là mấu chốt: bạn hỏi "nó có đây ngay bây giờ không", không phải chờ nó đến. Timeout 30 giây ở đây phí 30 giây mỗi lần chạy không có popup.
Ví dụ nâng cao — branch by template
Một node quyết bạn đang ở màn nào trong bốn:
Thay bốn Find Image nối tiếp bằng một, và một ảnh chụp thay vì bốn.
Best practices
- Chụp cắt sát đúng mục tiêu, không nền. Nền là thứ làm template ngừng khớp về sau.
- Khởi đầu threshold 0.88 và chỉnh bằng Test Node.
- Luôn nối Failure. Port Failure trống biến "không thấy" thành lần chạy bị kết thúc.
- Đặt search region mỗi khi biết đại khái mục tiêu ở đâu.
- Timeout khớp với câu hỏi. "Nó có đây chưa?" = ngắn. "Chờ nó tải" = dài.
- Dùng node làm coordinate source của Click thay vì luồn tọa độ qua biến.
- Ưu tiên branch-by-template hơn chuỗi Find Image khi nhận diện màn nào đang hiện.
Ghi chú hiệu năng
- Chi phí mỗi poll ≈ (diện tích vùng) × (số template) × (số tỉ lệ). Cả ba nhân nhau.
- Search region là đòn bẩy lớn nhất. Cắt còn một phần tư màn giảm ~4 lần việc so.
- Đa tỉ lệ đắt — mỗi nấc tỉ lệ là một lượt quét đủ. Chỉ bật khi mục tiêu thật sự đổi cỡ.
- Xám rẻ hơn màu và thường đủ tin cho khung UI.
- Poll ngắn nghĩa nhiều lần chụp mỗi giây. Dưới ~150 ms thường tốn cho chụp nhiều hơn lợi về phản hồi.
- Timeout dài không tốn gì khi ảnh có mặt — node về ngay khi khớp. Nó chỉ tốn ở ca không-thấy.
Ghi chú bộ nhớ
- Template được nạp và cache. Nhiều template lớn = working set lớn; cắt sát nhỏ về mọi nghĩa.
- Mỗi poll chụp khung mới. Khung tạm thời, nhưng poll rất ngắn tăng churn chụp.
- Chế độ
allvớimaxMatchescao giữ danh sách khớp; để trần hợp lý.
Lỗi thường gặp
| Lỗi | Hậu quả | Cách sửa |
|---|---|---|
| Chỉ nối Success | "Không thấy" kết thúc lần chạy | Nối Failure |
| Template rối | Confidence tụt khi nền đổi | Cắt sát phần đặc trưng |
| Threshold 0.95+ | Trượt khớp hợp lệ | Khởi đầu 0.88 |
| Timeout quá ngắn cho màn tải | Bỏ cuộc giữa hiệu ứng | Timeout khớp thứ đang chờ |
| Timeout dài cho phần tử tùy chọn | Phí thời gian đó mỗi lần chạy | Ngắn cho "có đây chưa" |
| Thêm retry để "tìm kỹ" | Không nổ — không-thấy là status success | Nâng timeout |
| Đa tỉ lệ bật khắp nơi | Phát hiện chậm nhiều lần | Chỉ nơi cỡ thay đổi |
Khắc phục sự cố
Không bao giờ thấy ảnh rõ ràng đang trên màn. Hạ threshold và xem Test Node báo confidence thật. Thấp hơn hẳn 0.88 → template dính nền đã đổi.
Khớp nhầm chỗ.
Đặt search region, hoặc chuyển ambiguity sang requireUnique kèm delta để ca sát nút hỏng thay vì đoán.
Từng chạy, rồi hỏng sau đổi độ phân giải hay zoom. So template theo pixel. Chụp lại template, hoặc bật đa tỉ lệ trong cổng tính năng flow.
Node chậm. Kiểm cỡ vùng, số template và dải tỉ lệ — ba thứ nhân nhau. Bắt đầu bằng thêm search region.
Một port branch-by-template biến mất. Template của nó bị gỡ khỏi lựa chọn. Editor cắt edge mồ côi.
FAQ
Không-thấy có tính là thất bại cho retry hay ngưỡng sức khỏe?
Không. Status của nó là success.
Tìm chỉ một phần màn được không? Được — đặt search region. Nhanh và tin hơn.
Một node chứa mấy template? Tối đa 16.
Nên nhắm confidence bao nhiêu? Cao thoải mái trên threshold. Khớp thật tốt nhất 0.89 với threshold 0.88 là biên quá mỏng — cải thiện template.
Poll interval có phải timeout? Không. Poll là tần suất kiểm lại; timeout là tổng thời gian thử.
Node liên quan
- Click — chạm thứ tìm thấy
- Swipe — căn giữa thứ tìm thấy
- Read Text — đọc giá trị thay vì tìm hình
- Check Region — trạng thái không biểu tượng
- If — rẽ trên kết cục node này về sau
Trang liên quan
- Mô hình thực thi — status với route
- Giải phẫu Flow — chất lượng template