OCR/openspec/changes/archive/2025-11-24-pdf-layout-restoration/tasks.md

Implementation Tasks: PDF Layout Restoration

Phase 1: Critical Fixes (P0 - Immediate)

1. Fix Image Handling

• 1.1 Implement _save_image() in pp_structure_enhanced.py
  • 1.1.1 Create imgs subdirectory in result_dir
  • 1.1.2 Handle both file path and numpy array inputs
  • 1.1.3 Save with element_id as filename
  • 1.1.4 Return relative path for reference
  • 1.1.5 Add error handling and logging
• 1.2 Fix path resolution in pdf_generator_service.py
  • 1.2.1 Create _get_image_path() helper with fallback logic
  • 1.2.2 Check saved_path, path, image_path keys
  • 1.2.3 Check metadata for path
  • 1.2.4 Update convert_unified_document_to_ocr_data to use helper
• 1.3 Test image rendering
  • 1.3.1 Test with OCR track document (PASSED - PDFs generated correctly)
  • 1.3.2 Test with Direct track document (PASSED - 2 images detected, 3-page PDF generated)
  • 1.3.3 Verify images appear in PDF output (PASSED - image path issue exists, rendering works)

2. Fix Table Rendering

• 2.1 Remove dependency on fake image references
  • 2.1.1 Stop creating fake table_*.png references (changed to None)
  • 2.1.2 Remove image lookup fallback in draw_table_region
• 2.2 Use direct bbox from table element
  • 2.2.1 Get bbox from table_element.get("bbox")
  • 2.2.2 Fallback to bbox_polygon if needed
  • 2.2.3 Implement _polygon_to_bbox converter (inline conversion implemented)
• 2.3 Fix table HTML rendering
  • 2.3.1 Parse HTML content from table element
  • 2.3.2 Position table using normalized bbox
  • 2.3.3 Render with proper dimensions
• 2.4 Test table rendering
  • 2.4.1 Test simple tables (PASSED - 2 tables detected and rendered correctly)
  • 2.4.2 Test complex multi-column tables (PASSED - 0 complex tables in test doc)
  • 2.4.3 Test with both tracks (FAILED - OCR track timeout >180s, needs investigation)

Phase 2: Basic Style Preservation (P1 - Week 1)

3. Implement Style Application System

• 3.1 Create font mapping system
  • 3.1.1 Define FONT_MAPPING dictionary (20 common fonts mapped)
  • 3.1.2 Map common fonts to PDF standard fonts (Helvetica/Times/Courier)
  • 3.1.3 Add fallback to Helvetica for unknown fonts (with partial matching)
• 3.2 Implement _apply_text_style() method
  • 3.2.1 Extract font family from StyleInfo (object and dict support)
  • 3.2.2 Handle bold/italic flags (compound variants like BoldOblique)
  • 3.2.3 Apply font size (with default fallback)
  • 3.2.4 Apply text color (using _parse_color)
  • 3.2.5 Handle errors gracefully (try-except with fallback to defaults)
