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:

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)

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

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)

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

# 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

# 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

# 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

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