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

MagicImg là thư viện Python mạnh mẽ cho xử lý và tiền xử lý ảnh, được tối ưu cho OCR và computer vision.

🚀 Tính năng mới trong v1.0.8

• ✅ Logging Control: Hoàn toàn kiểm soát được logging levels (DEBUG/INFO/WARNING)
• ✅ Custom Logging: Hỗ trợ custom format và log to file
• ✅ Silent Mode: Chế độ WARNING level để tắt progress messages
• ✅ Debug Flexibility: Debug riêng từng module
• ✅ User Preference: Tôn trọng logging configuration của user

📦 Cài đặt

Cài đặt cơ bản

pip install magicimg

Cài đặt Tesseract OCR

Windows

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

# Thêm vào PATH
set PATH=%PATH%;C:\Program Files\Tesseract-OCR

Ubuntu/Debian

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

macOS

brew install tesseract

🎯 Sử dụng nhanh

Basic Usage

import magicimg

# Xử lý ảnh cơ bản với preserve color
result = magicimg.process_image("input.jpg", "output.jpg", preserve_color=True)
print(f"Success: {result.success}")
print(f"Processing steps: {result.processing_steps}")

# Kiểm tra chất lượng ảnh
is_good, quality_info, enhanced = magicimg.check_image_quality("input.jpg")
print(f"Quality score: {quality_info['quality_score']}")

# Tăng cường ảnh
enhanced = magicimg.enhance_image("input.jpg", "enhanced.jpg")

# Preprocessing cho OCR (tối ưu cho text recognition)
result = magicimg.preprocess_for_ocr("input.jpg", "output.jpg", preserve_color=False)

API Mode (cho Google, Anthropic, Local API)

import magicimg

# Preprocessing cho Google Vision API
success, info, output_path = magicimg.preprocess_image_for_api(
    "input.jpg", 
    provider="google",
    output_dir="./output/",
    min_quality_score=0.3
)

print(f"Success: {success}")
print(f"Output: {output_path}")
print(f"Processing steps: {info['processing_steps']}")

📚 API Reference

Core Functions

process_image(image_path, output_path=None, auto_rotate=True, preserve_color=True)

Xử lý ảnh hoàn chỉnh với tất cả các bước tối ưu.

Parameters:

• image_path (str | np.ndarray): Đường dẫn ảnh hoặc numpy array
• output_path (str, optional): Đường dẫn lưu kết quả
• auto_rotate (bool): Tự động xoay ảnh (default: True)
• preserve_color (bool): Giữ nguyên màu sắc (default: True)

Returns:

• ProcessingResult: Object chứa kết quả xử lý

check_image_quality(image_path)

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

Returns:

• tuple(bool, dict, np.ndarray): (is_good, quality_info_dict, enhanced_image)

preprocess_image_for_api(image_path, provider="google")

Tiền xử lý ảnh tối ưu cho các API nhà cung cấp.

Parameters:

• provider: "google", "anthropic", hoặc "local"

Returns:

• tuple(bool, dict, str): (success, processing_info, output_path)

Quality Enhancement Functions

enhance_image(image_path, output_path=None)

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

enhance_image_for_ocr(image_path, output_path=None)

Tối ưu ảnh đặc biệt cho OCR (chuyển binary).

Orientation & Skew Functions

detect_skew(image_path)

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

correct_skew(image_path, angle=None)

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

rotate_image(image_path, angle)

Xoay ảnh theo góc cho trước.

⚙️ Cấu hình nâng cao

Quality Thresholds

# Cấu hình ngưỡng chất lượng
config = {
    "min_blur_index": 100.0,      # Tăng yêu cầu độ nét
    "min_brightness": 200.0,      # Tăng yêu cầu độ sáng
    "min_contrast": 60.0,         # Tăng yêu cầu độ tương phản
    "min_resolution": (1200, 1600) # Tăng độ phân giải tối thiểu
}

processor = ImageProcessor(config=config)

Processing Modes

High Quality Mode (cho ảnh quan trọng)

config = {
    "min_blur_index": 120.0,
    "min_brightness": 220.0,
    "min_contrast": 70.0,
    "min_resolution": (1500, 2000)
}
result = magicimg.process_image("input.jpg", config=config, preserve_color=True)

Fast Processing Mode (cho batch processing)

config = {
    "min_blur_index": 60.0,
    "min_brightness": 160.0,
    "min_contrast": 40.0,
    "skip_rotation": True
}
result = magicimg.process_image("input.jpg", config=config)

OCR Optimization Mode

result = magicimg.preprocess_for_ocr("input.jpg", preserve_color=False)

🔍 Debug Mode

Bật chế độ DEBUG

import logging
import magicimg

# Cách 1: Bật debug trước khi import
logging.basicConfig(level=logging.DEBUG)
import magicimg  # Import sau khi set DEBUG

# Cách 2: Bật debug sau khi import
logging.getLogger().setLevel(logging.DEBUG)

Các level logging

import logging
import magicimg

# 1. DEBUG - Hiển thị tất cả thông tin
logging.basicConfig(level=logging.DEBUG)
# Sẽ hiển thị:
# - Chi tiết cấu hình
# - Các bước xử lý
# - Quality metrics
# - Line detection parameters
# - Skew detection details

# 2. INFO - Chỉ hiển thị tiến trình (mặc định)
logging.basicConfig(level=logging.INFO)
# Sẽ hiển thị:
# - 🔄 Đang xử lý: input.jpg
# - ✅ Hoàn thành: output.jpg

# 3. WARNING - Silent mode (chỉ warnings)
logging.basicConfig(level=logging.WARNING)
# Chỉ hiển thị warnings và errors