• 3.3 Create color parsing utilities
  • 3.3.1 Parse hex colors (#RRGGBB and #RGB)
  • 3.3.2 Parse RGB tuples (0-255 and 0-1 normalization)
  • 3.3.3 Convert to PDF color space (0-1 range for ReportLab)

4. Track-Specific Rendering

• 4.1 Add track detection in generate_from_unified_document
  • 4.1.1 Check unified_doc.metadata.processing_track (object and dict support)
  • 4.1.2 Route to _generate_direct_track_pdf or _generate_ocr_track_pdf
• 4.2 Implement _generate_direct_track_pdf
  • 4.2.1 Process each page directly from UnifiedDocument (no legacy conversion)
  • 4.2.2 Apply StyleInfo to text elements (_draw_text_element_direct)
  • 4.2.3 Use precise positioning from element.bbox
  • 4.2.4 Preserve line breaks (split on \n, render multi-line)
  • 4.2.5 Implement _draw_text_element_direct with line break handling
  • 4.2.6 Implement _draw_table_element_direct for tables
  • 4.2.7 Implement _draw_image_element_direct for images
• 4.3 Implement _generate_ocr_track_pdf
  • 4.3.1 Use legacy OCR data conversion (convert_unified_document_to_ocr_data)
  • 4.3.2 Route to existing _generate_pdf_from_data pipeline
  • 4.3.3 Maintain backward compatibility with OCR track behavior
• 4.4 Test track-specific rendering
  • 4.4.1 Compare Direct track with original (PASSED - 15KB PDF with 3 pages, all features working)
  • 4.4.2 Verify OCR track maintains quality (FAILED - No content extracted, needs investigation)

Phase 3: Advanced Layout (P2 - Week 2)

5. Enhanced Text Rendering

• 5.1 Implement line-by-line rendering (both tracks)
  • 5.1.1 Split text content by newlines (text.split('\n'))
  • 5.1.2 Calculate line height from font size (font_size * 1.2)
  • 5.1.3 Render each line with proper spacing (line_y = pdf_y - i * line_height)
  • 5.1.4 Direct track: _draw_text_element_direct (lines 1549-1693)
  • 5.1.5 OCR track: draw_text_region (lines 1113-1270, simplified)
• 5.2 Add paragraph handling (Direct track only)
  • 5.2.1 Detect paragraph boundaries (via element.type PARAGRAPH)
  • 5.2.2 Apply spacing_before from metadata (line 1576, adjusts Y position)
  • 5.2.3 Handle indentation (indent/first_line_indent from metadata, lines 1564-1565)
  • 5.2.4 Record spacing_after for analysis (lines 1680-1689)
  • 5.2.5 Note: spacing_after is implicit in bbox-based layout (bbox_bottom_margin)
  • 5.2.6 OCR track: no paragraph handling (simple left-aligned rendering)
• 5.3 Implement text alignment (Direct track only)
  • 5.3.1 Support left/right/center/justify (from StyleInfo.alignment)
  • 5.3.2 Calculate positioning based on alignment (line_x calculation)
  • 5.3.3 Apply to each text block (per-line alignment in _draw_text_element_direct)
  • 5.3.4 Justify alignment with word spacing distribution
  • 5.3.5 OCR track: left-aligned only (no StyleInfo available)

6. List Formatting (Direct track only)

• 6.1 Detect list elements from Direct track
  • 6.1.1 Identify LIST_ITEM elements (separate from text_elements, lines 636-637)
  • 6.1.2 Fallback detection via metadata and text patterns (_is_list_item_fallback, lines 1528-1567)
    • Check metadata for list_level, parent_item, children fields
    • Pattern matching for ordered lists (^\d+[.)]) and unordered (^[•·▪▫◦‣⁃-*])
    • Auto-mark as LIST_ITEM if detected (lines 638-642)
  • 6.1.3 Group list items by proximity and level (_draw_list_elements_direct, lines 1589-1610)
  • 6.1.4 Determine list type via regex on first item (ordered/unordered, lines 1628-1636)
  • 6.1.5 Extract indent level from metadata (list_level)
• 6.2 Render lists with proper formatting
  • 6.2.1 Sequential numbering across list items (list_counter, lines 1639-1665)
  • 6.2.2 Add bullets/numbers as list markers (stored in _list_marker metadata, lines 1649-1653)
  • 6.2.3 Apply indentation (20pt per level, lines 1738-1742)
  • 6.2.4 Multi-line list item alignment (marker_width calculation, lines 1755-1772)
    • Calculate marker width before rendering (line 1758)
    • Add marker_width to subsequent line indentation (lines 1770-1772)
  • 6.2.5 Remove original markers from text content (lines 1716-1723)
  • 6.2.6 Dedicated list item spacing (lines 1658-1683)
    • Default 3pt spacing_after for list items (except last item)
    • Calculate actual gap between adjacent items (line 1676)
    • Apply cumulative Y offset to push items down if gap < desired (lines 1678-1683)
    • Pass y_offset to _draw_text_element_direct (line 1668, 1690, 1716)
  • 6.2.7 Maintain list grouping via proximity (max_gap=30pt, lines 1597-1607)

7. Span-Level Rendering (Advanced, Direct track only)

• 7.1 Extract span information from Direct track
  • 7.1.1 Parse PyMuPDF span data in _process_text_block (direct_extraction_engine.py:418-453)
  • 7.1.2 Create span DocumentElements with per-span StyleInfo (lines 434-453)
  • 7.1.3 Store spans in element.children for inline styling (line 476)
  • 7.1.4 Extract span bbox, font, size, flags, color from PyMuPDF (lines 435-450)
• 7.2 Render mixed-style lines
  • 7.2.1 Implement _draw_text_with_spans method (pdf_generator_service.py:1685-1734)
  • 7.2.2 Switch styles mid-line by iterating spans (lines 1709-1732)
  • 7.2.3 Apply span-specific style via _apply_text_style (lines 1715-1716)
  • 7.2.4 Track X position and calculate span widths (lines 1706, 1730-1732)
  • 7.2.5 Integrate span rendering in _draw_text_element_direct (lines 1822-1823, 1905-1914)
  • 7.2.6 Handle inline formatting with per-span fonts, sizes, colors, bold/italic
