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.