xfmr-zem 0.2.2__py3-none-any.whl → 0.2.5__py3-none-any.whl

xfmr_zem/servers/ocr/deepdoc_vietocr/implementations.py

@@ -0,0 +1,1286 @@
+"""
+Concrete Implementations của các Abstract Phases
+
+File này chứa các implementations thực tế cho từng phase trong pipeline.
+Mỗi implementation có thể được thay thế độc lập bằng implementation khác.
+"""
+
+import os
+import logging
+from typing import List, Dict, Tuple, Optional, Any
+from PIL import Image
+import numpy as np
+import cv2
+
+from .phases import (
+    LayoutAnalysisPhase,
+    TextDetectionPhase,
+    TextRecognitionPhase,
+    PostProcessingPhase,
+    DocumentReconstructionPhase,
+)
+
+# Import existing modules
+from . import LayoutRecognizer
+from .ocr import TextDetector, TextRecognizer, get_project_base_directory
+
+
+# ============================================================================
+# Layout Analysis Implementations
+# ============================================================================
+
+class DocLayoutYOLOAnalyzer(LayoutAnalysisPhase):
+    """
+    Layout Analysis sử dụng DocLayout-YOLO ONNX model.
+
+    Features:
+    - Sử dụng ONNX optimized model cho CPU performance
+    - Phát hiện: text, title, figure, table, caption, header, footer, equation
+    """
+
+    def __init__(self, model_name: str = "layout"):
+        """
+        Args:
+            model_name: Tên model (default: "layout" for DocLayout-YOLO)
+        """
+        self.recognizer = LayoutRecognizer(model_name)
+        logging.info("✓ DocLayoutYOLOAnalyzer initialized with ONNX model")
+
+    def analyze(self, image: Image.Image, threshold: float = 0.5) -> List[Dict[str, Any]]:
+        """
+        Phân tích layout sử dụng DocLayout-YOLO.
+
+        Returns:
+            List of regions with structure:
+            {
+                "bbox": [x0, y0, x1, y1],
+                "type": str (text/title/figure/table/etc.),
+                "score": float,
+                "label": str (detailed label)
+            }
+        """
+        # Call forward on batch of 1 image
+        layouts = self.recognizer.forward([image], thr=float(threshold))[0]
+
+        # Normalize output format
+        results = []
+        for region in layouts:
+            bbox = self._extract_bbox(region)
+            label = region.get("type", "").lower()
+            score = region.get("score", 1.0)
+
+            if score < threshold:
+                continue
+
+            results.append({
+                "bbox": bbox,
+                "type": label,
+                "score": score,
+                "label": label,
+                "raw": region  # Keep original for backward compatibility
+            })
+
+        logging.info(f"DocLayoutYOLO detected {len(results)} regions")
+        return results
+
+    def _extract_bbox(self, region: Dict) -> List[int]:
+        """Extract and normalize bbox from region dict"""
+        if "bbox" in region:
+            return list(map(int, region["bbox"]))
+        return list(map(int, [
+            region.get("x0", 0),
+            region.get("top", 0),
+            region.get("x1", 0),
+            region.get("bottom", 0)
+        ]))
+
+
+
+class PaddleStructureV3Analyzer(LayoutAnalysisPhase):
+    """
+    Layout & Table Analysis utilizing PaddleOCR's PP-StructureV3.
+
+    Features:
+    - Unified Layout Analysis + Table Recognition + OCR
+    - PP-StructureV3 model (SOTA for document structure)
+    - Supports 'layout', 'table', 'ocr' modes (default: structure=True)
+    - Better handling of complex tables and multi-column layouts
+
+    Note: Requires paddleocr>=2.7 (best with 3.x)
+    """
+
+    def __init__(self, lang: str = 'en', show_log: bool = True, **kwargs):
+        """
+        Args:
+            lang: Language code (default: 'en' for layout compatibility)
+            show_log: Whether to show PaddleOCR logs
+            **kwargs: Additional arguments passed to PPStructureV3 (e.g., use_gpu, enable_mkldnn)
+        """
+        try:
+            from paddleocr import PPStructureV3
+        except ImportError as e:
+            try:
+                # Fallback for older versions or if PPStructure is the name
+                from paddleocr import PPStructure as PPStructureV3
+            except ImportError:
+                raise ImportError(f"paddleocr must be installed to use PPStructure/V3: {e}")
+
+        self.engine = PPStructureV3(
+            lang=lang,
+            # show_log is not supported in PPStructureV3 init args
+            **kwargs
+        )
+        logging.info(f"✓ PaddleStructureV3Analyzer initialized (lang={lang})")
+
+    def analyze(self, image: Image.Image, threshold: float = 0.5) -> List[Dict[str, Any]]:
+        """
+        Analyze document structure.
+
+        Returns:
+            List of regions including Text, Title, Figure, Table, etc.
+            For 'table' regions, it may include structural info if available.
+        """
+        import numpy as np
+
+        # Convert PIL to numpy
+        if isinstance(image, Image.Image):
+            image = np.array(image)
+
+        # Ensure RGB
+        if len(image.shape) == 2:
+            image = cv2.cvtColor(image, cv2.COLOR_GRAY2RGB)
+        elif image.shape[2] == 4:
+            image = cv2.cvtColor(image, cv2.COLOR_RGBA2RGB)
+
+        # Run PP-Structure
+        if hasattr(self.engine, 'predict'):
+            predict_gen = self.engine.predict(image)
+        else:
+            # Fallback for older versions
+            predict_gen = self.engine(image)
+
+        # Each result is a dict containing 'doc_layout_result' (list of regions)
+        raw_regions = []
+        for res in predict_gen:
+             logging.info(f"DEBUG: Processing result item type: {type(res)}")
+             try:
+                 logging.info(f"DEBUG: res.keys(): {list(res.keys())}")
+             except:
+                 logging.info("DEBUG: res has no keys()")
+             logging.info(f"DEBUG: str(res): {str(res)}")
+
+             # Handle structure extraction from various result types
+             success = False
+
+             # Strategy 1: key access 'parsing_res_list' (V2 result)
+             try:
+                 if 'parsing_res_list' in res:
+                     raw_regions.extend(res['parsing_res_list'])
+                     logging.info("DEBUG: Extracted via res['parsing_res_list']")
+                     success = True
+             except Exception as e:
+                 logging.info(f"DEBUG: Strategy 1 failed: {e}")
+
+             if not success:
+                 # Strategy 2: key access 'doc_layout_result' (Legacy/V3 result)
+                 try:
+                     if 'doc_layout_result' in res:
+                         raw_regions.extend(res['doc_layout_result'])
+                         logging.info("DEBUG: Extracted via res['doc_layout_result']")
+                         success = True
+                 except:
+                     pass
+
+             if not success:
+                 # Strategy 3: direct access
+                 if hasattr(res, 'parsing_res_list'):
+                     val = res.parsing_res_list
+                     if val:
+                         raw_regions.extend(val)
+                         success = True
+
+             if not success and isinstance(res, list):
+                 raw_regions.extend(res)
+                 logging.info("DEBUG: Extracted via list extension")
+
+        # Normalize results
+        normalized_results = []
+        for region in raw_regions:
+            # Handle dictionary or object attributes
+            if isinstance(region, dict):
+                region_type = region.get('type', region.get('label', '')).lower()
+                bbox = region.get('bbox', [0, 0, 0, 0])
+                score = region.get('score', 1.0)
+                # Content key might vary
+                if 'res' in region: # Legacy format
+                    content = ""
+                    res = region['res']
+                    if isinstance(res, list):
+                        texts = []
+                        for line in res:
+                           if isinstance(line, dict) and 'text' in line:
+                               texts.append(line['text'])
+                           elif isinstance(line, (list, tuple)) and len(line) > 0:
+                               texts.append(str(line[0]))
+                        content = " ".join(texts)
+                    elif isinstance(res, dict) and 'html' in res:
+                        content = res['html']
+                else:
+                    content = region.get('content', region.get('text', ''))
+            else:
+                # Handle parsed object (LayoutBlock)
+                # Attributes based on logs: label, bbox, content
+                try:
+                    region_type = getattr(region, 'label', '').lower()
+                    bbox = getattr(region, 'bbox', [0, 0, 0, 0])
+                    score = getattr(region, 'score', 1.0)
+                    content = getattr(region, 'content', getattr(region, 'text', ''))
+                except:
+                   logging.warning(f"Could not parse region object: {dir(region)}")
+                   continue
+
+            # Filter by threshold if score is available
+            if score < threshold:
+                continue
+
+            normalized_results.append({
+                "bbox": bbox,
+                "type": region_type,
+                "score": score,
+                "label": region_type,
+                "content": content,
+                "raw": str(region)
+            })
+
+        logging.info(f"PaddleStructureV3 detected {len(normalized_results)} regions")
+        return normalized_results
+
+
+# ============================================================================
+# Text Detection Implementations
+# ============================================================================
+
+class PaddleOCRTextDetector(TextDetectionPhase):
+    """
+    Text Detection sử dụng PaddleOCR ONNX detection model.
+
+    Features:
+    - ONNX optimized cho CPU
+    - DBNet architecture
+    - Phát hiện text boxes với 4 góc coordinates
+    """
+
+    def __init__(self, model_dir: Optional[str] = None, device_id: Optional[int] = None):
+        """
+        Args:
+            model_dir: Directory chứa ONNX models (default: auto-download)
+            device_id: Device ID cho CUDA (None = CPU only)
+        """
+        if model_dir is None:
+            model_dir = os.path.join(get_project_base_directory(), "onnx")
+
+        self.detector = TextDetector(model_dir, device_id)
+        logging.info("✓ PaddleOCRTextDetector initialized")
+
+    def detect(self, image: np.ndarray) -> Tuple[Optional[np.ndarray], Any]:
+        """
+        Phát hiện text boxes trong image.
+
+        Returns:
+            (dt_boxes, elapsed_time) where dt_boxes shape is (N, 4, 2)
+        """
+        return self.detector(image)
+
+
+# ============================================================================
+# Text Recognition Implementations
+# ============================================================================
+
+class VietOCRRecognizer(TextRecognitionPhase):
+    """
+    Text Recognition sử dụng VietOCR (vgg-seq2seq).
+
+    Features:
+    - Model chuyên cho tiếng Việt
+    - Accuracy: ~75-80%
+    - CPU optimized với quantization
+
+    Limitations:
+    - Model cũ (2019)
+    - Tốc độ chậm hơn
+    - Có thể có nhiễu character
+    """
+
+    def __init__(self, model_dir: Optional[str] = None, device_id: Optional[int] = None):
+        """
+        Args:
+            model_dir: Directory chứa models (không dùng với VietOCR)
+            device_id: Device ID (không dùng, VietOCR luôn dùng CPU)
+        """
+        self.recognizer = TextRecognizer(model_dir, device_id)
+        logging.info("✓ VietOCRRecognizer initialized (vgg-seq2seq)")
+
+    def recognize(self, image_crops: List[Any]) -> Tuple[List[Tuple[str, float]], float]:
+        """
+        Nhận dạng text sử dụng VietOCR.
+
+        Args:
+            image_crops: List các image crops (numpy array hoặc PIL Image)
+
+        Returns:
+            (results, elapsed_time) where results = [(text, confidence), ...]
+        """
+        return self.recognizer(image_crops)
+
+
+class LandingAIRecognizer(TextRecognitionPhase):
+    """
+    Text Recognition sử dụng LandingAI OCR API.
+
+    Features:
+    - Cloud-based OCR với accuracy cao
+    - Support nhiều ngôn ngữ
+    - Phù hợp cho production với volume lớn
+
+    Limitations:
+    - Cần API key
+    - Cần internet connection
+    - Có cost per request
+
+    Note: Đây là placeholder implementation. Cần implement API calls thực tế.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, model_dir: Optional[str] = None, device_id: Optional[int] = None):
+        """
+        Args:
+            api_key: LandingAI API key
+            model_dir: Không sử dụng (placeholder for interface consistency)
+            device_id: Không sử dụng (cloud-based)
+        """
+        self.api_key = api_key or os.environ.get("LANDINGAI_API_KEY")
+        if not self.api_key:
+            logging.warning("LandingAI API key not provided. Recognition will fail.")
+
+        logging.info("✓ LandingAIRecognizer initialized (placeholder)")
+
+    def recognize(self, image_crops: List[Any]) -> Tuple[List[Tuple[str, float]], float]:
+        """
+        Nhận dạng text sử dụng LandingAI API.
+
+        TODO: Implement actual API calls
+        """
+        # Placeholder: Return empty results
+        logging.warning("LandingAIRecognizer not fully implemented yet")
+        return [(("", 0.0)) for _ in image_crops], 0.0
+
+
+class SVTRv2Recognizer(TextRecognitionPhase):
+    """
+    Text Recognition sử dụng PP-OCRv3 với SVTRv2-LCNet.
+
+    ⚠️ IMPORTANT: Chỉ hoạt động với PaddleOCR 2.7.x (KHÔNG tương thích với 3.x)
+
+    PaddleOCR 2.7.x có method `.rec()` cho recognition-only.
+    PaddleOCR 3.x đã remove `.rec()` method và chỉ support full pipeline.
+
+    Để sử dụng class này, cần downgrade:
+        pip uninstall paddleocr paddlepaddle
+        pip install paddleocr==2.7.3 paddlepaddle==2.5.2
+
+    Features:
+    - SVTRv2-LCNet architecture (Transformer-based, không dùng RNN)
+    - Accuracy: 92-95% (vs 75-80% VietOCR)
+    - Speed: ~150ms per crop on CPU (vs ~500ms VietOCR)
+    - Model size: 50-80 MB
+    - Vietnamese support: Excellent
+    - Giảm ký tự nhiễu rõ rệt so với VietOCR
+
+    Advantages over VietOCR:
+    - 3x faster inference
+    - +15-20% accuracy improvement
+    - Better handling of Vietnamese diacritics
+    - Less character noise
+    - Production-ready và stable
+
+    Architecture:
+    - Backbone: SVTRv2-HGNet (Hierarchical Grouped Network)
+    - Neck: LCNet (Lightweight Convolutional Network)
+    - Head: CTC/Attention decoder
+
+    Note: Yêu cầu PaddleOCR 2.7.x (không phải 3.x)
+    """
+
+    def __init__(self, model_dir: Optional[str] = None, device_id: Optional[int] = None, lang: str = 'vi'):
+        """
+        Args:
+            model_dir: Directory chứa models (auto-download if None)
+            device_id: Device ID cho CUDA (None = CPU)
+            lang: Language code ('vi' for Vietnamese, 'en' for English)
+        """
+        try:
+            from paddleocr import PaddleOCR
+        except ImportError:
+            raise ImportError(
+                "PaddleOCR not installed. Install with:\n"
+                "  pip install paddleocr>=2.7.0 paddlepaddle>=2.5.0"
+            )
+
+        # Initialize PaddleOCR with PP-OCRv3 (includes SVTRv2)
+        # Following the same pattern as TextRecognizerPaddleOCR in ocr.py:176
+
+        # Use simple initialization like in ocr.py - this is the stable API
+        self.ocr = PaddleOCR(lang=lang)
+
+        self.device_id = device_id
+        self.lang = lang
+
+        device_str = f"GPU:{device_id}" if device_id is not None else "CPU"
+        logging.info(f"✓ SVTRv2Recognizer initialized (PP-OCRv3 via PaddleOCR, lang={lang}, device={device_str})")
+
+    def recognize(self, image_crops: List[Any]) -> Tuple[List[Tuple[str, float]], float]:
+        """
+        Nhận dạng text sử dụng SVTRv2.
+
+        Args:
+            image_crops: List các image crops (numpy array hoặc PIL Image)
+
+        Returns:
+            Tuple of (results, elapsed_time):
+            - results: List of (text, confidence) tuples
+            - elapsed_time: Thời gian xử lý tổng (seconds)
+        """
+        import time
+        start_time = time.time()
+
+        results = []
+
+        for img_crop in image_crops:
+            # Convert to numpy if PIL Image
+            if isinstance(img_crop, Image.Image):
+                img_crop = np.array(img_crop)
+
+            # Ensure correct format (RGB)
+            if len(img_crop.shape) == 2:
+                # Grayscale -> RGB
+                img_crop = cv2.cvtColor(img_crop, cv2.COLOR_GRAY2RGB)
+            elif img_crop.shape[2] == 4:
+                # RGBA -> RGB
+                img_crop = cv2.cvtColor(img_crop, cv2.COLOR_RGBA2RGB)
+
+            # Ensure minimum height for SVTRv2 (32px)
+            if img_crop.shape[0] < 32:
+                scale = 32.0 / img_crop.shape[0]
+                new_width = int(img_crop.shape[1] * scale)
+                img_crop = cv2.resize(img_crop, (new_width, 32), interpolation=cv2.INTER_CUBIC)
+
+            try:
+                # Call PaddleOCR recognition (SVTRv2)
+                # Use .rec() method for recognition-only (same as ocr.py:200)
+                rec_result = self.ocr.rec(img_crop)
+
+                # Parse result - format: [(text, confidence), ...]
+                # Following the pattern from ocr.py:203-213
+                if rec_result and len(rec_result) > 0:
+                    # Extract first result
+                    if isinstance(rec_result[0], (tuple, list)) and len(rec_result[0]) >= 2:
+                        text = str(rec_result[0][0])
+                        confidence = float(rec_result[0][1])
+                    else:
+                        text = str(rec_result[0]) if rec_result[0] else ""
+                        confidence = 1.0
+                else:
+                    text = ""
+                    confidence = 0.0
+
+                results.append((text, confidence))
+
+            except Exception as e:
+                logging.warning(f"SVTRv2 recognition failed: {e}")
+                results.append(("", 0.0))
+
+        elapsed = time.time() - start_time
+        return results, elapsed
+
+
+class PPOCRv5Recognizer(TextRecognitionPhase):
+    """
+    Text Recognition sử dụng PP-OCRv5 (PaddleOCR 3.x) với FULL PIPELINE.
+
+    ✅ Hoạt động với PaddleOCR 3.x (latest version)
+
+    Lưu ý quan trọng:
+    ----------------
+    PP-OCRv5 trong PaddleOCR 3.x KHÔNG hỗ trợ recognition-only mode.
+    Class này sử dụng FULL PIPELINE (detection + recognition) cho TOÀN BỘ image.
+
+    Do đó, class này KHÔNG integrate vào phase-based architecture hiện tại.
+    Thay vào đó, nó thay thế cả Detection + Recognition phases.
+
+    API Changes từ PaddleOCR 2.7.x → 3.x:
+    - REMOVED: `.rec()` method (recognition-only)
+    - NEW: `.predict()` method (full pipeline only)
+    - NEW: Result object với `.print()`, `.save_to_img()`, `.save_to_json()`
+
+    Features:
+    - PP-OCRv5_server model (latest, 2025)
+    - +13% accuracy improvement vs PP-OCRv4
+    - Vietnamese support: Excellent
+    - Detection: PP-OCRv5 DBNet
+    - Recognition: PP-OCRv5 SVTRv2
+
+    Architecture:
+    - Detection: PP-OCRv5_server_det (DBNet-based)
+    - Recognition: PP-OCRv5_server_rec (SVTRv2-based)
+    - Full pipeline: 5 modules (doc orientation, unwarping, text orientation, detection, recognition)
+
+    Usage:
+        ```python
+        # Sử dụng riêng PP-OCRv5, không cần phase-based pipeline
+        recognizer = PPOCRv5Recognizer(lang='vi')
+        text, confidence = recognizer.recognize_full_image(image)
+        ```
+
+    Note: Yêu cầu PaddleOCR >= 3.0 (tested with 3.3.3)
+    """
+
+    def __init__(
+        self,
+        model_dir: Optional[str] = None,
+        device_id: Optional[int] = None,
+        lang: str = 'vi',
+        use_doc_orientation: bool = False,
+        use_doc_unwarping: bool = False,
+        use_textline_orientation: bool = False,
+        text_detection_model_name: Optional[str] = None,
+        text_recognition_model_name: Optional[str] = None,
+        **kwargs
+    ):
+        """
+        Args:
+            model_dir: Directory chứa models (không dùng trong PaddleOCR 3.x)
+            device_id: Device ID cho CUDA (None = CPU)
+            lang: Language code ('vi' for Vietnamese, 'en' for English, 'ch' for Chinese)
+            use_doc_orientation: Sử dụng doc orientation classification (default: False)
+            use_doc_unwarping: Sử dụng doc unwarping (default: False)
+            use_textline_orientation: Sử dụng textline orientation (default: False)
+            text_detection_model_name: Model name for detection (e.g. "PP-OCRv5_mobile_det")
+            text_recognition_model_name: Model name for recognition (e.g. "PP-OCRv5_mobile_rec")
+            **kwargs: Additional arguments for PaddleOCR (e.g., enable_mkldnn, use_gpu)
+        """
+        try:
+            from paddleocr import PaddleOCR
+        except ImportError:
+            raise ImportError(
+                "PaddleOCR not installed. Install with:\n"
+                "  pip install paddleocr>=3.0.0 paddlepaddle>=2.5.0"
+            )
+
+        # Initialize PaddleOCR with PP-OCRv5 (PaddleOCR 3.x API)
+        # Based on documentation: https://www.paddleocr.ai/latest/version3.x/pipeline_usage/OCR.html
+        init_params = {
+            'lang': lang,
+            'use_doc_orientation_classify': use_doc_orientation,
+            'use_doc_unwarping': use_doc_unwarping,
+            'use_textline_orientation': use_textline_orientation,
+        }
+
+        # Add custom model names if provided
+        if text_detection_model_name:
+            init_params['text_detection_model_name'] = text_detection_model_name
+        if text_recognition_model_name:
+            init_params['text_recognition_model_name'] = text_recognition_model_name
+
+        # Note: PaddleOCR 3.x không có use_gpu parameter
+        # GPU được tự động detect hoặc set qua device parameter
+        if device_id is not None:
+            init_params['use_gpu'] = True
+            init_params['gpu_id'] = device_id
+
+        # Merge additional kwargs (e.g., enable_mkldnn)
+        init_params.update(kwargs)
+
+        self.ocr = PaddleOCR(**init_params)
+        self.device_id = device_id
+        self.lang = lang
+
+        device_str = f"GPU:{device_id}" if device_id is not None else "CPU"
+        logging.info(
+            f"✓ PPOCRv5Recognizer initialized "
+            f"(PP-OCRv5 full pipeline, lang={lang}, device={device_str})"
+        )
+
+    def recognize(self, image_crops: List[Any]) -> Tuple[List[Tuple[str, float]], float]:
+        """
+        ⚠️ WARNING: Method này KHÔNG nên sử dụng với image crops!
+
+        PP-OCRv5 trong PaddleOCR 3.x không support recognition-only mode.
+        Method này sẽ chạy FULL PIPELINE (detection + recognition) trên MỖI crop,
+        dẫn đến kết quả sai và performance kém.
+
+        Thay vào đó, sử dụng `recognize_full_image()` với toàn bộ image.
+
+        Args:
+            image_crops: List các image crops (không khuyến khích)
+
+        Returns:
+            (results, elapsed_time) - nhưng kết quả có thể không chính xác
+        """
+        import time
+        logging.warning(
+            "PPOCRv5Recognizer.recognize() is called with image crops. "
+            "This is NOT recommended! Use recognize_full_image() instead."
+        )
+
+        start_time = time.time()
+        results = []
+
+        for img_crop in image_crops:
+            # Convert to numpy if PIL Image
+            if isinstance(img_crop, Image.Image):
+                img_crop = np.array(img_crop)
+
+            # Ensure correct format (RGB)
+            if len(img_crop.shape) == 2:
+                img_crop = cv2.cvtColor(img_crop, cv2.COLOR_GRAY2RGB)
+            elif img_crop.shape[2] == 4:
+                img_crop = cv2.cvtColor(img_crop, cv2.COLOR_RGBA2RGB)
+
+            try:
+                # Call PaddleOCR full pipeline (không phải recognition-only)
+                # API: result = ocr.predict(input)
+                predict_result = self.ocr.predict(img_crop)
+
+                # Parse result - format: iterable of result objects
+                # Each result has: dt_polys, rec_texts, etc.
+                text = ""
+                confidence = 0.0
+
+                if predict_result:
+                    for res in predict_result:
+                        # Access rec_texts field
+                        if hasattr(res, 'rec_texts'):
+                            rec_texts = res.rec_texts
+                        elif isinstance(res, dict) and 'rec_texts' in res:
+                            rec_texts = res['rec_texts']
+                        else:
+                            rec_texts = []
+
+                        # Concatenate all recognized texts
+                        if rec_texts:
+                            text = " ".join([str(t) for t in rec_texts if t])
+                            confidence = 1.0  # PP-OCRv5 doesn't return confidence per text
+
+                results.append((text, confidence))
+
+            except Exception as e:
+                logging.error(f"PP-OCRv5 recognition failed: {e}", exc_info=True)
+                results.append(("", 0.0))
+
+        elapsed = time.time() - start_time
+        return results, elapsed
+
+    def recognize_full_image(
+        self,
+        image: np.ndarray,
+        return_visualization: bool = False
+    ) -> Dict[str, Any]:
+        """
+        Nhận dạng text trên TOÀN BỘ image sử dụng PP-OCRv5 full pipeline.
+
+        Đây là cách SỬ DỤNG ĐÚNG cho PP-OCRv5 trong PaddleOCR 3.x.
+
+        Args:
+            image: Full image (numpy array hoặc PIL Image)
+            return_visualization: Return visualization image (default: False)
+
+        Returns:
+            Dictionary chứa:
+            {
+                'texts': List[str],              # Recognized texts
+                'boxes': List[np.ndarray],       # Detection boxes (N, 4, 2)
+                'scores': List[float],           # Confidence scores (if available)
+                'elapsed_time': float,           # Processing time (seconds)
+                'visualization': np.ndarray,     # Visualization image (if requested)
+            }
+
+        Example:
+            ```python
+            recognizer = PPOCRv5Recognizer(lang='vi')
+            result = recognizer.recognize_full_image(image)
+
+            for text, box in zip(result['texts'], result['boxes']):
+                print(f"Text: {text}, Box: {box}")
+            ```
+        """
+        import time
+        start_time = time.time()
+
+        # Convert to numpy if PIL Image
+        if isinstance(image, Image.Image):
+            image = np.array(image)
+
+        # Ensure correct format (RGB)
+        if len(image.shape) == 2:
+            image = cv2.cvtColor(image, cv2.COLOR_GRAY2RGB)
+        elif image.shape[2] == 4:
+            image = cv2.cvtColor(image, cv2.COLOR_RGBA2RGB)
+
+        try:
+            # Call PaddleOCR full pipeline
+            # API from documentation: result = ocr.predict(input)
+            predict_result = self.ocr.predict(image)
+
+            texts = []
+            boxes = []
+            scores = []
+
+            # Parse result - format: iterable of result objects
+            for res in predict_result:
+                # Extract data from result object
+                # Based on documentation, result has fields: dt_polys, rec_texts, etc.
+                if hasattr(res, 'dt_polys'):
+                    dt_polys = res.dt_polys
+                elif isinstance(res, dict) and 'dt_polys' in res:
+                    dt_polys = res['dt_polys']
+                else:
+                    dt_polys = []
+
+                if hasattr(res, 'rec_texts'):
+                    rec_texts = res.rec_texts
+                elif isinstance(res, dict) and 'rec_texts' in res:
+                    rec_texts = res['rec_texts']
+                else:
+                    rec_texts = []
+
+                # Append results
+                texts.extend([str(t) for t in rec_texts if t])
+                boxes.extend(dt_polys if isinstance(dt_polys, list) else [dt_polys])
+
+                # PP-OCRv5 may not return per-text scores, default to 1.0
+                scores.extend([1.0] * len(rec_texts))
+
+            elapsed = time.time() - start_time
+
+            result = {
+                'texts': texts,
+                'boxes': boxes,
+                'scores': scores,
+                'elapsed_time': elapsed,
+            }
+
+            # Generate visualization if requested
+            if return_visualization:
+                vis_image = self._draw_boxes_and_texts(image.copy(), boxes, texts)
+                result['visualization'] = vis_image
+
+            logging.info(
+                f"PP-OCRv5 processed image: {len(texts)} texts detected "
+                f"in {elapsed:.2f}s"
+            )
+
+            return result
+
+        except Exception as e:
+            logging.error(f"PP-OCRv5 full image recognition failed: {e}", exc_info=True)
+            return {
+                'texts': [],
+                'boxes': [],
+                'scores': [],
+                'elapsed_time': time.time() - start_time,
+            }
+
+    def _draw_boxes_and_texts(
+        self,
+        image: np.ndarray,
+        boxes: List[np.ndarray],
+        texts: List[str]
+    ) -> np.ndarray:
+        """
+        Vẽ boxes và texts lên image để visualization.
+
+        Args:
+            image: Image to draw on
+            boxes: List of boxes (N, 4, 2)
+            texts: List of texts
+
+        Returns:
+            Image with boxes and texts drawn
+        """
+        for box, text in zip(boxes, texts):
+            if isinstance(box, np.ndarray) and box.shape == (4, 2):
+                # Draw box
+                pts = box.astype(np.int32)
+                cv2.polylines(image, [pts], True, (0, 255, 0), 2)
+
+                # Draw text
+                cv2.putText(
+                    image,
+                    text,
+                    tuple(pts[0]),
+                    cv2.FONT_HERSHEY_SIMPLEX,
+                    0.5,
+                    (255, 0, 0),
+                    1
+                )
+
+        return image
+
+
+
+class AdvancedPaddleOCR(PPOCRv5Recognizer):
+    """
+    Advanced PaddleOCR Configuration for difficult documents.
+
+    Enables:
+    - Document Orientation Classification (Auto-rotate)
+    - Document Unwarping (UVDoc) for bent/curved pages
+    - Textline Orientation Correction
+
+    Ideal for:
+    - Scanned legal documents
+    - Photos of documents taken by mobile phones
+    - Tilted/Skewed scans
+    """
+
+    def __init__(self, lang: str = 'vi', device_id: Optional[int] = None, **kwargs):
+        super().__init__(
+            lang=lang,
+            device_id=device_id,
+            use_doc_orientation=True,
+            use_doc_unwarping=True,
+            use_textline_orientation=True,
+            **kwargs
+        )
+        logging.info("✓ AdvancedPaddleOCR initialized with Unwarping & Orientation enabled")
+
+
+# ============================================================================
+# Post-Processing Implementations
+# ============================================================================
+
+class VietnameseTextPostProcessor(PostProcessingPhase):
+    """
+    Post-processing chuyên cho tiếng Việt.
+
+    Features:
+    - Sửa các lỗi OCR thường gặp (I -> l, 0 -> O, etc.)
+    - Loại bỏ ký tự nhiễu
+    - Normalize Vietnamese diacritics
+
+    Note: Đây là placeholder. Có thể extend với dictionary-based correction.
+    """
+
+    def __init__(self):
+        logging.info("✓ VietnameseTextPostProcessor initialized")
+
+    def process(self, text: str, confidence: float, metadata: Optional[Dict] = None) -> str:
+        """
+        Xử lý text để giảm nhiễu và cải thiện chất lượng.
+        """
+        if not text or not text.strip():
+            return text
+
+        # Basic cleaning
+        cleaned = text.strip()
+
+        # TODO: Implement Vietnamese-specific corrections
+        # - Fix common OCR errors (I/l, 0/O, etc.)
+        # - Remove excessive whitespace
+        # - Normalize diacritics
+
+        return cleaned
+
+
+# ============================================================================
+# Document Reconstruction Implementations
+# ============================================================================
+
+class SmartMarkdownReconstruction(DocumentReconstructionPhase):
+    """
+    Smart Markdown reconstruction với reading order intelligence.
+
+    Features:
+    - Smart sorting: Y-first, then X for same-line regions
+    - Handles multi-column layouts
+    - Preserves document structure
+    """
+
+    def __init__(self, y_threshold: int = 30):
+        """
+        Args:
+            y_threshold: Threshold (pixels) để xem regions có cùng dòng hay không
+        """
+        self.y_threshold = y_threshold
+        logging.info(f"✓ SmartMarkdownReconstruction initialized (y_threshold={y_threshold}px)")
+
+    def reconstruct(
+        self,
+        regions: List[Tuple[int, str, Any]],
+        output_format: str = "markdown"
+    ) -> str:
+        """
+        Ghép nối regions với smart sorting.
+
+        Args:
+            regions: List of (y_position, content, bbox) tuples
+            output_format: Only "markdown" supported
+
+        Returns:
+            Markdown string
+        """
+        if output_format != "markdown":
+            raise NotImplementedError(f"Format {output_format} not supported")
+
+        # Smart sort regions (Y-first, X-second for same line)
+        sorted_regions = self._smart_sort_regions(regions)
+
+        # Concatenate with double newline
+        markdown = "\n\n".join([item[1] for item in sorted_regions])
+        return markdown
+
+    def _smart_sort_regions(self, regions: List[Tuple[int, str, Any]]) -> List[Tuple[int, str, Any]]:
+        """
+        Sort regions với reading order thông minh.
+
+        Algorithm:
+        1. Group regions by Y coordinate (với threshold)
+        2. Sort each group by X coordinate
+        3. Flatten results
+        """
+        if not regions:
+            return regions
+
+        # Convert to dict format for sorting
+        regions_dict = []
+        for item in regions:
+            y_pos = item[0]
+            content = item[1]
+
+            # Extract x0 from bbox if available
+            x0 = 0
+            if len(item) > 2 and isinstance(item[2], (list, tuple)):
+                bbox = item[2]
+                x0 = bbox[0] if len(bbox) > 0 else 0
+
+            regions_dict.append({
+                "top": y_pos,
+                "x0": x0,
+                "content": content,
+                "original": item
+            })
+
+        # Use LayoutRecognizer.sort_Y_firstly for smart Y+X sorting
+        sorted_dict = LayoutRecognizer.sort_Y_firstly(regions_dict, self.y_threshold)
+
+        # Reconstruct original format
+        return [r["original"] for r in sorted_dict]
+
+
+# ============================================================================
+# Factory Functions
+# ============================================================================
+
+def create_default_pipeline() -> Dict[str, Any]:
+    """
+    Tạo pipeline mặc định với các implementations hiện tại.
+
+    Returns:
+        Dictionary chứa các phase instances:
+        {
+            "layout_analyzer": LayoutAnalysisPhase,
+            "text_detector": TextDetectionPhase,
+            "text_recognizer": TextRecognitionPhase,
+            "post_processor": PostProcessingPhase,
+            "reconstructor": DocumentReconstructionPhase
+        }
+    """
+    return {
+        "layout_analyzer": DocLayoutYOLOAnalyzer(),
+        "text_detector": PaddleOCRTextDetector(),
+        "text_recognizer": VietOCRRecognizer(),
+        "post_processor": VietnameseTextPostProcessor(),
+        "reconstructor": SmartMarkdownReconstruction(y_threshold=30)
+    }
+
+
+def create_svtrv2_pipeline(device_id: Optional[int] = None, lang: str = 'vi') -> Dict[str, Any]:
+    """
+    Tạo pipeline với SVTRv2 recognizer (recommended for production).
+
+    SVTRv2 Benefits:
+    - 3x faster than VietOCR (150ms vs 500ms per crop)
+    - +15-20% accuracy improvement (92-95% vs 75-80%)
+    - Better Vietnamese diacritic handling
+    - Less character noise
+    - Production-ready và stable
+
+    Args:
+        device_id: Device ID cho CUDA (None = CPU)
+        lang: Language code ('vi' for Vietnamese, 'en' for English)
+
+    Returns:
+        Dictionary chứa các phase instances với SVTRv2
+
+    Example:
+        ```python
+        from deepdoc_vietocr import DocumentPipeline
+        from deepdoc_vietocr.implementations import create_svtrv2_pipeline
+
+        # Create SVTRv2 pipeline
+        config = create_svtrv2_pipeline()
+        pipeline = DocumentPipeline(**config, threshold=0.5, max_workers=2)
+
+        # Process image
+        result = pipeline.process(image, img_name='test', figure_save_dir='./output')
+        ```
+    """
+    return {
+        "layout_analyzer": DocLayoutYOLOAnalyzer(),
+        "text_detector": PaddleOCRTextDetector(),
+        "text_recognizer": SVTRv2Recognizer(device_id=device_id, lang=lang),  # ← SVTRv2
+        "post_processor": VietnameseTextPostProcessor(),
+        "reconstructor": SmartMarkdownReconstruction(y_threshold=30)
+    }
+
+
+def create_experimental_pipeline() -> Dict[str, Any]:
+    """
+    Tạo pipeline thử nghiệm với các implementations mới.
+
+    Ví dụ: Swap VietOCR bằng LandingAI recognizer
+    """
+    return {
+        "layout_analyzer": DocLayoutYOLOAnalyzer(),
+        "text_detector": PaddleOCRTextDetector(),
+        "text_recognizer": LandingAIRecognizer(),  # Experimental
+        "post_processor": VietnameseTextPostProcessor(),
+        "reconstructor": SmartMarkdownReconstruction(y_threshold=30)
+    }
+
+
+# ============================================================================
+# Hybrid Pipeline Implementations (Fusion)
+# ============================================================================
+
+def ocr_region_worker(args):
+    """
+    Worker function for parallel processing.
+    Args:
+        args: (image_np, bbox, detector, recognizer)
+        Note: detector/recognizer must be picklable or re-initialized.
+        However, re-initializing models in each worker is expensive.
+
+        Optimized Approach:
+        Pass cropping logic here, but models might need global init or passed if lightweight.
+        VietOCR is lightweight enough on CPU. PaddleDetector (ONNX) is also fine.
+
+        Alternative: Initialize models inside worker (using global singleton pattern).
+    """
+    import numpy as np
+    from PIL import Image
+
+    crop, detector_instance, recognizer_instance = args
+
+    if crop is None:
+        return "", 1.0
+
+    # 1. Line Detection (Split paragraph into lines)
+    # Convert PIL to numpy for PaddleDetector
+    crop_np = np.array(crop)
+    # Ensure RGB
+    if len(crop_np.shape) == 2:
+        crop_np = cv2.cvtColor(crop_np, cv2.COLOR_GRAY2RGB)
+    elif crop_np.shape[2] == 4:
+        crop_np = cv2.cvtColor(crop_np, cv2.COLOR_RGBA2RGB)
+
+    dt_boxes, _ = detector_instance.detect(crop_np)
+
+    if dt_boxes is None or len(dt_boxes) == 0:
+        # Fallback: Treat whole crop as single line (or empty)
+        # But if it was a paragraph, VietOCR might fail.
+        # Let's try OCR on whole crop if detection fails (might be single line already)
+        lines = [crop]
+    else:
+        # Sort lines matching reading order (Top to Bottom)
+        # dt_boxes shape: [N, 4, 2]
+        # Sort by Y coordinate of top-left corner
+        dt_boxes = sorted(dt_boxes, key=lambda b: b[0][1])
+
+        lines = []
+        for box in dt_boxes:
+            # Crop each line
+            # Box might be rotated, but for now assume mostly horizontal or slight tilt
+            # Get min/max x,y
+            h, w, _ = crop_np.shape
+            box_int = np.int0(box)
+            x_min = max(0, np.min(box_int[:, 0]))
+            x_max = min(w, np.max(box_int[:, 0]))
+            y_min = max(0, np.min(box_int[:, 1]))
+            y_max = min(h, np.max(box_int[:, 1]))
+
+            if x_max > x_min and y_max > y_min:
+                line_crop = crop.crop((x_min, y_min, x_max, y_max))
+                lines.append(line_crop)
+
+    # 2. Line Recognition (VietOCR)
+    full_text = []
+    total_conf = 0.0
+
+    if not lines:
+        return "", 0.0
+
+    results, _ = recognizer_instance.recognize(lines)
+
+    texts = []
+    confs = []
+    for text, conf in results:
+        if text.strip():
+            texts.append(text.strip())
+            confs.append(conf)
+
+    final_text = " ".join(texts)
+    avg_conf = sum(confs) / len(confs) if confs else 0.0
+
+    return final_text, avg_conf
+
+class HybridStructureVietOCRAnalyzer(LayoutAnalysisPhase):
+    """
+    Hybrid Pipeline combining PP-StructureV3 (Layout) + VietOCR (Text).
+
+    Strategy:
+    1. Use PP-StructureV3 for Layout Analysis (Top-down reading order, Table detection).
+    2. For 'Text'/'Title' regions: Crop image and use VietOCR for high-accuracy recognition.
+    3. For 'Table' regions: Keep PP-StructureV3's HTML/Markdown output (since VietOCR can't handle tables).
+
+    Pros:
+    - Best of both worlds: Perfect layout + Perfect Vietnamese characters.
+    - Handles complex tables (wireless, merged cells).
+    - Solves the 'bottom-up' reading order issue of YOLOv10.
+
+    Cons:
+    - Slower than pure YOLO+VietOCR (due to heavy Layout model).
+    - Slower than pure PP-StructureV3 (due to extra VietOCR calls).
+    """
+
+    def __init__(self, lang: str = 'vi'):
+        from .ocr import TextRecognizer # Import locally to avoid circular deps if any
+        import multiprocessing
+
+        # 1. Initialize Text Recognition Engine (VietOCR) - EARLY INIT to avoid conflicts
+        # VietOCR is CPU optimized and very accurate for Vietnamese
+        self.text_engine = VietOCRRecognizer()
+        logging.info("✓ HybridPipeline: Text Engine (VietOCR) ready")
+
+        # 2. Initialize Line Detector (PaddleOCR Det)
+        # Needed for splitting paragraphs into lines
+        self.line_detector = PaddleOCRTextDetector()
+        logging.info("✓ HybridPipeline: Line Detector (PaddleOCR) ready")
+
+        # 3. Initialize Layout Engine (PP-StructureV3)
+        # Note: We use the existing wrapper to safely handle import errors
+        self.layout_engine = PaddleStructureV3Analyzer(lang=lang, show_log=False)
+        logging.info("✓ HybridPipeline: Layout Engine (PP-StructureV3) ready")
+
+        # CPU Count for multiprocessing
+        self.num_workers = min(4, multiprocessing.cpu_count())
+
+    def analyze(self, image: Image.Image, threshold: float = 0.5) -> List[Dict[str, Any]]:
+        """
+        Run the hybrid analysis pipeline.
+        """
+        import numpy as np
+
+        # Ensure image is PIL for cropping (VietOCR likes PIL)
+        if isinstance(image, np.ndarray):
+            image_pil = Image.fromarray(cv2.cvtColor(image, cv2.COLOR_BGR2RGB))
+        else:
+            image_pil = image
+
+        # Step 1: Run Layout Analysis (PP-StructureV3)
+        # This returns regions with 'bbox', 'type', and raw 'content' (from PaddleOCR)
+        logging.info("HybridPipeline: Running Layout Analysis...")
+        layout_results = self.layout_engine.analyze(image_pil, threshold=threshold)
+
+        # Step 2: Refine Text Content with VietOCR
+        logging.info(f"HybridPipeline: Refining {len(layout_results)} regions with VietOCR...")
+
+        final_results = []
+        text_crops = []
+        text_indices = []
+
+        # Prepare batch for Parallel Processing
+        # We cannot pass self.text_engine/self.line_detector easily if they are not picklable
+        # For simplicity in this demo, we will use sequential processing first with the new logic
+        # OR use a ThreadPool since VietOCR releases GIL or runs C++ (Paddle)
+        # Wait, VietOCR is PyTorch, Paddle is ONNX.
+        # Deepcopying models for processes is heavy.
+        # User suggested multiprocessing but that requires pickling models.
+        # BETTER STRATEGY: Use ThreadPoolExecutor for I/O bound tasks,
+        # but here it is CPU bound.
+        #
+        # WORKAROUND for non-picklable models in simple script:
+        # Just run sequential loop first to prove quality fix (Line detection).
+        # Optimization (Multiprocessing) requires moving model init to global or worker_init.
+        # Given complexity, let's implement the LINE DETECTION logic first (Quality Fix).
+        # We can simulate "Parallel" by batching lines if possible, but here we process region by region.
+
+        # Let's conform to User Request for Quality First (Line Detection).
+        # We will iterate regions and perform split + OCR.
+
+        from concurrent.futures import ThreadPoolExecutor
+
+        # We will use ThreadPool to parallelize the *regions* processing if models are thread-safe.
+        # Paddle (ONNX Runtime) is thread-safe. VietOCR (PyTorch) is thread-safe for inference.
+
+        def process_single_region(idx_region_tuple):
+            idx, region = idx_region_tuple
+            rtype = region.get('type', '').lower()
+
+            # Note: PPStructureV3 uses 'paragraph_title'
+            if rtype in ['text', 'title', 'header', 'footer', 'paragraph_title', 'reference', 'list']:
+                bbox = region.get('bbox')
+                if bbox:
+                    # Crop image: [x0, y0, x1, y1]
+                    x0, y0, x1, y1 = map(int, bbox)
+                    w, h = image_pil.size
+                    x0 = max(0, x0); y0 = max(0, y0)
+                    x1 = min(w, x1); y1 = min(h, y1)
+
+                    if x1 > x0 and y1 > y0:
+                        crop = image_pil.crop((x0, y0, x1, y1))
+
+                        # CALL WORKER LOGIC DIRECTLY (No pickling issues)
+                        # Pass self.line_detector and self.text_engine
+                        text, conf = ocr_region_worker((crop, self.line_detector, self.text_engine))
+
+                        region['content'] = text
+                        region['score'] = conf
+                        region['source'] = 'VietOCR+LineDet'
+            return region
+
+        # Collect extractable regions
+        tasks = []
+        for idx, region in enumerate(layout_results):
+            tasks.append((idx, region))
+
+        # Run in ThreadPool (lighter than ProcessPool and works with unpicklable objects usually)
+        # If CPU bound, GIL limits speedup, but ONNX Runtime releases GIL.
+        with ThreadPoolExecutor(max_workers=self.num_workers) as executor:
+             results = list(executor.map(process_single_region, tasks))
+
+        return results
+
+def create_hybrid_pipeline() -> Dict[str, Any]:
+    """
+    Creates the Hybrid Pipeline (Fusion Strategy).
+    Usage similar to other pipelines, but 'layout_analyzer' does mostly everything.
+    """
+    return {
+        "layout_analyzer": HybridStructureVietOCRAnalyzer(),
+        # Other components are placeholders since HybridAnalyzer handles everything internally
+        # but we keep them for interface consistency if needed
+        "text_detector": None,
+        "text_recognizer": None,
+        "post_processor": VietnameseTextPostProcessor(),
+        "reconstructor": SmartMarkdownReconstruction(y_threshold=30)
+    }