PDF OCR Bookmarks

Overview

Add navigation bookmarks (PDF outline/TOC) to scanned PDF documents by using OCR to read the table of contents page and locate section headers across all pages. Ensures bookmark jump targets match the actual content pages, not the logical page numbers printed in the TOC.

When to Use

• User asks to add bookmarks / navigation / TOC / outline to a PDF
• User asks to add 目录 / 导航栏 / 书签 to a PDF
• The PDF is a scanned image document (no extractable text layer)
• The PDF has a visible table of contents page but no embedded bookmarks

Workflow

Step 1: Detect PDF Type

Check whether the PDF has a text layer or is a scanned image:

import fitz
doc = fitz.open(input_pdf)
page = doc[0]
text = page.get_text().strip()
if len(text) < 10:
    # Scanned PDF - no text layer, needs OCR
else:
    # Text-layer PDF - extract text directly

• If text-layer PDF: extract TOC entries from text, find matching pages, write bookmarks. Skip to Step 5.
• If scanned PDF: proceed to Step 2.

Step 2: Set Up OCR Environment

Refer to references/environment_setup.md for detailed setup instructions. Key requirements:

1. Tesseract OCR installed at C:\Program Files\Tesseract-OCR\ (Windows)
2. Chinese language pack (chi_sim.traineddata) downloaded to a custom tessdata directory
3. PyMuPDF installed (use pdfkit-py skill's venv if direct pip install fails)
4. pytesseract + Pillow installed in the same venv

Set environment variables before importing pytesseract:

os.environ['TESSDATA_PREFIX'] = 'C:/Users/USERNAME/.workbuddy/tessdata'  # dir containing .traineddata files
pytesseract.pytesseract.tesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'

Step 3: OCR the Table of Contents Page

1. Ask the user which page contains the table of contents (commonly page 2-4)
2. Render the TOC page at 300 DPI and OCR with chi_sim+eng
3. Parse OCR text to extract section titles and their printed page numbers
4. Build a preliminary bookmark list: [[level, title, printed_page], ...]

OCR tips for TOC pages:
- Use --psm 4 (single column, variable sizes) or --psm 6 (uniform block)
- 300 DPI gives good accuracy for most scans
- Chinese-numeral section headers (一、二、三...) are reliable anchors

Step 4: OCR All Pages to Find Actual Section Positions

The printed page numbers in the TOC often do NOT match PDF page indices (cover pages, unnumbered pages cause offset). To ensure correct jump targets:

1. Run scripts/add_pdf_bookmarks.py --mode find_sections to OCR all pages (top 50% at 200 DPI)
2. Search each page's OCR text for section header keywords from the TOC
3. Match each TOC entry to the actual PDF page where its header first appears
4. For unmatched entries, try alternative keywords or visual inspection

Key matching strategy:
- Extract 1-3 distinctive keywords per TOC entry (e.g., "投标函", "开标一览表")
- Search page OCR text for these keywords in the first 5-8 lines (header region)
- If a keyword appears on multiple pages, prefer the earliest page where it appears as a header (short line, near top)

Step 5: Write Bookmarks to PDF

Use PyMuPDF set_toc() to write bookmarks:

import fitz
doc = fitz.open(input_pdf)
# toc = [[level, title, page_number_1based], ...]
doc.set_toc(toc)
doc.save(output_pdf, garbage=4, deflate=True)
doc.close()

Notes:
- Page numbers in TOC are 1-based (page 1 = first page)
- For parent-level bookmarks (level 1) without their own page, set page to the first child's page
- garbage=4 removes unused objects; deflate=True compresses streams
- File content is never modified - only bookmark metadata is added

Step 6: Verify and Deliver

1. Reopen the output PDF and call doc.get_toc() to verify bookmark count and page numbers
2. Copy to the user's desired output location
3. Present the file to the user

Scripts

scripts/add_pdf_bookmarks.py

General-purpose script supporting three modes:

--mode ocr_titles: OCR each page's top region and generate one bookmark per page (fallback when no TOC page exists).

--mode find_sections: OCR all pages, then search for user-specified section keywords to find actual page positions. Outputs a JSON file mapping section names to found pages.

--mode write_bookmarks: Write a predefined bookmark list (from JSON) to a PDF.

Usage:

python add_pdf_bookmarks.py --input input.pdf --output output.pdf --mode find_sections --keywords keywords.json
python add_pdf_bookmarks.py --input input.pdf --output output.pdf --mode write_bookmarks --bookmarks bookmarks.json

Common Pitfalls

1. Printed page numbers != PDF page indices: Always verify by OCR-searching for actual headers. A 3-page offset (cover + TOC) is common.
2. Tesseract language pack missing: Default Windows install only includes eng. Download chi_sim.traineddata separately.
3. TESSDATA_PREFIX path: Must point to the directory containing the .traineddata files, not a parent directory.
4. PyMuPDF on Python 3.13: Direct pip install pymupdf may fail. Use the pdfkit-py skill's venv which has PyMuPDF pre-installed.
5. Console encoding on Windows: Set sys.stdout.reconfigure(encoding='utf-8') or use PYTHONUNBUFFERED=1 to avoid GBK encoding errors with Chinese text.
6. Sandbox file access: Writing to Desktop may fail if the file is open. Save to a temp directory first, then copy.
7. OCR speed: ~1 page/second at 200 DPI with chi_sim+eng. A 100-page PDF takes ~2 minutes.