Skip to content
TheChatArchiveThe Chat Archive
ClaudeClaude Haiku 4.5· anthropicHugging Face Frontier Reasoning Traces

Implement OCR with Tesseract using OpenCV preprocessing. Apply adaptive thresholding and…

  1. User

    Implement OCR with Tesseract using OpenCV preprocessing. Apply adaptive thresholding and deskewing to correct rotation before passing to Tesseract. Output results as HOCR preserving layout positions.

  2. Claude Assistant

    This is a comprehensive request for implementing OCR using Tesseract with advanced preprocessing. Let me create a complete solution that includes:

    1. Image loading and preprocessing
    2. Adaptive thresholding
    3. Deskewing (rotation correction)
    4. Tesseract OCR integration
    5. HOCR output to preserve layout positions

    I'll create multiple files to make this well-organized:

    • Main OCR processor
    • Preprocessing utilities
    • HOCR utilities
    • Example usage

    Let me write comprehensive code with proper error handling and documentation.

    Complete OCR Pipeline with Tesseract and Advanced Preprocessing

    I'll create a comprehensive OCR system with image preprocessing, deskewing, and HOCR output.

    1. Core OCR Processor

    # ocr_processor.py
    import cv2
    import numpy as np
    import pytesseract
    from PIL import Image
    import logging
    from pathlib import Path
    from dataclasses import dataclass
    from typing import Optional, Tuple, List
    import re
    from xml.etree import ElementTree as ET
    from datetime import datetime
    
    logging.basicConfig(level=logging.INFO)
    logger = logging.getLogger(__name__)
    
    
    @dataclass
    class OCRConfig:
        """Configuration for OCR processing"""
        lang: str = 'eng'
        psm: int = 1  # Page segmentation mode
        oem: int = 3  # OCR engine mode
        apply_adaptive_threshold: bool = True
        apply_deskew: bool = True
        apply_denoise: bool = True
        apply_dilation: bool = True
        adaptive_threshold_block_size: int = 11
        adaptive_threshold_c: int = 2
        kernel_size: int = 3
        dilation_iterations: int = 1
    
    
    class ImagePreprocessor:
        """Advanced image preprocessing for OCR"""
        
        def __init__(self, config: OCRConfig):
            self.config = config
        
        def preprocess(self, image_path: str) -> np.ndarray:
            """
            Apply complete preprocessing pipeline
            
            Args:
                image_path: Path to input image
                
            Returns:
                Preprocessed image
            """
            # Load image
            image = cv2.imread(image_path)
            if image is None:
                raise ValueError(f"Could not load image from {image_path}")
            
            logger.info(f"Original image shape: {image.shape}")
            
            # Convert to grayscale
            gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
            logger.info("Converted to grayscale")
            
            # Denoise if enabled
            if self.config.apply_denoise:
                gray = self._denoise(gray)
                logger.info("Applied denoising")
            
            # Deskew if enabled
            if self.config.apply_deskew:
                gray = self._deskew(gray)
                logger.info("Applied deskewing")
            
            # Apply adaptive thresholding
            if self.config.apply_adaptive_threshold:
                gray = self._adaptive_threshold(gray)
                logger.info("Applied adaptive thresholding")
            
            # Apply dilation if enabled
            if self.config.apply_dilation:
                gray = self._dilate(gray)
                logger.info("Applied dilation")
            
            return gray
        
        def _denoise(self, image: np.ndarray) -> np.ndarray:
            """
            Denoise using bilateral filter
            
            Args:
                image: Input image
                
            Returns:
                Denoised image
            """
            return cv2.bilateralFilter(image, 9, 75, 75)
        
        def _deskew(self, image: np.ndarray) -> np.ndarray:
            """
            Detect and correct skew/rotation
            
            Args:
                image: Input image
                
            Returns:
                Deskewed image
            """
            # Get contours for text lines
            _, binary = cv2.threshold(image, 127, 255, cv2.THRESH_BINARY)
            contours, _ = cv2.findContours(
                binary, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
            )
            
            if not contours:
                logger.warning("No contours found for deskewing")
                return image
            
            # Get the rotated bounding rectangle
            all_points = np.vstack(contours)
            rect = cv2.minAreaRect(all_points)
            
            # Extract rotation angle
            angle = rect[2]
            
            # Normalize angle
            if angle > 45:
                angle = angle - 90
            elif angle < -45:
                angle = angle + 90
            
            logger.info(f"Detected rotation angle: {angle:.2f} degrees")
            
            if abs(angle) < 0.5:
                return image
            
            # Get rotation matrix
            (h, w) = image.shape[:2]
            center = (w // 2, h // 2)
            rotation_matrix = cv2.getRotationMatrix2D(center, angle, 1.0)
            
            # Calculate new dimensions
            cos = np.abs(rotation_matrix[0, 0])
            sin = np.abs(rotation_matrix[0, 1])
            new_w = int((h * sin) + (w * cos))
            new_h = int((h * cos) + (w * sin))
            
            # Adjust rotation matrix for translation
            rotation_matrix[0, 2] += (new_w / 2) - center[0]
            rotation_matrix[1, 2] += (new_h / 2) - center[1]
            
            # Apply rotation
            deskewed = cv2.warpAffine(
                image,
                rotation_matrix,
                (new_w, new_h),
                borderMode=cv2.BORDER_REPLICATE
            )
            
            return deskewed
        
        def _adaptive_threshold(self, image: np.ndarray) -> np.ndarray:
            """
            Apply adaptive thresholding
            
            Args:
                image: Input grayscale image
                
            Returns:
                Binary image with adaptive thresholding
            """
            block_size = self.config.adaptive_threshold_block_size
            c = self.config.adaptive_threshold_c
            
            # Ensure block_size is odd
            if block_size % 2 == 0:
                block_size += 1
            
            return cv2.adaptiveThreshold(
                image,
                255,
                cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
                cv2.THRESH_BINARY,
                block_size,
                c
            )
        
        def _dilate(self, image: np.ndarray) -> np.ndarray:
            """
            Apply morphological dilation
            
            Args:
                image: Input binary image
                
            Returns:
                Dilated image
            """
            kernel = cv2.getStructuringElement(
                cv2.MORPH_ELLIPSE,
                (self.config.kernel_size, self.config.kernel_size)
            )
            return cv2.dilate(
                image,
                kernel,
                iterations=self.config.dilation_iterations
            )
    
    
    class TesseractOCR:
        """Tesseract OCR wrapper with HOCR support"""
        
        def __init__(self, config: OCRConfig):
            self.config = config
            self._verify_tesseract()
        
        def _verify_tesseract(self):
            """Verify Tesseract is installed"""
            try:
                pytesseract.pytesseract.get_languages()
                logger.info("Tesseract verification successful")
            except pytesseract.TesseractNotFoundError:
                logger.error(
                    "Tesseract not found. Please install it:"
                    "\n  macOS: brew install tesseract"
                    "\n  Ubuntu: sudo apt-get install tesseract-ocr"
                    "\n  Windows: Download from https://github.com/UB-Mannheim/tesseract"
                )
                raise
        
        def extract_text(self, image: np.ndarray) -> str:
            """
            Extract plain text using Tesseract
            
            Args:
                image: Preprocessed image
                
            Returns:
                Extracted text
            """
            config = self._get_tesseract_config()
            text = pytesseract.image_to_string(image, config=config)
            return text
        
        def extract_hocr(self, image: np.ndarray) -> str:
            """
            Extract HOCR preserving layout
            
            Args:
                image: Preprocessed image
                
            Returns:
                HOCR string
            """
            config = self._get_tesseract_config() + ' hocr'
            hocr = pytesseract.image_to_pdf_or_hocr(image, extension='hocr', config=config)
            return hocr.decode('utf-8')
        
        def extract_data(self, image: np.ndarray) -> dict:
            """
            Extract detailed data including confidence scores
            
            Args:
                image: Preprocessed image
                
            Returns:
                Dictionary with OCR data
            """
            config = self._get_tesseract_config()
            data = pytesseract.image_to_data(image, config=config, output_type=pytesseract.Output.DICT)
            return data
        
        def _get_tesseract_config(self) -> str:
            """Generate Tesseract configuration string"""
            return f'--psm {self.config.psm} --oem {self.config.oem}'
    
    
    class HOCRGenerator:
        """Generate standardized HOCR output"""
        
        @staticmethod
        def parse_hocr(hocr_string: str) -> dict:
            """
            Parse HOCR string into structured data
            
            Args:
                hocr_string: Raw HOCR output
                
            Returns:
                Parsed HOCR data
            """
            try:
                root = ET.fromstring(hocr_string)
            except ET.ParseError as e:
                logger.error(f"Failed to parse HOCR: {e}")
                return {}
            
            data = {
                'pages': [],
                'lines': [],
                'words': [],
                'metadata': {}
            }
            
            # Extract metadata
            meta_elements = root.findall('.//meta')
            for meta in meta_elements:
                name = meta.get('name')
                content = meta.get('content')
                if name and content:
                    data['metadata'][name] = content
            
            # Extract pages
            pages = root.findall('.//div[@class="ocr_page"]')
            for page in pages:
                page_data = HOCRGenerator._extract_bbox(page)
                data['pages'].append(page_data)
            
            # Extract lines
            lines = root.findall('.//span[@class="ocr_line"]')
            for line in lines:
                line_data = HOCRGenerator._extract_bbox(line)
                line_data['text'] = (line.text or '').strip()
                data['lines'].append(line_data)
            
            # Extract words
            words = root.findall('.//span[@class="ocrx_word"]')
            for word in words:
                word_data = HOCRGenerator._extract_bbox(word)
                word_data['text'] = (word.text or '').strip()
                
                # Extract confidence
                title = word.get('title', '')
                conf_match = re.search(r'x_conf (\d+)', title)
                if conf_match:
                    word_data['confidence'] = int(conf_match.group(1))
                
                data['words'].append(word_data)
            
            return data
        
        @staticmethod
        def _extract_bbox(element) -> dict:
            """Extract bounding box from HOCR element"""
            title = element.get('title', '')
            bbox_match = re.search(r'bbox (\d+) (\d+) (\d+) (\d+)', title)
            
            bbox = {}
            if bbox_match:
                x0, y0, x1, y1 = map(int, bbox_match.groups())
                bbox = {
                    'x0': x0,
                    'y0': y0,
                    'x1': x1,
                    'y1': y1,
                    'width': x1 - x0,
                    'height': y1 - y0
                }
            
            bbox['id'] = element.get('id', '')
            return bbox
        
        @staticmethod
        def create_hocr(
            image_path: str,
            ocr_data: dict,
            preprocessing_info: dict
        ) -> str:
            """
            Create custom HOCR with metadata
            
            Args:
                image_path: Path to processed image
                ocr_data: OCR data from Tesseract
                preprocessing_info: Preprocessing steps applied
                
            Returns:
                HOCR string
            """
            root = ET.Element('html')
            root.set('xmlns', 'http://www.w3.org/1999/xhtml')
            
            # Head
            head = ET.SubElement(root, 'head')
            title = ET.SubElement(head, 'title')
            title.text = f'OCR of {Path(image_path).name}'
            
            # Metadata
            meta_charset = ET.SubElement(head, 'meta')
            meta_charset.set('charset', 'utf-8')
            
            meta_ocr = ET.SubElement(head, 'meta')
            meta_ocr.set('name', 'ocr-system')
            meta_ocr.set('content', 'tesseract')
            
            meta_time = ET.SubElement(head, 'meta')
            meta_time.set('name', 'ocr-date')
            meta_time.set('content', datetime.now().isoformat())
            
            # Preprocessing info
            preproc_meta = ET.SubElement(head, 'meta')
            preproc_meta.set('name', 'preprocessing')
            preproc_meta.set('content', str(preprocessing_info))
            
            # Body
            body = ET.SubElement(root, 'body')
            
            # Add OCR data
            if ocr_data.get('text'):
                p = ET.SubElement(body, 'p')
                p.text = ocr_data['text']
            
            # Pretty print
            ET.indent(root, space="  ")
            return ET.tostring(root, encoding='unicode')
    
    
    class OCRPipeline:
        """Complete OCR processing pipeline"""
        
        def __init__(self, config: Optional[OCRConfig] = None):
            self.config = config or OCRConfig()
            self.preprocessor = ImagePreprocessor(self.config)
            self.ocr = TesseractOCR(self.config)
        
        def process(
            self,
            image_path: str,
            output_dir: Optional[str] = None
        ) -> dict:
            """
            Process image through complete OCR pipeline
            
            Args:
                image_path: Path to input image
                output_dir: Optional directory to save outputs
                
            Returns:
                Dictionary with all outputs
            """
            image_path = str(image_path)
            logger.info(f"Starting OCR pipeline for: {image_path}")
            
            # Create output directory
            if output_dir:
                Path(output_dir).mkdir(parents=True, exist_ok=True)
            
            # Preprocess
            preprocessed = self.preprocessor.preprocess(image_path)
            
            # Save preprocessed image
            if output_dir:
                cv2.imwrite(f"{output_dir}/preprocessed.png", preprocessed)
            
            # Extract text
            text = self.ocr.extract_text(preprocessed)
            logger.info(f"Extracted text: {len(text)} characters")
            
            # Extract HOCR
            hocr = self.ocr.extract_hocr(preprocessed)
            logger.info("Extracted HOCR")
            
            # Parse HOCR
            hocr_data = HOCRGenerator.parse_hocr(hocr)
            logger.info(f"Parsed HOCR: {len(hocr_data.get('words', []))} words")
            
            # Extract detailed data
            ocr_data = self.ocr.extract_data(preprocessed)
            
            result = {
                'image_path': image_path,
                'text': text,
                'hocr': hocr,
                'hocr_data': hocr_data,
                'ocr_data': ocr_data,
                'preprocessing': {
                    'adaptive_threshold': self.config.apply_adaptive_threshold,
                    'deskew': self.config.apply_deskew,
                    'denoise': self.config.apply_denoise,
                    'dilation': self.config.apply_dilation
                }
            }
            
            # Save outputs
            if output_dir:
                self._save_results(result, output_dir)
            
            return result
        
        def _save_results(self, result: dict, output_dir: str):
            """Save OCR results to files"""
            output_dir = Path(output_dir)
            
            # Save plain text
            with open(output_dir / 'output.txt', 'w', encoding='utf-8') as f:
                f.write(result['text'])
            logger.info(f"Saved text to {output_dir / 'output.txt'}")
            
            # Save HOCR
            with open(output_dir / 'output.hocr', 'w', encoding='utf-8') as f:
                f.write(result['hocr'])
            logger.info(f"Saved HOCR to {output_dir / 'output.hocr'}")
            
            # Save JSON summary
            import json
            summary = {
                'image': result['image_path'],
                'text_length': len(result['text']),
                'word_count': len(result['hocr_data'].get('words', [])),
                'line_count': len(result['hocr_data'].get('lines', [])),
                'preprocessing': result['preprocessing'],
                'metadata': result['hocr_data'].get('metadata', {})
            }
            with open(output_dir / 'summary.json', 'w', encoding='utf-8') as f:
                json.dump(summary, f, indent=2)
            logger.info(f"Saved summary to {output_dir / 'summary.json'}")
    

    2. Visualization and Analysis Tools

    # ocr_visualizer.py
    import cv2
    import numpy as np
    from pathlib import Path
    from typing import Dict, Tuple
    import matplotlib.pyplot as plt
    import matplotlib.patches as patches
    from PIL import Image, ImageDraw, ImageFont
    
    
    class OCRVisualizer:
        """Visualize OCR results with bounding boxes"""
        
        @staticmethod
        def visualize_hocr_boxes(
            image_path: str,
            hocr_data: dict,
            output_path: str,
            box_type: str = 'words',
            confidence_threshold: int = 0
        ) -> None:
            """
            Draw HOCR bounding boxes on image
            
            Args:
                image_path: Path to original image
                hocr_data: Parsed HOCR data
                output_path: Path to save visualization
                box_type: 'words', 'lines', or 'pages'
                confidence_threshold: Minimum confidence score
            """
            image = Image.open(image_path).convert('RGB')
            draw = ImageDraw.Draw(image)
            
            boxes = hocr_data.get(box_type, [])
            colors = {
                'words': (0, 255, 0),  # Green
                'lines': (0, 0, 255),  # Red
                'pages': (255, 0, 0)   # Blue
            }
            color = colors.get(box_type, (0, 255, 0))
            
            for item in boxes:
                # Filter by confidence
                if 'confidence' in item and item['confidence'] < confidence_threshold:
                    continue
                
                bbox = item
                if bbox.get('width', 0) > 0 and bbox.get('height', 0) > 0:
                    # Draw rectangle
                    coords = [
                        bbox['x0'], bbox['y0'],
                        bbox['x1'], bbox['y1']
                    ]
                    draw.rectangle(coords, outline=color, width=2)
                    
                    # Add text label
                    if 'text' in item:
                        text = item['text']
                        conf = item.get('confidence', '')
                        label = f"{text} ({conf}%)" if conf else text
                        draw.text(
                            (bbox['x0'], bbox['y0'] - 10),
                            label,
                            fill=color
                        )
            
            image.save(output_path)
            print(f"Saved visualization to {output_path}")
        
        @staticmethod
        def plot_preprocessing_steps(
            original_path: str,
            preprocessed_path: str,
            output_path: str
        ) -> None:
            """
            Create side-by-side comparison of preprocessing
            
            Args:
                original_path: Path to original image
                preprocessed_path: Path to preprocessed image
                output_path: Path to save comparison
            """
            fig, axes = plt.subplots(1, 2, figsize=(15, 8))
            
            # Original
            original = cv2.imread(original_path)
            original = cv2.cvtColor(original, cv2.COLOR_BGR2RGB)
            axes[0].imshow(original)
            axes[0].set_title('Original Image')
            axes[0].axis('off')
            
            # Preprocessed
            preprocessed = cv2.imread(preprocessed_path, cv2.IMREAD_GRAYSCALE)
            axes[1].imshow(preprocessed, cmap='gray')
            axes[1].set_title('Preprocessed Image')
            axes[1].axis('off')
            
            plt.tight_layout()
            plt.savefig(output_path, dpi=150, bbox_inches='tight')
            plt.close()
            print(f"Saved comparison to {output_path}")
        
        @staticmethod
        def create_word_statistics_plot(
            hocr_data: dict,
            output_path: str
        ) -> None:
            """
            Plot word confidence statistics
            
            Args:
                hocr_data: Parsed HOCR data
                output_path: Path to save plot
            """
            words = hocr_data.get('words', [])
            confidences = [w.get('confidence', 0) for w in words]
            
            if not confidences:
                print("No confidence data available")
                return
            
            fig, axes = plt.subplots(2, 2, figsize=(12, 10))
            
            # Histogram
            axes[0, 0].hist(confidences, bins=20, edgecolor='black')
            axes[0, 0].set_title('Confidence Distribution')
            axes[0, 0].set_xlabel('Confidence (%)')
            axes[0, 0].set_ylabel('Frequency')
            
            # Box plot
            axes[0, 1].boxplot(confidences)
            axes[0, 1].set_title('Confidence Box Plot')
            axes[0, 1].set_ylabel('Confidence (%)')
            
            # Stats text
            stats_text = f"""
            Statistics:
            Mean: {np.mean(confidences):.2f}%
            Median: {np.median(confidences):.2f}%
            Std Dev: {np.std(confidences):.2f}%
            Min: {np.min(confidences)}%
            Max: {np.max(confidences)}%
            """
            axes[1, 0].text(0.1, 0.5, stats_text, fontsize=11, family='monospace')
            axes[1, 0].axis('off')
            
            # Low confidence words
            low_conf = [w for w in words if w.get('confidence', 100) < 80]
            axes[1, 1].text(
                0.1, 0.5,
                f"Low Confidence Words (< 80%):\n" +
                "\n".join([w['text'] for w in low_conf[:10]]),
                fontsize=10,
                family='monospace'
            )
            axes[1, 1].axis('off')
            
            plt.tight_layout()
            plt.savefig(output_path, dpi=150, bbox_inches='tight')
            plt.close()
            print(f"Saved statistics plot to {output_path}")
    
    
    class HOCRAnalyzer:
        """Analyze HOCR output"""
        
        @staticmethod
        def get_statistics(hocr_data: dict) -> dict:
            """
            Calculate statistics from HOCR data
            
            Args:
                hocr_data: Parsed HOCR data
                
            Returns:
                Statistics dictionary
            """
            words = hocr_data.get('words', [])
            lines = hocr_data.get('lines', [])
            
            if not words:
                return {}
            
            confidences = [w.get('confidence', 0) for w in words]
            
            return {
                'total_words': len(words),
                'total_lines': len(lines),
                'mean_confidence': float(np.mean(confidences)),
                'median_confidence': float(np.median(confidences)),
                'min_confidence': int(np.min(confidences)),
                'max_confidence': int(np.max(confidences)),
                'std_confidence': float(np.std(confidences)),
                'low_confidence_words': sum(1 for c in confidences if c < 80),
                'high_confidence_words': sum(1 for c in confidences if c >= 95)
            }
        
        @staticmethod
        def extract_text_with_positions(hocr_data: dict) -> str:
            """
            Extract text preserving approximate positions
            
            Args:
                hocr_data: Parsed HOCR data
                
            Returns:
                Text with position markers
            """
            lines = hocr_data.get('lines', [])
            text_output = []
            
            for line in lines:
                text_output.append(line.get('text', ''))
            
            return '\n'.join(text_output)
        
        @staticmethod
        def find_uncertain_regions(
            hocr_data: dict,
            confidence_threshold: int = 75
        ) -> list:
            """
            Find regions with low OCR confidence
            
            Args:
                hocr_data: Parsed HOCR data
                confidence_threshold: Confidence threshold
                
            Returns:
                List of low-confidence regions
            """
            words = hocr_data.get('words', [])
            uncertain = []
            
            for word in words:
                conf = word.get('confidence', 100)
                if conf < confidence_threshold:
                    uncertain.append({
                        'text': word.get('text', ''),
                        'confidence': conf,
                        'bbox': {
                            'x0': word.get('x0', 0),
                            'y0': word.get('y0', 0),
                            'x1': word.get('x1', 0),
                            'y1': word.get('y1', 0)
                        }
                    })
            
            return sorted(uncertain, key=lambda x: x['confidence'])
    

    3. Example Usage

    # main_example.py
    from ocr_processor import OCRConfig, OCRPipeline, HOCRGenerator
    from ocr_visualizer import OCRVisualizer, HOCRAnalyzer
    from pathlib import Path
    import json
    
    
    def example_basic_ocr():
        """Basic OCR example"""
        print("=" * 60)
        print("BASIC OCR EXAMPLE")
        print("=" * 60)
        
        # Configure
        config = OCRConfig(
            lang='eng',
            apply_adaptive_threshold=True,
            apply_deskew=True,
            apply_denoise=True
        )
        
        # Create pipeline
        pipeline = OCRPipeline(config)
        
        # Process image
        result = pipeline.process(
            image_path='sample_image.png',
            output_dir='output/basic_ocr'
        )
        
        # Print results
        print("\nExtracted Text:")
        print("-" * 40)
        print(result['text'][:500])
        print("\n...")
        
        return result
    
    
    def example_detailed_analysis():
        """Detailed OCR with analysis"""
        print("\n" + "=" * 60)
        print("DETAILED ANALYSIS EXAMPLE")
        print("=" * 60)
        
        # Configure
        config = OCRConfig(
            lang='eng',
            apply_adaptive_threshold=True,
            apply_deskew=True,
            apply_denoise=True,
            apply_dilation=True
        )
        
        # Process
        pipeline = OCRPipeline(config)
        result = pipeline.process(
            image_path='sample_image.png',
            output_dir='output/detailed_analysis'
        )
        
        # Analyze HOCR
        hocr_data = result['hocr_data']
        stats = HOCRAnalyzer.get_statistics(hocr_data)
        
        print("\nOCR Statistics:")
        print("-" * 40)
        for key, value in stats.items():
            if isinstance(value, float):
                print(f"{key:.<30} {value:.2f}")
            else:
                print(f"{key:.<30} {value}")
        
        # Find uncertain regions
        uncertain = HOCRAnalyzer.find_uncertain_regions(hocr_data, 80)
        print(f"\nLow Confidence Words (<80%):")
        print("-" * 40)
        for word in uncertain[:10]:
            print(f"  '{word['text']}' - {word['confidence']}%")
        
        return result, stats
    
    
    def example_visualization():
        """Visualization example"""
        print("\n" + "=" * 60)
        print("VISUALIZATION EXAMPLE")
        print("=" * 60)
        
        # Process
        config = OCRConfig(lang='eng', apply_adaptive_threshold=True, apply_deskew=True)
        pipeline = OCRPipeline(config)
        result = pipeline.process(
            image_path='sample_image.png',
            output_dir='output/visualization'
        )
        
        # Visualize word boxes
        OCRVisualizer.visualize_hocr_boxes(
            image_path='sample_image.png',
            hocr_data=result['hocr_data'],
            output_path='output/visualization/hocr_words.png',
            box_type='words',
            confidence_threshold=0
        )
        
        # Visualize line boxes
        OCRVisualizer.visualize_hocr_boxes(
            image_path='sample_image.png',
            hocr_data=result['hocr_data'],
            output_path='output/visualization/hocr_lines.png',
            box_type='lines'
        )
        
        # Plot statistics
        OCRVisualizer.plot_preprocessing_steps(
            original_path='sample_image.png',
            preprocessed_path='output/visualization/preprocessed.png',
            output_path='output/visualization/preprocessing_comparison.png'
        )
        
        OCRVisualizer.create_word_statistics_plot(
            hocr_data=result['hocr_data'],
            output_path='output/visualization/confidence_statistics.png'
        )
        
        print("\nVisualizations saved to output/visualization/")
    
    
    def example_batch_processing():
        """Batch processing example"""
        print("\n" + "=" * 60)
        print("BATCH PROCESSING EXAMPLE")
        print("=" * 60)
        
        # Configure
        config = OCRConfig(lang='eng', apply_adaptive_threshold=True, apply_deskew=True)
        pipeline = OCRPipeline(config)
        
        # Process multiple images
        image_dir = Path('sample_images')
        if not image_dir.exists():
            print("Create 'sample_images' directory with image files")
            return
        
        results = []
        summary = {
            'total_images': 0,
            'total_words': 0,
            'average_confidence': 0,
            'images': []
        }
        
        for image_path in image_dir.glob('*.png'):
            print(f"\nProcessing: {image_path.name}")
            
            result = pipeline.process(
                image_path=str(image_path),
                output_dir=f'output/batch/{image_path.stem}'
            )
            
            stats = HOCRAnalyzer.get_statistics(result['hocr_data'])
            
            image_summary = {
                'filename': image_path.name,
                'text_length': len(result['text']),
                'statistics': stats
            }
            summary['images'].append(image_summary)
            summary['total_images'] += 1
            summary['total_words'] += stats.get('total_words', 0)
            
            results.append(result)
        
        # Calculate averages
        if summary['total_images'] > 0:
            avg_conf = np.mean([
                img['statistics'].get('mean_confidence', 0)
                for img in summary['images']
            ])
            summary['average_confidence'] = float(avg_conf)
        
        # Save batch summary
        output_dir = Path('output/batch')
        with open(output_dir / 'summary.json', 'w') as f:
            json.dump(summary, f, indent=2)
        
        print("\nBatch Summary:")
        print("-" * 40)
        print(f"Total Images: {summary['total_images']}")
        print(f"Total Words: {summary['total_words']}")
        print(f"Average Confidence: {summary['average_confidence']:.2f}%")
        
        return results, summary
    
    
    def example_custom_preprocessing():
        """Custom preprocessing parameters"""
        print("\n" + "=" * 60)
        print("CUSTOM PREPROCESSING EXAMPLE")
        print("=" * 60)
        
        configs = [
            ('minimal', OCRConfig(apply_denoise=False, apply_dilation=False)),
            ('standard', OCRConfig()),
            ('aggressive', OCRConfig(
                adaptive_threshold_block_size=21,
                adaptive_threshold_c=5,
                dilation_iterations=2
            ))
        ]
        
        results = {}
        
        for name, config in configs:
            print(f"\nTesting {name} preprocessing...")
            
            pipeline = OCRPipeline(config)
            result = pipeline.process(
                image_path='sample_image.png',
                output_dir=f'output/preprocessing/{name}'
            )
            
            stats = HOCRAnalyzer.get_statistics(result['hocr_data'])
            results[name] = {
                'text': result['text'],
                'stats': stats,
                'config': {
                    'denoise': config.apply_denoise,
                    'deskew': config.apply_deskew,
                    'adaptive_threshold': config.apply_adaptive_threshold,
                    'dilation': config.apply_dilation
                }
            }
            
            print(f"  Words: {stats.get('total_words', 0)}")
            print(f"  Mean Confidence: {stats.get('mean_confidence', 0):.2f}%")
        
        # Compare results
        print("\n" + "=" * 60)
        print("PREPROCESSING COMPARISON")
        print("=" * 60)
        
        for name, result in results.items():
            print(f"\n{name.upper()}:")
            print(f"  Mean Confidence: {result['stats'].get('mean_confidence', 0):.2f}%")
            print(f"  Total Words: {result['stats'].get('total_words', 0)}")
        
        return results
    
    
    if __name__ == '__main__':
        # Run examples
        try:
            # Basic OCR
            result1 = example_basic_ocr()
            
            # Detailed analysis
            result2, stats = example_detailed_analysis()
            
            # Visualization
            example_visualization()
            
            # Custom preprocessing
            preprocessing_results = example_custom_preprocessing()
            
            # Uncomment for batch processing
            # batch_results, batch_summary = example_batch_processing()
            
            print("\n" + "=" * 60)
            print("ALL EXAMPLES COMPLETED")
            print("=" * 60)
            print("Check the 'output' directory for results")
            
        except Exception as e:
            print(f"Error: {e}")
            import traceback
            traceback.print_exc()
    

    4. Testing and Utilities

    # test_and_utils.py
    import unittest
    import tempfile
    from pathlib import Path
    import cv2
    import numpy as np
    from ocr_processor import OCRConfig, OCRPipeline, ImagePreprocessor, HOCRGenerator
    
    
    class TestOCRPipeline(unittest.TestCase):
        """Test OCR pipeline"""
        
        @classmethod
        def setUpClass(cls):
            """Create test image"""
            cls.test_dir = Path(tempfile.mkdtemp())
            cls.test_image = cls.test_dir / 'test.png'
            
            # Create test image with text
            from PIL import Image, ImageDraw, ImageFont
            img = Image.new('RGB', (400, 200), color='white')
            draw = ImageDraw.Draw(img)
            draw.text((50, 50), 'Test OCR Image', fill='black')
            img.save(cls.test_image)
        
        def test_config_creation(self):
            """Test configuration"""
            config = OCRConfig(lang='eng')
            self.assertEqual(config.lang, 'eng')
            self.assertTrue(config.apply_adaptive_threshold)
        
        def test_preprocessor(self):
            """Test image preprocessing"""
            config = OCRConfig()
            preprocessor = ImagePreprocessor(config)
            processed = preprocessor.preprocess(str(self.test_image))
            
            self.assertIsNotNone(processed)
            self.assertEqual(len(processed.shape), 2)  # Grayscale
        
        def test_pipeline(self):
            """Test full pipeline"""
            config = OCRConfig()
            pipeline = OCRPipeline(config)
            
            result = pipeline.process(str(self.test_image), str(self.test_dir))
            
            self.assertIn('text', result)
            self.assertIn('hocr', result)
            self.assertIn('hocr_data', result)
        
        def test_hocr_parsing(self):
            """Test HOCR parsing"""
            hocr_sample = '''
            <html>
                <span class="ocrx_word" title="bbox 10 20 100 30">test</span>
            </html>
            '''
            data = HOCRGenerator.parse_hocr(hocr_sample)
            self.assertIn('words', data)
    
    
    class ImageGenerator:
        """Generate test images"""
        
        @staticmethod
        def create_text_image(
            text: str,
            width: int = 800,
            height: int = 600,
            rotation: float = 0,
            noise: bool = False
        ) -> np.ndarray:
            """Create test image with text"""
            from PIL import Image, ImageDraw
            
            # Create white image
            img = Image.new('RGB', (width, height), color='white')
            draw = ImageDraw.Draw(img)
            
            # Draw text
            draw.multiline_text((50, 50), text, fill='black')
            
            # Convert to numpy
            img_array = np.array(img)
            img_bgr = cv2.cvtColor(img_array, cv2.COLOR_RGB2BGR)
            
            # Apply rotation
            if rotation != 0:
                h, w = img_bgr.shape[:2]
                center = (w // 2, h // 2)
                M = cv2.getRotationMatrix2D(center, rotation, 1.0)
                img_bgr = cv2.warpAffine(img_bgr, M, (w, h))
            
            # Add noise
            if noise:
                noise_array = np.random.normal(0, 25, img_bgr.shape)
                img_bgr = np.clip(img_bgr + noise_array, 0, 255).astype(np.uint8)
            
            return img_bgr
        
        @staticmethod
        def save_test_images(output_dir: str = 'test_images'):
            """Generate and save test images"""
            Path(output_dir).mkdir(exist_ok=True)
            
            # Regular text
            img = ImageGenerator.create_text_image(
                "Sample OCR Test Text\nThis is a test document",
                rotation=0
            )
            cv2.imwrite(f'{output_dir}/regular.png', img)
            
            # Rotated text
            img = ImageGenerator.create_text_image(
                "Rotated Test Text\nAngle: 15 degrees",
                rotation=15
            )
            cv2.imwrite(f'{output_dir}/rotated_15.png', img)
            
            # Noisy text
            img = ImageGenerator.create_text_image(
                "Noisy Test Text\nWith noise added",
                noise=True
            )
            cv2.imwrite(f'{output_dir}/noisy.png', img)
            
            print(f"Test images saved to {output_dir}/")
    
    
    if __name__ == '__main__':
        # Generate test images
        print("Generating test images...")
        ImageGenerator.save_test_images('test_images')
        
        # Run tests
        print("\nRunning tests...")
        unittest.main(argv=[''], verbosity=2, exit=False)
    

    5. Requirements

    # requirements.txt
    pytesseract>=0.3.10
    opencv-python>=4.5.0
    Pillow>=8.0.0
    numpy>=1.19.0
    matplotlib>=3.3.0
    pytest>=6.0.0
    

    Installation Guide

    # macOS
    brew install tesseract
    
    # Ubuntu/Debian
    sudo apt-get install tesseract-ocr
    
    # Windows
    # Download from: https://github.com/UB-Mannheim/tesseract/wiki
    
    # Python packages
    pip install -r requirements.txt
    

    Quick Start

    from ocr_processor import OCRConfig, OCRPipeline
    
    # Configure OCR
    config = OCRConfig(
        lang='eng',
        apply_adaptive_threshold=True,
        apply_deskew=True,
        apply_denoise=True
    )
    
    # Create pipeline
    pipeline = OCRPipeline(config)
    
    # Process image
    result = pipeline.process(
        image_path='document.png',
        output_dir='ocr_output'
    )
    
    # Access results
    print(result['text'])  # Plain text
    print(result['hocr'])  # HOCR with layout
    

    This implementation provides:

    ✅ Advanced Preprocessing: Adaptive thresholding, deskewing, denoising ✅ Tesseract Integration: Full OCR with confidence scores ✅ HOCR Output: Preserves text positions and layout ✅ Visualization Tools: Display results with bounding boxes ✅ Batch Processing: Process multiple images ✅ Statistical Analysis: Word confidence, quality metrics ✅ Testing Framework: Unit tests and utilities ✅ Production Ready: Error handling, logging, documentation

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.