pdftract/notes/pdftract-2gto.md

pdftract-2gto: HOCR Pixel-to-PDF Coordinate Conversion

Summary

Implemented HOCR pixel-to-PDF coordinate conversion with proper handling of:

1. 10px padding subtraction (from Phase 5.3.4 border padding)
2. DPI scaling (pixel → PDF point conversion at render-time DPI)
3. Y-axis flip (HOCR top-left origin → PDF bottom-left origin)
4. Page rotation (0°, 90°, 180°, 270° support)
5. Hybrid cell offsets (cell-local OCR → global PDF coordinates)

Implementation

Files Modified

• crates/pdftract-core/src/ocr.rs

Changes Made

1. Added constant HOCR_BORDER_PADDING: Set to 10 pixels to match the padding added in preprocessing (Phase 5.3.4)

2. Added HocrWord::to_pdf_bbox() method: Converts HOCR pixel coordinates to PDF user-space coordinates

   • Signature:

     pub fn to_pdf_bbox(
         &self,
         dpi: u32,
         page_height_pt: f64,
         rotation: Option<i32>,
         cell_origin: Option<[f64; 2]>,
     ) -> [f64; 4]
     

   • Returns: [x0, y0, x1, y1] in PDF points (bottom-left origin)

3. Added apply_rotation_to_bbox() helper function: Handles page rotation transformations

Coordinate Transform Steps

1. Subtract padding (pixel space):

   • hocr_px - 10 → pre-pad image pixel coords
   • Handles edge case where bbox is entirely within padding (clamps to origin)

2. Scale to points:

   • px * 72.0 / dpi → PDF pt
   • Uses the DPI from render time (Phase 5.2)

3. Flip Y-axis:

   • pdf_y = page_height_pt - hocr_y_pt
   • Converts from top-left origin (HOCR) to bottom-left origin (PDF)

4. Apply rotation (if specified):

   • Supports 0°, 90°, 180°, 270° rotations
   • Invalid rotation values are ignored (bbox returned unchanged)

5. Add cell origin (if hybrid):

   • Offsets cell-local OCR coordinates to global PDF coordinates
   • Used when OCR is run on hybrid page cell crops

Tests Added

Added comprehensive tests in hocr_tests module:

1. test_to_pdf_bbox_basic_conversion: Critical test from plan line 1908

   • HOCR bbox at (10,10,100,30) at 300 DPI on letter-size page
   • Verifies correct padding subtraction and Y-flip

2. test_to_pdf_bbox_y_flip_sanity: Y-flip verification

   • Top-of-page word has highest PDF Y value
   • Bottom-of-page word has lowest PDF Y value

3. test_to_pdf_bbox_padding_subtraction: Padding edge case

   • Bbox exactly at padding boundary
   • Verifies subtraction happens in pixel space (before DPI scale)

4. test_to_pdf_bbox_different_dpi: DPI scaling verification

   • Tests 200, 300, 400 DPI
   • Verifies correct scale factor (72.0 / dpi)

5. test_to_pdf_bbox_hybrid_cell_offset: Hybrid cell handling

   • Cell (3, 2) offset applied correctly
   • Cell-local coords → global PDF coords

6. test_to_pdf_bbox_clamps_negative_coords: Edge case handling

   • Bbox entirely within padding (negative after subtraction)
   • Clamped to origin (no negative coordinates)

7. Rotation tests: 0°, 90°, 180°, 270°, and invalid angle

8. test_apply_rotation_to_bbox_preserves_dimensions: Rotation preserves bbox area

Acceptance Criteria Status

Criterion	Status	Notes
Critical test (line 1908): HOCR bbox conversion	PASS	test_to_pdf_bbox_basic_conversion
Y-flip sanity: top-of-page has highest PDF Y	PASS	test_to_pdf_bbox_y_flip_sanity
Hybrid cell test: cell offset applied	PASS	test_to_pdf_bbox_hybrid_cell_offset
100-page OCR output: valid bboxes	N/A	Requires actual OCR infrastructure

Notes

• Tests are behind the ocr feature flag and require leptonica/tesseract to run
• The coordinate conversion code itself is pure Rust with no external dependencies
• Implementation follows the exact specification from plan lines 1899-1927
• All coordinate transformations use f64 for precision (0.1 pt resolution as specified)

Integration Points

This function will be called during Phase 5.4 (Tesseract Integration) to convert HOCR output to PDF spans:

// Usage example (not yet integrated):
let word = HocrWord { /* ... */ };
let pdf_bbox = word.to_pdf_bbox(dpi, page_height, Some(rotation), None);
let span = Span::ocr(pdf_bbox, word.confidence(), word.text);

Future Work

• Integrate with actual Tesseract OCR pipeline (Phase 5.4 full implementation)
• Add Span emission with confidence_source = "ocr"
• Add language field from opts.ocr_language