ocrmypdf-paddleocr CLAUDE.md

OCRmyPDF-PaddleOCR Bounding Box Fixes

This document describes the bounding box improvements implemented in the PaddleOCR plugin for OCRmyPDF.

Overview

Three major improvements to text bounding boxes in the hOCR output:

1. Native Word Boxes: Use PaddleOCR 3.x's return_word_box=True for accurate word-level detection
2. Horizontal Fallback: Improved word width estimation when native boxes unavailable
3. Vertical Issue: Tighter line bounding boxes using polygon edge averaging

Fix 1: Native Word-Level Bounding Boxes

Implementation

PaddleOCR 3.x supports native word-level bounding boxes via the return_word_box=True parameter. The plugin now uses this feature:

result = paddle_ocr.predict(str(input_file), return_word_box=True)

# Extract word-level data
text_words = ocr_result.get('text_word', [])
text_word_regions = ocr_result.get('text_word_region', [])

Token Merging

PaddleOCR may split words unexpectedly (German umlauts, punctuation, emails). The plugin merges adjacent non-whitespace tokens:

# Merge tokens that were split unexpectedly
merged_words = []
current_word = []
current_boxes = []

for token, box in zip(line_word_tokens, line_word_boxes):
    token_str = str(token).strip()
    if not token_str or token_str.isspace():
        # Whitespace token - finalize current word
        if current_word:
            merged_words.append((''.join(current_word), current_boxes))
            current_word = []
            current_boxes = []
    else:
        # Non-whitespace token - accumulate
        current_word.append(token_str)
        current_boxes.append(box)

The bounding box for merged words is computed as the union of all sub-token boxes, using the polygon-edge method for vertical bounds.

Location: src/ocrmypdf_paddleocr/plugin.py:319-404

Results

• Pixel-accurate word boundaries from PaddleOCR's detection
• Proper handling of split tokens (umlauts, punctuation)
• Automatic fallback to estimation when word boxes unavailable