magicimg 1.0.3

Thư viện xử lý ảnh thông minh với hỗ trợ GPU tự động

MagicImg - Thư viện xử lý ảnh Python thông minh

MagicImg là thư viện Python mạnh mẽ để xử lý và tối ưu hóa ảnh cho OCR (Optical Character Recognition). Thư viện tự động phát hiện và cải thiện chất lượng ảnh, xoay ảnh nghiêng, và tối ưu hóa cho các engine OCR khác nhau.

✨ Tính năng chính

• 🔍 Phân tích chất lượng ảnh tự động - Đánh giá độ mờ, độ sáng, tương phản
• 🎯 Tăng cường chất lượng thông minh - Cải thiện ảnh một cách nhẹ nhàng, tránh over-processing
• 🔄 Phát hiện và sửa góc nghiêng - Tự động xoay ảnh về đúng hướng
• 🚀 Hỗ trợ GPU - Tăng tốc xử lý với CUDA (tùy chọn)
• 📊 So sánh trước/sau - Theo dõi các thay đổi chất lượng ảnh
• 🛠️ API đơn giản - Dễ sử dụng và tích hợp
• 🔧 Tùy chỉnh linh hoạt - Cấu hình chi tiết cho từng use case

📦 Cài đặt

Cài đặt cơ bản

pip install magicimg

Cài đặt với hỗ trợ GPU (tùy chọn)

pip install magicimg[gpu]
# hoặc
pip install -r requirements-gpu.txt

Cài đặt Tesseract OCR (khuyến nghị)

Tesseract cần thiết cho một số tính năng nâng cao:

Windows:

# Sử dụng winget
winget install UB-Mannheim.TesseractOCR

# Hoặc download từ: https://github.com/UB-Mannheim/tesseract/wiki

Ubuntu/Debian:

sudo apt update
sudo apt install tesseract-ocr tesseract-ocr-vie

macOS:

brew install tesseract

📖 Xem INSTALL_TESSERACT.md để biết hướng dẫn chi tiết.

🚀 Sử dụng nhanh

Ví dụ cơ bản

import magicimg

# 1. Kiểm tra thông tin ảnh
info = magicimg.get_image_info("input.jpg")
print(f"Kích thước: {info['width']}x{info['height']}")
print(f"Dung lượng: {info['file_size_mb']:.2f} MB")

# 2. Kiểm tra chất lượng ảnh
is_good, quality_info, enhanced = magicimg.check_image_quality("input.jpg")
print(f"Chất lượng tốt: {is_good}")
print(f"Điểm số: {quality_info.quality_score:.2f}")

# 3. Tăng cường chất lượng
enhanced_image = magicimg.enhance_image("input.jpg", output_path="enhanced.jpg")

# 4. Phát hiện và sửa góc nghiêng
angle = magicimg.detect_skew("input.jpg")
if abs(angle) > 0.5:
    corrected = magicimg.correct_skew("input.jpg", output_path="rotated.jpg")

# 5. Xử lý hoàn chỉnh cho OCR
result = magicimg.preprocess_for_ocr("input.jpg", output_path="processed.jpg")
if result.success:
    print(f"Các bước đã thực hiện: {', '.join(result.processing_steps)}")
    print(f"Góc xoay: {result.rotation_angle:.1f}°")
    print(f"Chất lượng cuối: {result.quality_metrics.quality_score:.2f}")

Sử dụng nâng cao với cấu hình tùy chỉnh

from magicimg import ImageProcessor

# Cấu hình tùy chỉnh
config = {
    "min_blur_index": 60.0,      # Ngưỡng độ nét tối thiểu
    "min_brightness": 150.0,     # Ngưỡng độ sáng tối thiểu  
    "min_contrast": 30.0,        # Ngưỡng tương phản tối thiểu
    "min_quality_score": 0.5,    # Điểm chất lượng tối thiểu
    "skip_rotation": False,      # Có bỏ qua xoay ảnh không
    "use_gpu": True              # Sử dụng GPU nếu có
}

