natural-pdf 25.3.16__py3-none-any.whl

natural_pdf/elements/text.py

@@ -0,0 +1,304 @@
+"""
+Text element classes for natural-pdf.
+"""
+from typing import Dict, Any, Optional, TYPE_CHECKING
+
+from natural_pdf.elements.base import Element
+
+if TYPE_CHECKING:
+    from natural_pdf.core.page import Page
+
+
+class TextElement(Element):
+    """
+    Represents a text element in a PDF.
+    
+    This class is a wrapper around pdfplumber's character objects,
+    providing additional functionality for text extraction and analysis.
+    """
+    
+    def __init__(self, obj: Dict[str, Any], page: 'Page'):
+        """
+        Initialize a text element.
+        
+        Args:
+            obj: The underlying pdfplumber object. For OCR text elements,
+                 should include 'text', 'bbox', 'source', and 'confidence'
+            page: The parent Page object
+        """
+        # Add object_type if not present
+        if 'object_type' not in obj:
+            obj['object_type'] = 'text'
+            
+        super().__init__(obj, page)
+    
+    @property
+    def text(self) -> str:
+        """Get the text content."""
+        return self._obj.get('text', '')
+        
+    @property
+    def source(self) -> str:
+        """Get the source of this text element (pdf or ocr)."""
+        return self._obj.get('source', 'pdf')
+        
+    @property
+    def confidence(self) -> float:
+        """Get the confidence score for OCR text elements."""
+        return self._obj.get('confidence', 1.0)
+    
+    @property
+    def fontname(self) -> str:
+        """Get the font name."""
+        # First check if we have a real fontname from PDF resources
+        if 'real_fontname' in self._obj:
+            return self._obj['real_fontname']
+        # Otherwise use standard fontname
+        return self._obj.get('fontname', '') or self._obj.get('font', '')
+        
+    @property
+    def font_family(self) -> str:
+        """
+        Get a cleaner font family name by stripping PDF-specific prefixes.
+        
+        PDF font names often include prefixes like 'ABCDEF+' followed by the font name
+        or unique identifiers. This method attempts to extract a more readable font name.
+        """
+        font = self.fontname
+        
+        # Remove common PDF font prefixes (e.g., 'ABCDEF+')
+        if '+' in font:
+            font = font.split('+', 1)[1]
+            
+        # Try to extract common font family names
+        common_fonts = [
+            'Arial', 'Helvetica', 'Times', 'Courier', 'Calibri', 
+            'Cambria', 'Georgia', 'Verdana', 'Tahoma', 'Trebuchet'
+        ]
+        
+        for common in common_fonts:
+            if common.lower() in font.lower():
+                return common
+                
+        return font
+        
+    @property
+    def font_variant(self) -> str:
+        """
+        Get the font variant identifier (prefix before the '+' in PDF font names).
+        
+        PDF embeds font subsets with unique identifiers like 'AAAAAB+FontName'.
+        Different variants of the same base font will have different prefixes.
+        This can be used to differentiate text that looks different despite 
+        having the same font name and size.
+        
+        Returns:
+            The font variant prefix, or empty string if no variant is present
+        """
+        font = self.fontname
+        
+        # Extract the prefix before '+' if it exists
+        if '+' in font:
+            return font.split('+', 1)[0]
+            
+        return ""
+    
+    @property
+    def size(self) -> float:
+        """Get the font size."""
+        return self._obj.get('size', 0)
+    
+    @property
+    def color(self) -> tuple:
+        """Get the text color (RGB tuple)."""
+        # PDFs often use non-RGB values, so we handle different formats
+        # In pdfplumber, colors can be in various formats depending on the PDF
+        color = self._obj.get('non_stroking_color', (0, 0, 0))
+        
+        # If it's a single value, treat as grayscale
+        if isinstance(color, (int, float)):
+            return (color, color, color)
+        
+        # If it's a tuple of 3 values, treat as RGB
+        if isinstance(color, tuple) and len(color) == 3:
+            return color
+        
+        # If it's a tuple of 4 values, treat as CMYK and convert to approximate RGB
+        if isinstance(color, tuple) and len(color) == 4:
+            c, m, y, k = color
+            r = 1 - min(1, c + k)
+            g = 1 - min(1, m + k)
+            b = 1 - min(1, y + k)
+            return (r, g, b)
+        
+        # Default to black
+        return (0, 0, 0)
+    
+    def extract_text(self, keep_blank_chars=True, **kwargs) -> str:
+        """
+        Extract text from this element.
+        
+        Args:
+            keep_blank_chars: Whether to keep blank characters (default: True)
+            **kwargs: Additional extraction parameters
+            
+        Returns:
+            Text content
+        """
+        # For text elements, keep_blank_chars doesn't affect anything as we're
+        # simply returning the text property. Included for API consistency.
+        return self.text
+    
+    def contains(self, substring: str, case_sensitive: bool = True) -> bool:
+        """
+        Check if this text element contains a substring.
+        
+        Args:
+            substring: The substring to check for
+            case_sensitive: Whether the check is case-sensitive
+            
+        Returns:
+            True if the text contains the substring
+        """
+        if case_sensitive:
+            return substring in self.text
+        else:
+            return substring.lower() in self.text.lower()
+    
+    def matches(self, pattern: str) -> bool:
+        """
+        Check if this text element matches a regular expression pattern.
+        
+        Args:
+            pattern: Regular expression pattern
+            
+        Returns:
+            True if the text matches the pattern
+        """
+        import re
+        return bool(re.search(pattern, self.text))
+    
+    @property
+    def bold(self) -> bool:
+        """
+        Check if the text is bold based on multiple indicators in the PDF.
+        
+        PDFs encode boldness in several ways:
+        1. Font name containing 'bold' or 'black'
+        2. Font descriptor flags (bit 2 indicates bold)
+        3. StemV value (thickness of vertical stems)
+        4. Font weight values (700+ is typically bold)
+        5. Text rendering mode 2 (fill and stroke)
+        """
+        # Check font name (original method)
+        fontname = self.fontname.lower()
+        if 'bold' in fontname or 'black' in fontname or self.fontname.endswith('-B'):
+            return True
+            
+        # Check font descriptor flags if available (bit 2 = bold)
+        flags = self._obj.get('flags')
+        if flags is not None and (flags & 4) != 0:  # Check if bit 2 is set
+            return True
+            
+        # Check StemV (vertical stem width) if available
+        # Higher StemV values indicate bolder fonts
+        stemv = self._obj.get('stemv') or self._obj.get('StemV')
+        if stemv is not None and isinstance(stemv, (int, float)) and stemv > 120:
+            return True
+            
+        # Check font weight if available (700+ is typically bold)
+        weight = self._obj.get('weight') or self._obj.get('FontWeight')
+        if weight is not None and isinstance(weight, (int, float)) and weight >= 700:
+            return True
+            
+        # Check text rendering mode (mode 2 = fill and stroke, can make text appear bold)
+        render_mode = self._obj.get('render_mode')
+        if render_mode is not None and render_mode == 2:
+            return True
+        
+        # Additional check: if we have text with the same font but different paths/strokes
+        # Path widths or stroke widths can indicate boldness
+        stroke_width = self._obj.get('stroke_width') or self._obj.get('lineWidth')
+        if stroke_width is not None and isinstance(stroke_width, (int, float)) and stroke_width > 0:
+            return True
+            
+        return False
+    
+    @property
+    def italic(self) -> bool:
+        """
+        Check if the text is italic based on multiple indicators in the PDF.
+        
+        PDFs encode italic (oblique) text in several ways:
+        1. Font name containing 'italic' or 'oblique'
+        2. Font descriptor flags (bit 6 indicates italic)
+        3. Text with non-zero slant angle
+        """
+        # Check font name (original method)
+        fontname = self.fontname.lower()
+        if 'italic' in fontname or 'oblique' in fontname or self.fontname.endswith('-I'):
+            return True
+            
+        # Check font descriptor flags if available (bit 6 = italic)
+        flags = self._obj.get('flags')
+        if flags is not None and (flags & 64) != 0:  # Check if bit 6 is set
+            return True
+            
+        # Check italic angle if available
+        # Non-zero italic angle indicates italic font
+        italic_angle = self._obj.get('italic_angle') or self._obj.get('ItalicAngle')
+        if italic_angle is not None and isinstance(italic_angle, (int, float)) and italic_angle != 0:
+            return True
+            
+        return False
+    
+    def __repr__(self) -> str:
+        """String representation of the text element."""
+        preview = self.text[:10] + '...' if len(self.text) > 10 else self.text
+        font_style = []
+        if self.bold:
+            font_style.append("bold")
+        if self.italic:
+            font_style.append("italic")
+        style_str = f", style={font_style}" if font_style else ""
+        
+        # Use font_family for display but include raw fontname and variant
+        font_display = self.font_family
+        variant = self.font_variant
+        variant_str = f", variant='{variant}'" if variant else ""
+        
+        if font_display != self.fontname and '+' in self.fontname:
+            base_font = self.fontname.split('+', 1)[1]
+            font_display = f"{font_display} ({base_font})"
+            
+        return f"<TextElement text='{preview}' font='{font_display}'{variant_str} size={self.size}{style_str} bbox={self.bbox}>"
+        
+    def font_info(self) -> dict:
+        """
+        Get detailed font information for this text element.
+        
+        Returns a dictionary with all available font-related properties,
+        useful for debugging font detection issues.
+        """
+        info = {
+            'text': self.text,
+            'fontname': self.fontname,
+            'font_family': self.font_family,
+            'font_variant': self.font_variant,
+            'size': self.size,
+            'bold': self.bold,
+            'italic': self.italic,
+            'color': self.color
+        }
+        
+        # Include raw font properties from the PDF
+        font_props = [
+            'flags', 'stemv', 'StemV', 'weight', 'FontWeight',
+            'render_mode', 'stroke_width', 'lineWidth'
+        ]
+        
+        for prop in font_props:
+            if prop in self._obj:
+                info[f"raw_{prop}"] = self._obj[prop]
+                
+        return info

