egg/OCR
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
09cf9149ce7aaf1406198d7c680583acdb3507a8
OCR/openspec/changes/pdf-layout-restoration/tasks.md
egg 09cf9149ce feat: implement proper track-specific PDF rendering 
Implement independent Direct and OCR track rendering methods with
complete separation of concerns and proper line break handling.

**Architecture Changes**:
- Created _generate_direct_track_pdf() for rich formatting
- Created _generate_ocr_track_pdf() for backward compatible rendering
- Modified generate_from_unified_document() to route by track type
- No more shared rendering path that loses information

**Direct Track Features** (_generate_direct_track_pdf):
- Processes UnifiedDocument directly (no legacy conversion)
- Preserves all StyleInfo without information loss
- Handles line breaks (\n) in text content
- Layer-based rendering: images → tables → text
- Three specialized helper methods:
  - _draw_text_element_direct(): Multi-line text with styling
  - _draw_table_element_direct(): Direct bbox table rendering
  - _draw_image_element_direct(): Image positioning from bbox

**OCR Track Features** (_generate_ocr_track_pdf):
- Uses legacy OCR data conversion pipeline
- Routes to existing _generate_pdf_from_data()
- Maintains full backward compatibility
- Simplified rendering for OCR-detected layout

**Line Break Handling** (Direct Track):
- Split text on '\n' into multiple lines
- Calculate line height as font_size * 1.2
- Render each line with proper vertical spacing
- Font scaling per line if width exceeds bbox

**Implementation Details**:
Lines 535-569: Track detection and routing
Lines 571-670: _generate_direct_track_pdf() main method
Lines 672-717: _generate_ocr_track_pdf() main method
Lines 1497-1575: _draw_text_element_direct() with line breaks
Lines 1577-1656: _draw_table_element_direct()
Lines 1658-1714: _draw_image_element_direct()

**Corrected Task Status**:
- Task 4.2: NOW properly implements separate Direct track pipeline
- Task 4.3: NOW properly implements separate OCR track pipeline
- Both with distinct rendering logic as designed

**Breaking vs Previous Commit**:
Previous commit (3fc32bc) only added conditional styling in shared
draw_text_region(). This commit creates true track-specific pipelines
as per design.md requirements.

Direct track PDFs will now:
✅ Process without legacy conversion (no info loss)
✅ Render multi-line text properly (split on \n)
✅ Apply StyleInfo per element
✅ Use precise bbox positioning
✅ Render images and tables directly

OCR track PDFs will:
✅ Use existing proven pipeline
✅ Maintain backward compatibility
✅ No changes to current behavior

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-24 07:53:17 +08:00

7.3 KiB
Raw Blame History

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
    • 1.3.2 Test with Direct track document
    • 1.3.3 Verify images appear in PDF output

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
    • 2.4.2 Test complex multi-column tables
    • 2.4.3 Test with both tracks

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
    • 4.4.2 Verify OCR track maintains quality

Phase 3: Advanced Layout (P2 - Week 2)

5. Enhanced Text Rendering

  • 5.1 Implement line-by-line rendering
    • 5.1.1 Split text content by newlines
    • 5.1.2 Calculate line height from font size
    • 5.1.3 Render each line with proper spacing
  • 5.2 Add paragraph handling
    • 5.2.1 Detect paragraph boundaries
    • 5.2.2 Apply paragraph spacing
    • 5.2.3 Handle indentation
  • 5.3 Implement text alignment
    • 5.3.1 Support left/right/center/justify
    • 5.3.2 Calculate positioning based on alignment
    • 5.3.3 Apply to each text block

6. List Formatting

  • 6.1 Detect list elements
    • 6.1.1 Identify list items from metadata
    • 6.1.2 Determine list type (ordered/unordered)
    • 6.1.3 Extract indent level
  • 6.2 Render lists with proper formatting
    • 6.2.1 Add bullets/numbers
    • 6.2.2 Apply indentation
    • 6.2.3 Maintain list spacing

7. Span-Level Rendering (Advanced)

  • 7.1 Extract span information from Direct track
    • 7.1.1 Parse children elements for spans
    • 7.1.2 Get per-span styling
    • 7.1.3 Track position within line
  • 7.2 Render mixed-style lines
    • 7.2.1 Switch styles mid-line
    • 7.2.2 Handle inline formatting
    • 7.2.3 Preserve exact positioning

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
  • Tables render with correct layout
  • No regression in existing functionality

Should Have (Phase 2)

  • Text styling preserved in Direct track
  • Font sizes and colors applied
  • Line breaks maintained

Nice to Have (Phase 3-4)

  • Paragraph formatting
  • List rendering
  • Span-level styling
  • <10% performance overhead

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