Tools,

PP-StructureV3 on a book scan: light settings won

1,807

of 1,955 words, light settings

Get the script

Light settings: more words, half the time

Four runs on the same 10 scanned book pages, on a Mac CPU with 2 threads.

Words found of 1,955, and time
Settings Words Time
Defaults 1,624 472 s
--flat 1,711 431 s
--flat --mobile 1,807 245 s
--light 1,807 215 s

--flat turns off the page turn, unwarp and line turn models. The mobile OCR models gave the extra words. --light also skips the table, formula and region models.

The script, part 1: flags

pip install paddlepaddle==3.3.1 "paddleocr[doc-parser]==3.7.0"

Or download pp_structure.py.

"""PP-StructureV3 on a scanned PDF: book.md plus one JSON file per page
(brasspage.com/pp-structure/, Nov 15, 2026)."""

import argparse
from pathlib import Path

from paddleocr import PPStructureV3

ap = argparse.ArgumentParser()
ap.add_argument("pdf")
ap.add_argument("--out", default="out")
ap.add_argument("--threads", type=int, default=10)  # PaddleOCR's default
# --flat: no page turn, unwarp or line turn models
ap.add_argument("--flat", action="store_true")
# --mobile: the small PP-OCRv5 mobile OCR models, not server
ap.add_argument("--mobile", action="store_true")
# --light: --flat --mobile, and no table, formula or region models
ap.add_argument("--light", action="store_true")
a = ap.parse_args()

Part 2: run and write

opts = {"cpu_threads": a.threads}
if a.flat or a.light:
    opts["use_doc_orientation_classify"] = False
    opts["use_doc_unwarping"] = False
    opts["use_textline_orientation"] = False
if a.mobile or a.light:
    opts["text_detection_model_name"] = "PP-OCRv5_mobile_det"
    opts["text_recognition_model_name"] = "PP-OCRv5_mobile_rec"
if a.light:
    opts["use_table_recognition"] = False
    opts["use_formula_recognition"] = False
    opts["use_region_detection"] = False
pipe = PPStructureV3(**opts)
out = Path(a.out)
out.mkdir(exist_ok=True)
pages = list(pipe.predict(a.pdf))
for res in pages:
    res.save_to_json(str(out))  # out/<name>_<page>_res.json: blocks, boxes, text
md = pipe.concatenate_markdown_pages([r.markdown for r in pages])
# md is a MarkdownResult, not a str: write its text
(out / "book.md").write_text(md["markdown_texts"])
python pp_structure.py scan.pdf --light --threads 2

The docs example passes md to f.write(). In 3.7.0 that raises TypeError: write() argument must be str, not MarkdownResult.

The defaults bend a flat scan

With no options, the page JSON says use_doc_unwarping: True. On our flat pages that cost words. Page 1, second paragraph, first line:

Settings Text
Defaults [Ta]
--flat The boy slackened his pace a bit to rattle off

Markdown glues words together

The Markdown has words with no space after a punctuation mark: "story.When", "store,he". Our scorer counts each as two missed words.

The defaults have 103 glued spots, about half of them already in the OCR lines. --light has 24, and 23 of those come from the Markdown join.

Running heads become headings

Each of our pages has a running head, like THE UNCOMMON PRAYER-BOOK, and no real heading. With --light, 4 were dropped as headers and 6 became headings.

... Said he was an Indian traveling to Dare

## The Boy Scouts of the Air

County and that his name was Buffalo ...

Five of the six land mid-sentence, like this one.

The fix: rebuild text from the JSON

clean.py drops page numbers, headers and titles near the top of a page, then puts the spaces back.

import json
import re
import sys
from pathlib import Path

files = Path(sys.argv[1]).glob("*_res.json")
pages = [json.loads(f.read_text()) for f in files]
pages.sort(key=lambda p: p["page_index"] or 0)
paras = []
for page in pages:
    for b in page["parsing_res_list"]:
        label, box = b["block_label"], b["block_bbox"]
        near_top = box[3] < 0.15 * page["height"]
        if label in ("number", "header", "footer"):
            continue  # page numbers and running heads
        if label == "paragraph_title" and near_top:
            continue  # running heads the layout model called titles
        text = b["block_content"].strip()
        paras.append(re.sub(r"([a-z][.,;:!?])(?=[\"'“‘]?[A-Za-z])", r"\1 ", text))
print("\n\n".join(paras))
python clean.py out > book.txt

With the fix: 1,846 words

Words found of 1,955
Settings book.md clean.py
Defaults 1,624 1,803
--light 1,807 1,846

The 15% line fits our pages. A chapter title near the top of your page would go too, so check.

Plain PaddleOCR found more words

Same 10 pages, words found of 1,955
Tool Words Time
PaddleOCR-VL 1.6 (Mac GPU) 1,947 73 s
PP-OCRv6, no unwarp 1,919 319 s
Tesseract 5.5.4 1,878 38 s
Our Actor's code 1,877 45 s
PP-StructureV3 --light + clean.py 1,846 215 s

PP-StructureV3 adds layout: labels, boxes, reading order, Markdown. For the plain text of a book scan, you do not need it.

The scan is 10 proofread pages from two public domain books on Wikisource: 1,955 words. The score is true words found in order.

How we ran it
  • A Mac with Apple M5 Max, Python 3.12.12, paddlepaddle 3.3.1, paddleocr 3.7.0, paddlex 3.7.2.
  • Every run: --threads 2, OMP_NUM_THREADS=2, low priority, one at a time, while other jobs ran. Times are rough.
  • Defaults use the PP-OCRv5 server OCR models and PP-DocLayout_plus-L for layout. The first run downloads 13 models, 1.86 GB, from Hugging Face. The formula model alone is 736 MB.
  • The PaddleOCR-VL, PP-OCRv6, Tesseract and Actor rows come from our earlier runs on the same scan, Nov 12 and Nov 15.
  • Licenses: PaddleOCR, PaddleX and PaddlePaddle are Apache-2.0. All 15 model cards the pipeline names say apache-2.0. We only ran them.

Watch the memory

Time and peak memory
Input and settings Time Peak
Our 10-page PDF, defaults 472 s 17.9 GB
The same, --light 215 s 3.0 GB
Page 1 alone as a 1920 px JPEG, defaults 145 s 38.5 GB

PaddleOCR draws PDF pages at 144 dpi: 922 px wide here.

Scanned pages to Markdown, no install

Run it yourself. Our Apify Actor turns a scanned PDF into Markdown or text. $0.006 a scanned page. Its code found 1,877 of these 1,955 words.

Try the Actor

Or send us the scan. Tack, our AI, does the job for $29, up to 50 pages. First page free.

Get one page free

Questions people ask

What is PP-StructureV3?

PaddleOCR's document parsing pipeline. It finds layout blocks, reads them with OCR, adds tables and formulas, and writes Markdown and JSON.

PP-StructureV3 or PaddleOCR-VL?

On our book scan, PaddleOCR-VL 1.6 found 1,947 of 1,955 words in 73 s on the Mac GPU. PP-StructureV3 with --light found 1,807 in 215 s on the CPU.

Why does writing the Markdown fail?

In PaddleOCR 3.7.0, concatenate_markdown_pages() returns a MarkdownResult, not a string. Write md["markdown_texts"].

Does it use the Mac GPU?

Not in our runs. The PaddlePaddle wheel for Mac runs on the CPU. We gave it 2 threads.

Did you test tables?

No. Our pages have no tables, and the layout model found no table blocks on them.