# Tạo processor với cấu hình tùy chỉnh
processor = ImageProcessor(config=config, debug_dir="debug_output")

# Xử lý ảnh
result = processor.process_image("input.jpg", "output.jpg")
print(f"GPU available: {processor.has_gpu}")

📚 API Reference

Hàm tiện ích chính

get_image_info(image_path)

Lấy thông tin cơ bản về ảnh.

Tham số:

• image_path (str): Đường dẫn đến ảnh

Trả về:

{
    'width': int,           # Chiều rộng (pixels)
    'height': int,          # Chiều cao (pixels) 
    'channels': int,        # Số kênh màu
    'file_size_mb': float,  # Dung lượng file (MB)
    'aspect_ratio': float   # Tỷ lệ khung hình
}

check_image_quality(image_path, **kwargs)

Kiểm tra và đánh giá chất lượng ảnh.

Tham số:

• image_path (str): Đường dẫn đến ảnh
• **kwargs: Tham số tùy chỉnh cho ImageProcessor

Trả về:

• is_good (bool): Ảnh có chất lượng tốt không
• quality_info (ImageQualityMetrics): Thông tin chi tiết về chất lượng
• enhanced_image (np.ndarray): Ảnh đã được tăng cường (nếu cần)

enhance_image(image_path, output_path=None, **kwargs)

Tăng cường chất lượng ảnh một cách nhẹ nhàng.

Tham số:

• image_path (str): Đường dẫn ảnh đầu vào
• output_path (str, optional): Đường dẫn lưu ảnh kết quả
• **kwargs: Tham số tùy chỉnh

Trả về:

• np.ndarray: Ảnh đã tăng cường (hoặc None nếu không cần)

detect_skew(image_path)

Phát hiện góc nghiêng của ảnh.

Tham số:

• image_path (str): Đường dẫn đến ảnh

Trả về:

• float: Góc nghiêng (độ), âm = nghiêng trái, dương = nghiêng phải

correct_skew(image_path, output_path=None, angle=None)

Sửa góc nghiêng của ảnh.

Tham số:

• image_path (str): Đường dẫn ảnh đầu vào
• output_path (str, optional): Đường dẫn lưu ảnh kết quả
• angle (float, optional): Góc xoay cụ thể (nếu không cung cấp sẽ tự phát hiện)

Trả về:

• np.ndarray: Ảnh đã được xoay

preprocess_for_ocr(image_path, output_path=None, **kwargs)

Xử lý ảnh hoàn chỉnh cho OCR.

Tham số:

• image_path (str): Đường dẫn ảnh đầu vào
• output_path (str, optional): Đường dẫn lưu ảnh kết quả
• **kwargs: Tham số tùy chỉnh cho ImageProcessor

Trả về:

• ProcessingResult: Kết quả xử lý chi tiết

Class ImageProcessor

Lớp chính để xử lý ảnh với cấu hình tùy chỉnh.

processor = ImageProcessor(
    debug_dir="debug",      # Thư mục lưu ảnh debug
    config={               # Cấu hình tùy chỉnh
        "min_blur_index": 60.0,
        "min_brightness": 150.0,
        "min_contrast": 30.0,
        "min_quality_score": 0.5,
        "skip_rotation": False,
        "use_gpu": True
    }
)

Phương thức chính:

• process_image(input_path, output_path): Xử lý ảnh hoàn chỉnh
• check_quality(image): Kiểm tra chất lượng ảnh
• enhance_image(image, quality_info): Tăng cường chất lượng
• detect_skew(image): Phát hiện góc nghiêng
• correct_skew(image, angle): Sửa góc nghiêng

⚙️ Cấu hình chi tiết

Tham số cấu hình mặc định