natural_pdf/ocr/__init__.py

@@ -0,0 +1,62 @@
+"""
+OCR engines for natural-pdf.
+
+This module provides different OCR engines that can be used with natural-pdf.
+"""
+import logging
+
+# Set up module logger
+logger = logging.getLogger("natural_pdf.ocr")
+from .engine import OCREngine
+from .easyocr_engine import EasyOCREngine
+
+# Try to import PaddleOCR engine, but don't fail if it's not available
+try:
+    from .paddleocr_engine import PaddleOCREngine
+    __all__ = ['OCREngine', 'EasyOCREngine', 'PaddleOCREngine']
+except ImportError:
+    __all__ = ['OCREngine', 'EasyOCREngine']
+
+# Default engine to use if none is specified
+try:
+    from .paddleocr_engine import PaddleOCREngine
+    DEFAULT_ENGINE = PaddleOCREngine  # Use PaddleOCR as default if available
+except ImportError:
+    DEFAULT_ENGINE = EasyOCREngine  # Fall back to EasyOCR if PaddleOCR is not available
+
+def get_engine(engine_name=None, **kwargs):
+    """
+    Get OCR engine by name.
+    
+    Args:
+        engine_name: Name of the engine to use ('easyocr', 'paddleocr', etc.)
+                     If None, the default engine is used (PaddleOCR if available, otherwise EasyOCR)
+        **kwargs: Additional arguments to pass to the engine constructor
+        
+    Returns:
+        OCREngine instance
+    """
+    logger.debug(f"Initializing OCR engine: {engine_name or 'default'}")
+    
+    if engine_name is None or engine_name == 'default':
+        engine = DEFAULT_ENGINE(**kwargs)
+        logger.info(f"Using default OCR engine: {engine.__class__.__name__}")
+        return engine
+    
+    if engine_name.lower() == 'easyocr':
+        logger.info("Initializing EasyOCR engine")
+        return EasyOCREngine(**kwargs)
+    
+    if engine_name.lower() == 'paddleocr':
+        try:
+            from .paddleocr_engine import PaddleOCREngine
+            logger.info("Initializing PaddleOCR engine")
+            return PaddleOCREngine(**kwargs)
+        except ImportError:
+            logger.error("PaddleOCR is not installed")
+            raise ImportError(
+                "PaddleOCR is not installed. Please install it with: pip install paddlepaddle paddleocr"
+            )
+    
+    logger.error(f"Unknown OCR engine: {engine_name}")
+    raise ValueError(f"Unknown OCR engine: {engine_name}")