# 4. ERROR - Chỉ hiển thị errors
logging.basicConfig(level=logging.ERROR)

Custom Debug Output

import logging

# Log ra file
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(levelname)s - %(message)s',
    handlers=[logging.FileHandler('magicimg_debug.log')]
)

# Custom format
logging.basicConfig(
    level=logging.DEBUG,
    format='[%(levelname)s] %(message)s'
)

# Multiple handlers
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(message)s',
    handlers=[
        logging.FileHandler('debug.log'),
        logging.StreamHandler()  # Console output
    ]
)

Debug Quality Metrics

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

# Hiển thị chi tiết quality metrics
result = magicimg.process_image("input.jpg")
# DEBUG: Quality metrics:
#   - Blur index: 85.3
#   - Dark ratio: 0.15
#   - Brightness: 195.2
#   - Contrast: 55.8
#   - Resolution: (1200, 1600)

Debug Processing Steps

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

# Hiển thị chi tiết các bước xử lý
result = magicimg.process_image("input.jpg")
# DEBUG: Processing steps:
#   1. Loading image
#   2. Checking quality
#   3. Detecting orientation
#   4. Correcting skew (2.5 degrees)
#   5. Enhancing contrast
#   6. Saving result

Tips khi debug

1. Set DEBUG trước khi import: Để capture tất cả log messages
2. Log to file: Khi cần analyze logs sau
3. Custom format: Thêm timestamps hoặc log levels
4. WARNING level: Khi chỉ quan tâm issues
5. DEBUG specific modules:

# Debug chỉ magicimg.core
logging.getLogger('magicimg.core').setLevel(logging.DEBUG)

🔧 Troubleshooting

Common Issues

1. Tesseract error

# Windows: Thêm Tesseract vào PATH
set PATH=%PATH%;C:\Program Files\Tesseract-OCR

# Linux: Cài đặt Tesseract
sudo apt-get install tesseract-ocr

2. Memory errors với ảnh lớn

# Giảm batch_size
config = {
    "batch_size": 2
}
processor = magicimg.ImageProcessor(config=config)

3. Debug logs không hiển thị

# Đảm bảo set DEBUG trước khi import
import logging
logging.basicConfig(level=logging.DEBUG)  # ĐẶT TRƯỚC import!

import magicimg  # Import sau

# Hoặc set level sau import
logging.getLogger().setLevel(logging.DEBUG)

System Information

import magicimg
magicimg.print_system_info()
# In thông tin hệ thống và dependencies

📊 Performance Tips

1. Batch Processing

from magicimg import ImageProcessor

processor = ImageProcessor(config={"batch_size": 8})

# Xử lý nhiều ảnh cùng lúc
image_paths = ["img1.jpg", "img2.jpg", "img3.jpg"]
for path in image_paths:
    result = processor.process_image(path)
    print(f"Processed {path}: {result.success}")

2. Preserve Color vs OCR Mode

# Cho ảnh cần giữ chất lượng cao
result = magicimg.process_image("photo.jpg", preserve_color=True)

# Cho text recognition
result = magicimg.preprocess_for_ocr("document.jpg", preserve_color=False)

🧪 Testing

Run API Consistency Tests

# Test tất cả API functions
python -c "
import magicimg
print('Testing basic APIs...')
result1 = magicimg.check_image_quality('input.jpg')
result2 = magicimg.process_image('input.jpg')
result3 = magicimg.preprocess_image_for_api('input.jpg')
print('All APIs working correctly!')
"

Performance Benchmark

import time
import magicimg

start = time.time()
result = magicimg.process_image("test.jpg")
end = time.time()

print(f"Processing time: {end-start:.2f}s")
print(f"Success: {result.success}")

📝 Examples

Complete Processing Pipeline

import magicimg

def process_document(input_path, output_dir="./output/"):
    """Xử lý document hoàn chỉnh"""
    
    # 1. Kiểm tra chất lượng
    is_good, quality_info, enhanced = magicimg.check_image_quality(input_path)
    print(f"Quality score: {quality_info['quality_score']:.2f}")
    
    # 2. Xử lý với preserve color
    result = magicimg.process_image(
        input_path, 
        output_path=f"{output_dir}/processed.jpg",
        preserve_color=True
    )
    
    # 3. Tạo version cho OCR
    ocr_result = magicimg.preprocess_for_ocr(
        input_path,
        output_path=f"{output_dir}/ocr_ready.jpg", 
        preserve_color=False
    )
    
    # 4. API processing
    api_success, api_info, api_path = magicimg.preprocess_image_for_api(
        input_path,
        provider="google",
        output_dir=output_dir
    )
    
    return {
        "quality": quality_info,
        "processed": result.success,
        "ocr_ready": ocr_result.success,
        "api_ready": api_success,
        "steps": result.processing_steps
    }

# Sử dụng
results = process_document("document.jpg")
print(results)

🆕 Changelog v1.0.8

Fixed

• ✅ Sửa lỗi logging interference với user configuration
• ✅ Sửa lỗi DEBUG logs hiển thị khi không cần
• ✅ Cải thiện logging initialization
• ✅ Sửa lỗi logging handlers bị ghi đè

Improved

• 🚀 Tối ưu logging system với nhiều levels
• 🚀 Thêm custom logging format support
• 🚀 Cải thiện debug output readability
• 🚀 Silent mode cho production environment

Added

• ➕ Comprehensive logging documentation
• ➕ Debug mode examples
• ➕ Logging level control
• ➕ Module-specific debugging

🤝 Contributing

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

Distributed under the MIT License. See LICENSE for more information.

🙋‍♂️ Support

• 📧 Email: shumi2011@gmail.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Docs

---

Made with ❤️ by MagicImg Team