Scanned PDF To Epub

Scanned PDF To EPUB

Overview

Convert scanned Chinese PDFs into readable text EPUBs without losing editorial aids such as underlined names. The workflow is cross-platform: choose OCR and rendering tools available on the user's machine, verify a small sample first, then scale.

Environment Preparation

Start every conversion with an environment check; the user should not need to ask separately for tool installation. Follow environment setup to detect the OS and usable runtimes, reuse host-provided tools, and install only missing dependencies for the chosen pipeline in a task-local virtual environment. Reuse a previously verified environment when its executable paths still work.

Explain the selected tools briefly and continue within the user's existing authorization. Do not require confirmation for each routine local dependency. For system-level installation, paid services, or uploading book content, check existing authorization and host permissions; ask only for the concrete missing authorization. Do not silently switch from local to cloud OCR.

Before processing the whole book, run one real body page through rendering, Chinese OCR with coordinates, and a minimal text EPUB package. An installed command or successful import alone does not establish readiness. If setup fails, diagnose the error or choose an available equivalent; report the exact blocker rather than claiming the environment is ready.

Workflow

1. Inspect the PDF.

   • Use pdfinfo/Poppler when available, or Python libraries such as pypdf, PyMuPDF, or pypdfium2 for page count, metadata, page size, text layer, outline/bookmarks.
   • If extract_text() is empty on early pages, treat it as scan/OCR work.
   • Render a few pages with Poppler, PyMuPDF, or pypdfium2 and visually locate title, table of contents, and first body page.

2. Build a sample before full conversion.

   • Pick title/front matter plus one complete short section.
   • Confirm PDF page number vs printed page number offset.
   • Make the EPUB title, nav, and NCX point to real section starts.

3. OCR text with coordinates.

   • Prefer OCR that returns text boxes/character boxes.
   • On Windows, prefer PaddleOCR for local Chinese OCR; use Tesseract only as a fallback for simpler pages. Cloud OCR such as Azure, Baidu, Tencent, or Google is acceptable when privacy/cost is acceptable.
   • On macOS, Vision OCR via a tiny Swift helper is a good local default; PaddleOCR is also fine for portability.
   • On Linux, prefer PaddleOCR or Tesseract, with cloud OCR as the high-accuracy fallback.
   • If OCR returns only line/word boxes, estimate character boxes from the line box and text length; mark underline detection as lower confidence.
   • Sort lines by page coordinates; remove page headers, marginal running titles, and page numbers. In every text path (including the main body), merge same-row OCR fragments left-to-right before computing indentation. Carry character boxes through the merge for proper-name marking; a fragment starting far to the right is not evidence of a new paragraph.
   • Use OCR text for layout/alignment, then校对 against reliable text when available.
   • Reconstruct paragraphs across pages in all prose, including 前记、序跋 and commentary. A PDF page boundary must not create a new paragraph. Keep a paragraph buffer across pages; determine actual breaks from page-local text-region indentation, block style and headings. Do not use punctuation alone, raw x coordinates across facing pages, or one <p> per page.
   • Use logical row merging before paragraph accumulation in both front matter and body; it preserves character boxes. Calibrate row tolerance to OCR coordinates and process columns separately.
   • Read paragraph reconstruction before assembling XHTML. The optional paragraph accumulator supports horizontal prose when supplied with verified region-relative indentation; calibrate its inset-block assumptions to the source edition.

4. Preserve original underlined proper names.

   • Detect underlines from images as horizontal strokes near the bottom of OCR character boxes.
   • If character boxes are estimated, compare the detected stroke span against the estimated character centers and manually review more tokens.
   • Apply detection only to body lines, not headings; headings create false positives from Hanzi strokes.
   • Convert detected spans into semantic markup before styling, e.g. <span class="proper-name">周威烈王</span>.

5. Choose WeRead marking strategy.

   • For 微信读书 App and web together, prefer font/weight marking over underline: <strong class="proper-name" style="font-family:'Kaiti SC','STKaiti','KaiTi','楷体','FangSong','STFangsong',serif;font-weight:700;text-decoration:none;border:0;background:transparent;">周威烈王</strong>
   • Do not use border-bottom for WeRead web; its column layout can stretch borders across lines/columns.
   • Do not mix Unicode combining underline marks with web CSS in one WeRead file; web may render combining marks as misplaced strokes.
   • If the user insists on real underlines, produce separate App and web editions. See implementation notes.

6. Package and validate EPUB.

   • Use EPUB3: mimetype, META-INF/container.xml, OEBPS/content.opf, nav.xhtml, and toc.ncx.
   • XHTML must parse as XML. Zip mimetype first and uncompressed.
   • Validate with unzip -t; parse OPF/nav/NCX/XHTML with XML parser.
   • Audit every page boundary as join, new-paragraph, or section transition; inspect ambiguous cases in the source. Check known continuations in the generated XHTML are inside one <p>, and verify actual new paragraphs and chapter boundaries remain separate. Include front matter and indented commentary in this check; XML/ZIP validity does not validate reading order or paragraph structure.
   • Treat reader rendering as a separate check: compare visible column-boundary text against XHTML on the target reader. If text exists in the EPUB but is missing onscreen, investigate import parsing/rendering; a no-markup comparison edition can test style involvement, but do not claim a confirmed cause or fix without reproducing the result.
   • Report sample scope, remaining OCR risk, and which reader edition to use.