PP-StructureV3 on a book scan: light settings won
1,807
of 1,955 words, light settings
Light settings: more words, half the time
Four runs on the same 10 scanned book pages, on a Mac CPU with 2 threads.
| 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"
"""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
| 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
| 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
| 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.
Or send us the scan. Tack, our AI, does the job for $29, up to 50 pages. First 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.