natural-pdf 0.1.0__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,56 @@
+"""
+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 .ocr_manager import OCRManager
+from .engine import OCREngine
+from .ocr_options import OCROptions
+from .engine import OCREngine
+from .engine_paddle import PaddleOCREngine
+from .engine_surya import SuryaOCREngine
+
+__all__ = ['OCRManager', 'OCREngine', 'OCROptions', 'EasyOCREngine', 'PaddleOCREngine', 'SuryaOCREngine']
+
+DEFAULT_ENGINE = SuryaOCREngine
+
+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 .engine_paddle 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/engine.py

@@ -0,0 +1,104 @@
+# ocr_engine_base.py
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict, List, Any, Optional, Tuple, Union
+from PIL import Image
+
+# Assuming ocr_options defines BaseOCROptions
+from .ocr_options import BaseOCROptions
+
+logger = logging.getLogger(__name__)
+
+class OCREngine(ABC):
+    """Abstract Base Class for OCR engines."""
+
+    def __init__(self):
+        """Initializes the base OCR engine."""
+        self.logger = logging.getLogger(f"{__name__}.{self.__class__.__name__}")
+        self.logger.info(f"Initializing {self.__class__.__name__}")
+        self._reader_cache = {} # Cache for initialized models/readers
+
+    @abstractmethod
+    def process_image(
+        self,
+        images: Union[Image.Image, List[Image.Image]], # Accept single or list
+        options: BaseOCROptions
+    ) -> Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]]: # Return single or list of lists
+        """
+        Processes a single image or a batch of images using the specific engine and options.
+
+        Args:
+            images: A single PIL Image or a list of PIL Images.
+            options: An instance of a dataclass inheriting from BaseOCROptions
+                     containing configuration for this run.
+
+        Returns:
+            If input is a single image: List of result dictionaries.
+            If input is a list of images: List of lists of result dictionaries,
+                                          corresponding to each input image.
+                                          An empty list indicates failure for that image.
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        Check if the engine's dependencies are installed and usable.
+
+        Returns:
+            True if the engine is available, False otherwise.
+        """
+        raise NotImplementedError("Subclasses must implement this method")
+
+    def _get_cache_key(self, options: BaseOCROptions) -> str:
+        """
+        Generates a cache key based on relevant options.
+        Subclasses should override if more specific key generation is needed.
+
+        Args:
+            options: The options dataclass instance.
+
+        Returns:
+            A string cache key.
+        """
+        # Basic key includes languages and device
+        lang_key = "-".join(sorted(options.languages))
+        device_key = str(options.device).lower()
+        return f"{self.__class__.__name__}_{lang_key}_{device_key}"
+
+    def _standardize_bbox(self, bbox: Any) -> Optional[Tuple[float, float, float, float]]:
+        """
+        Helper to standardize bounding boxes to (x0, y0, x1, y1) format.
+
+        Args:
+            bbox: The bounding box in the engine's native format.
+                  Expected formats:
+                  - List/Tuple of 4 numbers: (x0, y0, x1, y1)
+                  - List of points: [[x1,y1],[x2,y2],[x3,y3],[x4,y4]] (polygon)
+
+        Returns:
+            Tuple[float, float, float, float] or None if conversion fails.
+        """
+        try:
+            if isinstance(bbox, (list, tuple)) and len(bbox) == 4 and all(isinstance(n, (int, float)) for n in bbox):
+                # Already in (x0, y0, x1, y1) format (or similar)
+                return tuple(float(c) for c in bbox[:4])
+            elif isinstance(bbox, (list, tuple)) and len(bbox) > 0 and isinstance(bbox[0], (list, tuple)):
+                # Polygon format [[x1,y1],[x2,y2],...]
+                x_coords = [float(point[0]) for point in bbox]
+                y_coords = [float(point[1]) for point in bbox]
+                x0 = min(x_coords)
+                y0 = min(y_coords)
+                x1 = max(x_coords)
+                y1 = max(y_coords)
+                return (x0, y0, x1, y1)
+        except Exception as e:
+            self.logger.warning(f"Could not standardize bounding box: {bbox}. Error: {e}")
+        return None
+
+    def __del__(self):
+        """Cleanup resources when the engine is deleted."""
+        self.logger.info(f"Cleaning up {self.__class__.__name__} resources.")
+        # Clear reader cache to free up memory/GPU resources
+        self._reader_cache.clear()
+

natural_pdf/ocr/engine_easyocr.py

@@ -0,0 +1,179 @@
+# ocr_engine_easyocr.py
+import logging
+import importlib.util
+from typing import Dict, List, Any, Optional, Tuple, Union
+import numpy as np
+from PIL import Image
+import inspect # Used for dynamic parameter passing
+
+from .engine import OCREngine
+from .ocr_options import EasyOCROptions, BaseOCROptions
+
+logger = logging.getLogger(__name__)
+
+class EasyOCREngine(OCREngine):
+    """EasyOCR engine implementation."""
+
+    def __init__(self):
+        super().__init__()
+        self._easyocr = None # Lazy load easyocr module
+
+    def _lazy_import_easyocr(self):
+        """Imports easyocr only when needed."""
+        if self._easyocr is None:
+            if not self.is_available():
+                raise ImportError("EasyOCR is not installed or available.")
+            try:
+                import easyocr
+                self._easyocr = easyocr
+                logger.info("EasyOCR module imported successfully.")
+            except ImportError as e:
+                logger.error(f"Failed to import EasyOCR: {e}")
+                raise
+        return self._easyocr
+
+    def is_available(self) -> bool:
+        """Check if EasyOCR is installed."""
+        return importlib.util.find_spec("easyocr") is not None
+
+    def _get_cache_key(self, options: EasyOCROptions) -> str:
+        """Generate a more specific cache key for EasyOCR."""
+        base_key = super()._get_cache_key(options)
+        recog_key = options.recog_network
+        detect_key = options.detect_network
+        quantize_key = str(options.quantize)
+        return f"{base_key}_{recog_key}_{detect_key}_{quantize_key}"
+
+    def _get_reader(self, options: EasyOCROptions):
+        """Get or initialize an EasyOCR reader based on options."""
+        cache_key = self._get_cache_key(options)
+        if cache_key in self._reader_cache:
+            logger.debug(f"Using cached EasyOCR reader for key: {cache_key}")
+            return self._reader_cache[cache_key]
+
+        logger.info(f"Creating new EasyOCR reader for key: {cache_key}")
+        easyocr = self._lazy_import_easyocr()
+
+        constructor_sig = inspect.signature(easyocr.Reader.__init__)
+        constructor_args = {}
+        constructor_args['lang_list'] = options.languages
+        constructor_args['gpu'] = 'cuda' in str(options.device).lower() or 'mps' in str(options.device).lower()
+
+        for field_name, param in constructor_sig.parameters.items():
+            if field_name in ['self', 'lang_list', 'gpu']: continue
+            if hasattr(options, field_name):
+                 constructor_args[field_name] = getattr(options, field_name)
+            elif field_name in options.extra_args:
+                 constructor_args[field_name] = options.extra_args[field_name]
+
+        logger.debug(f"EasyOCR Reader constructor args: {constructor_args}")
+        try:
+            reader = easyocr.Reader(**constructor_args)
+            self._reader_cache[cache_key] = reader
+            logger.info("EasyOCR reader created successfully.")
+            return reader
+        except Exception as e:
+            logger.error(f"Failed to create EasyOCR reader: {e}", exc_info=True)
+            raise
+
+    def _prepare_readtext_args(self, options: EasyOCROptions, reader) -> Dict[str, Any]:
+        """Helper to prepare arguments for the readtext method."""
+        readtext_sig = inspect.signature(reader.readtext)
+        readtext_args = {}
+        for field_name, param in readtext_sig.parameters.items():
+             if field_name == 'image': continue
+             if hasattr(options, field_name):
+                 readtext_args[field_name] = getattr(options, field_name)
+             elif field_name in options.extra_args:
+                 readtext_args[field_name] = options.extra_args[field_name]
+        logger.debug(f"EasyOCR readtext args: {readtext_args}")
+        return readtext_args
+
+    def _standardize_results(self, raw_results: List[Any], options: EasyOCROptions) -> List[Dict[str, Any]]:
+        """Standardizes raw results from EasyOCR's readtext."""
+        standardized_results = []
+        min_confidence = options.min_confidence
+
+        for detection in raw_results:
+            try:
+                if options.detail == 1 and isinstance(detection, (list, tuple)) and len(detection) >= 3:
+                    bbox_raw = detection[0]
+                    text = str(detection[1])
+                    confidence = float(detection[2])
+
+                    if confidence >= min_confidence:
+                        bbox = self._standardize_bbox(bbox_raw)
+                        if bbox:
+                            standardized_results.append({
+                                'bbox': bbox, 'text': text, 'confidence': confidence, 'source': 'ocr'
+                            })
+                        else:
+                             logger.warning(f"Skipping result due to invalid bbox: {bbox_raw}")
+
+                elif options.detail == 0 and isinstance(detection, str):
+                     standardized_results.append({
+                         'bbox': None, 'text': detection, 'confidence': 1.0, 'source': 'ocr'
+                     })
+            except (IndexError, ValueError, TypeError) as e:
+                 logger.warning(f"Skipping invalid detection format: {detection}. Error: {e}")
+                 continue
+        return standardized_results
+
+
+    def process_image(
+        self,
+        images: Union[Image.Image, List[Image.Image]],
+        options: BaseOCROptions
+    ) -> Union[List[Dict[str, Any]], List[List[Dict[str, Any]]]]:
+        """Processes a single image or a batch of images with EasyOCR."""
+
+        if not isinstance(options, EasyOCROptions):
+             logger.warning("Received BaseOCROptions, expected EasyOCROptions. Using defaults.")
+             # Create default EasyOCR options if base was passed, preserving base settings
+             options = EasyOCROptions(
+                 languages=options.languages,
+                 min_confidence=options.min_confidence,
+                 device=options.device,
+                 extra_args=options.extra_args # Pass along any extra args
+             )
+
+        reader = self._get_reader(options)
+        readtext_args = self._prepare_readtext_args(options, reader)
+
+        # --- Handle single image or batch ---
+        if isinstance(images, list):
+            # --- Batch Processing (Iterative for EasyOCR) ---
+            all_results = []
+            logger.info(f"Processing batch of {len(images)} images with EasyOCR (iteratively)...")
+            for i, img in enumerate(images):
+                if not isinstance(img, Image.Image):
+                     logger.warning(f"Item at index {i} in batch is not a PIL Image. Skipping.")
+                     all_results.append([])
+                     continue
+                img_array = np.array(img)
+                try:
+                    logger.debug(f"Processing image {i+1}/{len(images)} in batch.")
+                    raw_results = reader.readtext(img_array, **readtext_args)
+                    standardized = self._standardize_results(raw_results, options)
+                    all_results.append(standardized)
+                except Exception as e:
+                    logger.error(f"Error processing image {i+1} in EasyOCR batch: {e}", exc_info=True)
+                    all_results.append([]) # Append empty list for failed image
+            logger.info(f"Finished processing batch with EasyOCR.")
+            return all_results # Return List[List[Dict]]
+
+        elif isinstance(images, Image.Image):
+            # --- Single Image Processing ---
+            logger.info("Processing single image with EasyOCR...")
+            img_array = np.array(images)
+            try:
+                raw_results = reader.readtext(img_array, **readtext_args)
+                standardized = self._standardize_results(raw_results, options)
+                logger.info(f"Finished processing single image. Found {len(standardized)} results.")
+                return standardized # Return List[Dict]
+            except Exception as e:
+                logger.error(f"Error processing single image with EasyOCR: {e}", exc_info=True)
+                return [] # Return empty list on failure
+        else:
+            raise TypeError("Input 'images' must be a PIL Image or a list of PIL Images.")
+