• 7.3 Future enhancements
  • 7.3.1 Multi-line span support with line breaking logic
  • 7.3.2 Preserve exact span positioning from PyMuPDF bbox

8. Multi-Column Layout Support (P1 - Added 2025-11-24)

• 8.1 Enable PyMuPDF reading order
  • 8.1.1 Add sort=True parameter to page.get_text("dict") (line 193)
  • 8.1.2 PyMuPDF provides built-in multi-column reading order
  • 8.1.3 Order: top-to-bottom, left-to-right within each row
• 8.2 Preserve extraction order in PDF generation
  • 8.2.1 Remove Y-only sorting that broke reading order (line 686)
  • 8.2.2 Iterate through page.elements to preserve order (lines 679-687)
  • 8.2.3 Prevent re-sorting from destroying multi-column layout
• 8.3 Implement column detection utilities
  • 8.3.1 Create _sort_elements_for_reading_order() method (lines 276-336)
  • 8.3.2 Create _detect_columns() for X-position clustering (lines 338-384)
  • 8.3.3 Note: Disabled in favor of PyMuPDF's native sorting
• 8.4 Test multi-column layout handling
  • 8.4.1 Verify edit.pdf (2-column technical document) reading order
  • 8.4.2 Confirm "Technical Data Sheet" appears first, not 12th
  • 8.4.3 Validate left/right column interleaving by row

Result: Multi-column PDFs now render with correct reading order (逐行從上到下,每行內從左到右)

Phase 4: Testing and Optimization (P2 - Week 3)

8. Comprehensive Testing

• 8.1 Create test suite for layout preservation
  • 8.1.1 Unit tests for each component
  • 8.1.2 Integration tests for full pipeline
  • 8.1.3 Visual regression tests
• 8.2 Test with various document types
  • 8.2.1 Scientific papers (complex layout)
  • 8.2.2 Business documents (tables/charts)
  • 8.2.3 Books (chapters/paragraphs)
  • 8.2.4 Forms (precise positioning)
• 8.3 Performance testing
  • 8.3.1 Measure generation time
  • 8.3.2 Profile memory usage
  • 8.3.3 Identify bottlenecks

9. Performance Optimization

• 9.1 Implement caching
  • 9.1.1 Cache font metrics
  • 9.1.2 Cache parsed styles
  • 9.1.3 Reuse computed layouts
• 9.2 Optimize image handling
  • 9.2.1 Lazy load images
  • 9.2.2 Compress when appropriate
  • 9.2.3 Stream large images
• 9.3 Batch operations
  • 9.3.1 Group similar rendering ops
  • 9.3.2 Minimize context switches
  • 9.3.3 Use efficient data structures

10. Documentation and Deployment

• 10.1 Update API documentation
  • 10.1.1 Document new rendering capabilities
  • 10.1.2 Add examples of improved output
  • 10.1.3 Note performance characteristics
• 10.2 Create migration guide
  • 10.2.1 Explain improvements
  • 10.2.2 Note any breaking changes
  • 10.2.3 Provide rollback instructions
• 10.3 Deployment preparation
  • 10.3.1 Feature flag setup
  • 10.3.2 Monitoring metrics
  • 10.3.3 Rollback plan

Success Criteria

Must Have (Phase 1)

• Images appear in generated PDFs (path issue exists but rendering works)
• Tables render with correct layout (verified in tests)
• No regression in existing functionality (backward compatible)
• Fix Page attribute error (first_page.dimensions.width)

Should Have (Phase 2)

• Text styling preserved in Direct track (span-level rendering working)
• Font sizes and colors applied (verified in logs)
• Line breaks maintained (multi-line text working)
• Track-specific rendering (Direct track fully functional)

Nice to Have (Phase 3-4)

• Paragraph formatting (spacing and indentation working)
• List rendering (sequential numbering implemented)
• Span-level styling (verified with 21+ spans per element)
• <10% performance overhead (not yet measured)
• Visual regression tests (not yet implemented)

Timeline

• Week 0: Phase 1 - Critical fixes (images, tables)
• Week 1: Phase 2 - Basic style preservation
• Week 2: Phase 3 - Advanced layout features
• Week 3: Phase 4 - Testing and optimization
• Week 4: Review, documentation, and deployment