natural_pdf/ocr/easyocr_engine.py

@@ -0,0 +1,254 @@
+"""
+EasyOCR engine implementation.
+"""
+import importlib.util
+from typing import Dict, List, Any, Optional
+import numpy as np
+from PIL import Image
+
+from .engine import OCREngine
+
+
+class EasyOCREngine(OCREngine):
+    """EasyOCR implementation."""
+    
+    def __init__(self, **kwargs):
+        """
+        Initialize EasyOCR engine with optional settings.
+        
+        Args:
+            **kwargs: Engine-specific settings
+        """
+        super().__init__(**kwargs)
+        self._readers = {}  # Cache for readers
+        
+        # Store initialization settings to use in model initialization
+        self._init_settings = kwargs
+        
+    def is_available(self) -> bool:
+        """
+        Check if EasyOCR is installed.
+        
+        Returns:
+            True if EasyOCR is available, False otherwise
+        """
+        try:
+            import easyocr
+            return True
+        except ImportError:
+            return False
+    
+    def get_reader(self, config: Dict[str, Any]):
+        """
+        Get or initialize an EasyOCR reader based on configuration.
+        
+        Args:
+            config: OCR configuration
+            
+        Returns:
+            EasyOCR reader instance
+        """
+        print(f"EasyOCR.get_reader: Config = {config}")
+        
+        # Get languages from config
+        languages = config.get("languages", ["en"])
+        print(f"EasyOCR.get_reader: Languages = {languages}")
+        
+        # Create a cache key from languages
+        cache_key = f"easyocr_{'-'.join(languages)}"
+        print(f"EasyOCR.get_reader: Cache key = {cache_key}")
+        
+        # Return cached reader if available
+        if cache_key in self._readers:
+            print(f"EasyOCR.get_reader: Using cached reader")
+            return self._readers[cache_key]
+        
+        # Check if easyocr is installed
+        if not importlib.util.find_spec("easyocr"):
+            print(f"EasyOCR.get_reader: EasyOCR not installed")
+            raise ImportError(
+                "EasyOCR is not installed. Please install it with: pip install easyocr"
+            )
+        
+        # Import easyocr
+        print(f"EasyOCR.get_reader: Importing easyocr")
+        import easyocr
+        
+        # Start with initialization settings
+        reader_kwargs = self._init_settings.copy()
+        print(f"EasyOCR.get_reader: Init settings = {reader_kwargs}")
+        
+        # Add languages parameter
+        reader_kwargs["lang_list"] = languages
+        
+        # Handle device parameter mapping
+        if "device" in config:
+            device = config["device"]
+            if device.startswith("cuda"):
+                reader_kwargs["gpu"] = True
+            else:
+                reader_kwargs["gpu"] = False
+            print(f"EasyOCR.get_reader: Set gpu={reader_kwargs.get('gpu', False)} from device={device}")
+        
+        # Apply model_settings if provided
+        model_settings = config.get("model_settings", {})
+        reader_kwargs.update(model_settings)
+        print(f"EasyOCR.get_reader: Final kwargs = {reader_kwargs}")
+        
+        # Create reader with specified settings
+        print(f"EasyOCR.get_reader: Creating EasyOCR.Reader with lang_list={languages}")
+        try:
+            reader = easyocr.Reader(**reader_kwargs)
+            print(f"EasyOCR.get_reader: Successfully created reader")
+        except Exception as e:
+            print(f"EasyOCR.get_reader: Error creating reader: {e}")
+            import traceback
+            traceback.print_exc()
+            raise
+        
+        # Cache reader
+        self._readers[cache_key] = reader
+        print(f"EasyOCR.get_reader: Reader cached with key {cache_key}")
+        return reader
+    
+    def process_image(self, image: Image.Image, config: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+        """
+        Process an image with EasyOCR.
+        
+        Args:
+            image: PIL Image to process
+            config: OCR configuration
+            
+        Returns:
+            List of standardized OCR results
+        """
+        print(f"EasyOCR.process_image: Starting with image type {type(image)}, size {image.width}x{image.height if hasattr(image, 'height') else 'unknown'}")
+        
+        # Save image for debugging
+        try:
+            import os
+            debug_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), "output")
+            os.makedirs(debug_dir, exist_ok=True)
+            debug_path = os.path.join(debug_dir, "easyocr_debug_input.png")
+            if isinstance(image, Image.Image):
+                image.save(debug_path)
+                print(f"EasyOCR.process_image: Saved input image to {debug_path}")
+        except Exception as e:
+            print(f"EasyOCR.process_image: Could not save debug image: {e}")
+            
+        # Normalize config
+        if config is None:
+            config = {}
+        print(f"EasyOCR.process_image: Raw config = {config}")
+        config = self.normalize_config(config)
+        print(f"EasyOCR.process_image: Normalized config = {config}")
+        
+        # Skip if OCR is disabled
+        if not config.get("enabled"):
+            print(f"EasyOCR.process_image: OCR is disabled in config, returning empty list")
+            return []
+            
+        # Direct test with known working code for debug
+        print(f"EasyOCR.process_image: Running direct test with EasyOCR")
+        try:
+            import easyocr
+            raw_reader = easyocr.Reader(['en'])
+            import numpy as np
+            img_array = np.array(image)
+            direct_result = raw_reader.readtext(img_array)
+            print(f"EasyOCR.process_image: Direct test got {len(direct_result)} results")
+        except Exception as e:
+            print(f"EasyOCR.process_image: Direct test failed: {e}")
+        
+        # Get reader
+        reader = self.get_reader(config)
+        
+        # Convert PIL Image to numpy array if needed
+        if isinstance(image, Image.Image):
+            img_array = np.array(image)
+        else:
+            img_array = image
+        
+        # Extract model_settings for readtext parameters
+        model_settings = config.get("model_settings", {})
+        
+        # For backward compatibility, handle both flattened and nested parameters
+        readtext_kwargs = {}
+        
+        # Add all model_settings to kwargs
+        readtext_kwargs.update(model_settings)
+        
+        # For backward compatibility, also check nested structures
+        detection_params = config.get("detection_params", {})
+        recognition_params = config.get("recognition_params", {})
+        
+        # Add nested params if provided
+        if detection_params:
+            for key, value in detection_params.items():
+                if key not in readtext_kwargs:
+                    readtext_kwargs[key] = value
+                    
+        if recognition_params:
+            for key, value in recognition_params.items():
+                if key not in readtext_kwargs:
+                    readtext_kwargs[key] = value
+        
+        # Run OCR with all parameters
+        print(f"EasyOCR: Running OCR with parameters: {readtext_kwargs}")
+        try:
+            result = reader.readtext(img_array, **readtext_kwargs)
+            print(f"EasyOCR: Got {len(result)} results")
+        except Exception as e:
+            print(f"EasyOCR error: {e}")
+            import traceback
+            traceback.print_exc()
+            return []
+        
+        # Apply minimum confidence threshold
+        min_confidence = config.get("min_confidence", 0.5)
+        
+        # Convert to standardized format
+        standardized_results = []
+        
+        for detection in result:
+            # Check the format based on what was returned
+            if isinstance(detection, list) and len(detection) >= 3:
+                # This is the detailed format (detail=1)
+                bbox = detection[0]  # [[x1,y1],[x2,y2],[x3,y3],[x4,y4]]
+                text = detection[1]
+                confidence = detection[2]
+                
+                # Skip if confidence is below threshold
+                if confidence < min_confidence:
+                    continue
+                
+                # Convert polygon bbox to rectangle (x0, y0, x1, y1)
+                x_coords = [point[0] for point in bbox]
+                y_coords = [point[1] for point in bbox]
+                
+                x0 = min(x_coords)
+                y0 = min(y_coords)
+                x1 = max(x_coords)
+                y1 = max(y_coords)
+                
+                standardized_results.append({
+                    'bbox': (x0, y0, x1, y1),
+                    'text': text,
+                    'confidence': confidence,
+                    'source': 'ocr'
+                })
+            elif isinstance(detection, str):
+                # Simple format (detail=0), no bbox or confidence
+                standardized_results.append({
+                    'bbox': (0, 0, 1, 1),  # Dummy bbox
+                    'text': detection,
+                    'confidence': 1.0,  # Default confidence
+                    'source': 'ocr'
+                })
+        
+        return standardized_results
+        
+    def __del__(self):
+        """Cleanup resources when the engine is deleted."""
+        # Clear reader cache to free up memory
+        self._readers.clear()