docs/ARCHITECTURE.md

Kiến trúc hệ thống

Tổng quan

Hệ thống gồm 3 lớp chính:

1. Template Matching (OpenCV): so khớp template với ảnh cần so sánh theo nhiều tỉ lệ và góc xoay.
2. NMS: loại bỏ bbox trùng lặp theo IoU.
3. CNN Verification (tùy chọn): cắt crop bbox, resize template tương ứng về cùng kích thước, trích xuất embedding và tính cosine similarity.

Thành phần

• template_matcher.py: class TemplateMatcher chứa hàm find trả về danh sách bbox và thông tin khớp.
• models.py: class ModelManager tải model timm, tiền xử lý ảnh, và tính cosine similarity.
• utils.py: các hàm hỗ trợ (rotate, resize, NMS, vẽ bbox, JSON).
• app.py: giao diện Gradio.
• main.py: CLI.

Pipeline xử lý

1. Đọc ảnh đầu vào và danh sách template.
2. Sinh biến thể template:
   • Xoay theo các góc: 0, 45, 90, 135, 180, 225, 270, 315.
   • Scale từ scale_min đến scale_max theo scale_steps.
3. Template matching với cv2.matchTemplate (TM_CCOEFF_NORMED).
4. Lấy các điểm >= match_threshold, tạo bbox, gom tất cả ứng viên.
5. NMS để giảm trùng lặp.
6. CNN (tùy chọn):
   • Crop theo bbox, resize template tương ứng về cùng kích thước crop.
   • Trích xuất embedding bằng model chọn trong UI.
   • Tính cosine similarity và lọc theo ngưỡng.
7. Vẽ bbox và xuất JSON kết quả.

JSON output

Mỗi phần tử có các trường:

• template_name: tên file template.
• bbox: (x, y, w, h).
• match_score: điểm template matching.
• angle: góc xoay template.
• scale: tỉ lệ scale.
• cosine_similarity: điểm CNN (có thể null nếu tắt CNN).

Lưu ý

• Template quá lớn sẽ tự động bị bỏ qua ở tỉ lệ không phù hợp.
• Thời gian xử lý tăng theo số lượng template, góc xoay, và số bước scale.
• CNN giúp lọc nhiều false positive nhưng sẽ làm chậm hệ thống.