IDcardsGenerator/README_ID_Card_Processing.md

# ID Card Processing with YOLO Detection

Hệ thống xử lý ID cards sử dụng YOLO để detect và crop, kết hợp với các phương pháp tiền xử lý để clean background và enhance chất lượng ảnh.

## Tính năng chính

- **YOLO Detection**: Detect và crop ID cards từ ảnh gốc
- **Background Removal**: 3 phương pháp loại bỏ background (GrabCut, Threshold, Contour)
- **Image Enhancement**: Cải thiện chất lượng ảnh cho OCR
- **Batch Processing**: Xử lý hàng loạt ảnh
- **Flexible Pipeline**: Có thể chạy từng bước riêng biệt

## Cài đặt

1. Cài đặt dependencies:
```bash
pip install -r requirements.txt
```

2. Cấu trúc thư mục:
```
OCR/
├── src/
│   ├── model/
│   │   ├── __init__.py
│   │   ├── yolo_detector.py
│   │   └── id_card_processor.py
│   └── ...
├── data/
│   ├── IDcards/          # Thư mục chứa ảnh ID cards gốc
│   └── processed_id_cards/ # Thư mục output
├── id_card_processor_main.py
└── requirements.txt
```

## Sử dụng

### 1. Full Pipeline (Detect + Preprocess)

```bash
python id_card_processor_main.py \
    --input-dir "data/IDcards" \
    --output-dir "data/processed_id_cards" \
    --confidence 0.5 \
    --bg-removal grabcut \
    --target-size 800x600 \
    --save-annotated
```

### 2. Chỉ Detect và Crop

```bash
python id_card_processor_main.py \
    --input-dir "data/IDcards" \
    --output-dir "data/processed_id_cards" \
    --detect-only \
    --save-annotated
```

### 3. Chỉ Preprocess (bỏ qua detection)

```bash
python id_card_processor_main.py \
    --input-dir "data/IDcards" \
    --output-dir "data/processed_id_cards" \
    --preprocess-only \
    --bg-removal threshold \
    --target-size 800x600
```

## Các tham số

### Detection Parameters
- `--model-path`: Đường dẫn đến custom YOLO model (.pt file)
- `--confidence`: Ngưỡng confidence cho detection (default: 0.5)

### Preprocessing Parameters
- `--bg-removal`: Phương pháp loại bỏ background
  - `grabcut`: Sử dụng GrabCut algorithm (recommended)
  - `threshold`: Sử dụng thresholding
  - `contour`: Sử dụng contour detection
  - `none`: Không loại bỏ background
- `--target-size`: Kích thước chuẩn hóa (width x height)

### Output Options
- `--save-annotated`: Lưu ảnh với bounding boxes
- `--detect-only`: Chỉ chạy detection
- `--preprocess-only`: Chỉ chạy preprocessing

## Output Structure

```
data/processed_id_cards/
├── cropped/           # Ảnh đã được crop từ YOLO
│   ├── image1_card_1.jpg
│   ├── image1_card_2.jpg
│   └── ...
├── processed/         # Ảnh đã được preprocess
│   ├── image1_card_1_processed.jpg
│   ├── image1_card_2_processed.jpg
│   └── ...
└── annotated/         # Ảnh với bounding boxes (nếu có)
    ├── image1_annotated.jpg
    └── ...
```

## Ví dụ sử dụng

### Ví dụ 1: Xử lý toàn bộ dataset
```bash
# Xử lý tất cả ảnh trong thư mục IDcards
python id_card_processor_main.py \
    --input-dir "data/IDcards" \
    --output-dir "data/processed_id_cards" \
    --confidence 0.6 \
    --bg-removal grabcut \
    --target-size 1024x768 \
    --save-annotated
```

### Ví dụ 2: Test với một vài ảnh
```bash
# Tạo thư mục test với một vài ảnh
mkdir -p data/test_images
# Copy một vài ảnh vào test_images

# Chạy detection
python id_card_processor_main.py \
    --input-dir "data/test_images" \
    --output-dir "data/test_output" \
    --detect-only \
    --save-annotated
```

### Ví dụ 3: Sử dụng custom model
```bash
# Nếu bạn có custom YOLO model đã train
python id_card_processor_main.py \
    --input-dir "data/IDcards" \
    --output-dir "data/processed_id_cards" \
    --model-path "models/custom_id_card_model.pt" \
    --confidence 0.7
```

## Lưu ý

1. **YOLO Model**: Mặc định sử dụng YOLOv8n pre-trained. Nếu có custom model tốt hơn, hãy sử dụng `--model-path`

2. **Background Removal**: 
   - `grabcut`: Tốt nhất cho ID cards có background phức tạp
   - `threshold`: Nhanh, phù hợp với background đơn giản
   - `contour`: Phù hợp với ID cards có viền rõ ràng

3. **Performance**: 
   - Sử dụng GPU nếu có thể để tăng tốc độ detection
   - Có thể điều chỉnh `--confidence` để cân bằng giữa precision và recall

4. **Memory**: Với dataset lớn, có thể cần tăng memory hoặc xử lý theo batch nhỏ hơn

## Troubleshooting

### Lỗi thường gặp

1. **No detections found**: 
   - Giảm `--confidence` xuống 0.3-0.4
   - Kiểm tra chất lượng ảnh input

2. **Memory error**:
   - Giảm batch size hoặc xử lý từng ảnh một
   - Sử dụng CPU thay vì GPU

3. **Poor background removal**:
   - Thử các phương pháp khác nhau: `grabcut`, `threshold`, `contour`
   - Điều chỉnh parameters trong code

### Debug mode

```bash
python id_card_processor_main.py \
    --input-dir "data/IDcards" \
    --output-dir "data/processed_id_cards" \
    --log-level DEBUG
```