DEFAULT_CONFIG = {
    # Ngưỡng chất lượng
    "min_blur_index": 100.0,        # Độ nét tối thiểu (càng cao càng nét)
    "min_brightness": 180.0,        # Độ sáng tối thiểu (0-255)
    "min_contrast": 50.0,           # Tương phản tối thiểu
    "min_quality_score": 0.6,       # Điểm chất lượng tối thiểu (0-1)
    
    # Xử lý góc nghiêng
    "min_skew_angle": 0.5,          # Góc nghiêng tối thiểu để xoay (độ)
    "skip_rotation": False,         # Bỏ qua xoay ảnh
    
    # GPU và hiệu năng
    "use_gpu": True,                # Sử dụng GPU nếu có
    "optimize_for_gpu": True,       # Tối ưu cho GPU
    "batch_size": 4,                # Kích thước batch
    
    # Phát hiện đường kẻ
    "line_detection": {
        "min_line_length_ratio": 0.6,
        "histogram_threshold_ratio": 0.5
    }
}

Tùy chỉnh cho các use case khác nhau

Ảnh chất lượng cao:

high_quality_config = {
    "min_blur_index": 120.0,
    "min_brightness": 200.0,
    "min_contrast": 60.0,
    "min_quality_score": 0.8
}

Ảnh chất lượng thấp:

low_quality_config = {
    "min_blur_index": 40.0,
    "min_brightness": 120.0,
    "min_contrast": 20.0,
    "min_quality_score": 0.3
}

Xử lý nhanh (bỏ qua một số bước):

fast_config = {
    "skip_rotation": True,
    "use_gpu": False,
    "min_quality_score": 0.4
}

🔧 Debug và Troubleshooting

Bật chế độ debug

from magicimg import ImageProcessor

# Tạo processor với debug
processor = ImageProcessor(debug_dir="debug_output")
result = processor.process_image("input.jpg", "output.jpg")

# Kiểm tra thư mục debug_output để xem các bước xử lý

Kiểm tra thông tin hệ thống

import magicimg
magicimg.print_system_info()

Các lỗi thường gặp

1. Lỗi import torch (GPU):

ImportError: No module named 'torch'

Giải pháp: Cài đặt PyTorch:

pip install torch torchvision

2. Lỗi Tesseract:

TesseractNotFoundError

Giải pháp: Cài đặt Tesseract OCR (xem phần cài đặt ở trên)

3. Lỗi GPU:

CUDA out of memory

Giải pháp: Giảm batch_size hoặc tắt GPU:

config = {"use_gpu": False, "batch_size": 1}

Logging

import logging
logging.basicConfig(level=logging.DEBUG)

# Bây giờ sẽ thấy log chi tiết
result = magicimg.preprocess_for_ocr("input.jpg")

📊 So sánh hiệu suất

Test với ảnh thật

# Chạy test tập trung
python tests/test_focused_apis.py

# Chạy test toàn diện
python tests/test_pip_apis.py

Benchmark

import time
import magicimg

# Test thời gian xử lý
start_time = time.time()
result = magicimg.preprocess_for_ocr("large_image.jpg")
processing_time = time.time() - start_time

print(f"Thời gian xử lý: {processing_time:.2f}s")
print(f"GPU được sử dụng: {result.success}")

🤝 Đóng góp

Chúng tôi hoan nghênh mọi đóng góp! Vui lòng:

1. Fork repository
2. Tạo feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Tạo Pull Request

📄 License

Dự án này được phân phối dưới giấy phép MIT. Xem LICENSE để biết thêm chi tiết.

🆕 Changelog

v1.0.2 (Latest)

• ✅ Tối ưu hóa enhancement để tránh over-processing
• ✅ Cải thiện phát hiện góc nghiêng
• ✅ Thêm so sánh trước/sau xử lý
• ✅ Sửa lỗi GPU memory management
• ✅ Cập nhật documentation chi tiết

v1.0.1

• ✅ Sửa lỗi API parameters
• ✅ Đồng bộ version numbers
• ✅ Cải thiện error handling

v1.0.0

• 🎉 Phiên bản đầu tiên
• ✅ Hỗ trợ GPU với CUDA
• ✅ API đơn giản và mạnh mẽ
• ✅ Tự động phát hiện và xử lý ảnh

📞 Hỗ trợ

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Wiki

---

⭐ Nếu thấy hữu ích, hãy cho chúng tôi một star trên GitHub!