PP-OCR Autopsy
PaddleOCR's document pipeline taken apart piece by piece: every step that is not a neural network rewritten by hand and checked identical to the original, on a CV and a heritage catalogue form.
Introduction
PaddleOCR turns a PDF into text, and with PP-StructureV3 into Markdown with headings, images and tables. One call does it all, and that is the problem: when the output is wrong there is no way to tell which part failed.
So I took it apart. Each component runs on its own, its inputs and outputs are recorded, and every step that is not a neural network is rewritten from scratch and checked against the library until both give the same result, number for number.
The page follows the data through the stages in order, from the PDF to the table HTML. Each stage runs the rewritten code live in your browser on the real outputs of the networks, so you can move a threshold and watch what changes.
- CV
- My own CV: two columns, a photo, headings, icons and bullet lists. It is the case where reading order and images matter.
- ICCD form
- A catalogue record from Italy's heritage census (Santa Maria del Monte Serra, Cetraro): a two-page grid of field codes and long Italian text, a real table.
Pick a document at the top of any stage and every stage switches to it.
Methodology
The stages follow the data. First the plain OCR (detection, glue, recognition), rebuilt by hand and compared with PaddleOCR. Then the document layer PP-StructureV3 adds on top: block types, regions, reading order, images and tables.
PDF ─► render ─► DET ─► sort + crop ─► REC ─► text PaddleOCR(...).predict()
│ [net] (no model) [net]
│ └ pre-process, DB post-process └ resize to 48 px, CTC decoding
│
└─► LAYOUT [net] + REGIONS [net] ─► rules ─► reading order ─► Markdown PP-StructureV3
└ thresholds, NMS, merges └ blocks → regions, lines → blocks
└─► table: classifier [net] ─► structure [net] ─► match lines ↔ cells ─► HTML
[net] = a trained network, the only borrowed part. Everything else is rewritten here.- Call the component alone (TextDetection, TextRecognition, LayoutDetection…) with the parameters the full pipeline gives it. They are not the module defaults.
- Open its predictor: the pre-process steps, the network runner and the post-process object, run one at a time.
- Rewrite every step that is not the network with NumPy and OpenCV, and assert that the result equals PaddleX's.
- Export the network's raw output, so this page can run the same code again in TypeScript on top of it.
- 2.0 MB
- PP-OCRv6_tiny_det
- 4.6 MB
- PP-OCRv6_tiny_rec
- 130.4 MB
- PP-DocLayout_plus-L
- 129.9 MB
- PP-DocBlockLayout
The OCR networks are tiny. The two layout detectors are RT-DETR-L models, 130 MB each. Anything not listed here is code you can read.
00 · PDF → pixels


A PDF stores text and vectors, not pixels. The models only see pixels, so the first step is to photograph each page. The zoom decides how many pixels a letter gets: at 72 DPI small type is a few pixels tall, at 216 DPI everything gets slower. PaddleX renders at zoom 2 (144 DPI).
- in
- CV_2026_10.pdf · 1 pages
- page
- 595.5 × 842.2 pt (1 pt = 1/72")
- render
- pypdfium2 · zoom = 2 · 144 DPI
- out
- ndarray (1685, 1191, 3) uint8 · BGR
- a pixel
- three integers 0–255, blue first (OpenCV order)
01a · Detection
The detector does not read. It marks blobs, and they come out in the order the contour search finds them, from the bottom of the page up. Putting them in reading order is stage 02's job.
| parameter | TextDetection | PaddleOCR(…) |
|---|---|---|
| limit_side_len / type | 960 · max | 64 · min |
| thresh | 0.2 | 0.3 |
| box_thresh | 0.4 | 0.6 |
| unclip_ratio | 1.4 | 1.5 |
The standalone module and the full PaddleOCR pipeline do not use the same defaults. To reproduce the pipeline, the module has to be called with the pipeline's values. The live boxes are computed in your browser from the network's probability map. They land within a couple of pixels of PaddleX's: the rest is pyclipper rounding to integers and OpenCV working in float32.
01b · Detection, inside
page (H, W, 3) uint8 BGR
Read BGR → RGB
Resize H, W → nearest multiple of 32 # the net halves the image 5×: 2⁵ = 32
Normalize (x / 255 − mean) / std # mean (0.485, 0.456, 0.406), std (0.229, 0.224, 0.225)
ToCHW (H, W, 3) → (3, H, W)
ToBatch (3, H, W) → (1, 3, H, W) float32- page
- (1685, 1191, 3) uint8
- resized
- (1696, 1184, 3)
- tensor
- (1, 3, 1696, 1184) float32 · [-2.015, 2.64]
- 2 · network
- PP-OCRv6_tiny_det, 1.97 MB, the only learned step
- output
- (1, 1, 1696, 1184) · mean 0.1
- Threshold: a pixel is text if p > thresh.
- Blobs: group touching pixels (8-connectivity).
- Fit the minimum-area rectangle around each blob; drop it if its short side is under 3 px.
- Score it by the mean probability inside; drop it under box_thresh.
- Unclip: push every side out by area × ratio / perimeter, then scale back to the page.
Why unclip? DB is trained to mark a shrunk core of each line, so two lines close together never melt into one blob. The box only gets its real size back at the end. OpenCV also counts holes inside blobs as contours, which is why its contour count can be higher than the blob count. Those holes never survive the filters.
Module defaults in the model's inference.yml: thresh 0.2 · box_thresh 0.4 · unclip 1.4 · max_candidates 3000
02 · Sort + crop
SortQuadBoxes: by the y of the top-left corner, then neighbours less than 10 px apart are swapped left to right. It is a simple rule with no idea of columns. On the CV, the left sidebar and the main column interleave line by line, which is exactly why PP-StructureV3 adds a layout model (stage 05).
Minimum-area rectangle → corners in a fixed order → perspective warp onto a straight rectangle. Strips at least 1.5× taller than wide are turned 90°. The recogniser never sees the page, only these strips. Here the canvas does the warp.
03a · Recognition
PP-OCRv6_tiny_rec answers one question: what does this strip say? It can only read a single line that has already been cut out, and it returns the text plus a confidence, the mean over the characters it wrote.
Sort by lowest score: the worst lines on the CV are its icons. A phone or a GitHub logo is not text, but the model has to write something, so it picks the closest symbol in its dictionary. That can be a Chinese character, or nothing at all.
- original0.98
« interpretazione dei dati, con un focus sulla modellazione economica. » - left half only0.99
« interpretazione dei dati, con un f »
- top half only (letters cut)0.57
« intoMnmoteziep.edeidotieenunfoeueoulem2.e dolezioneeeene3oiee »
- rotated 180°0.51
« 'ojouoea euolzeepo eins snoo} un uoo ‘nep ep euolzreudeu! » - blurred0.73
« inßergretaaigve deiedafi. con un focus sullamoielliaaioneegonomica » - ⅓ resolution0.70
« inlorμrclaliurrc ciculi Lu11 un1 Fucurasulliu muckelluiurc cu1u=icni. »
- half of one line + half of the next0.77
« Anerprelazitne: deh cdaanincoo automociose sutidizzoodectzlonemnetonoo ca. »
The last case is what a badly cut box looks like: half of two lines. The tiny model then produces confident-looking gibberish. When an OCR result is garbage, the cause is often the box, not the recogniser.
03b · Recognition, inside
·i·n··t·e·r··p·r··e·t·a·z·i·o··n··e··␣␣···d·e·i··␣␣··dd·a·t·i,␣␣␣··c··o··n··␣␣···u·n··␣␣··f··o·c··u··s·␣␣··s··ull·la··␣␣····m··o··d··el·l·a·z·i·o··n··e··␣␣··e··c··o··n·o····m·i·c·a·.·i·n·t·e·r·p·r·e·t·a·z·i·o·n·e·␣·d·e·i·␣·d·a·t·i,␣·c·o·n·␣·u·n·␣·f·o·c·u·s·␣·s·ul·la·␣·m·o·d·el·l·a·z·i·o·n·e·␣·e·c·o·n·o·m·i·c·a·.interpretazione dei dati, con un focus sulla modellazione economica.The network does not read letter by letter. It sweeps the strip in T vertical slices and gives each one a probability for all 6,906 symbols. The blank (·) means "nothing new here". It is also what lets a word contain double letters: l·l gives ll, while ll collapses to l.
- [0]
- blank: "no new character"
- [1…39]
- ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~ 0 1 2 3 4 5 6 …
- [6905]
- the space
The model can only ever write what is in this list. Over 6,100 of its symbols are Chinese characters; the rest are Latin, Greek, full-width and circled forms. That is why an icon can come out as 四.
04 · Pipeline by hand
def ocr_by_hand(page):
polys = det.predict(page, **PIPELINE_PARAMS) # 01 network + DB post-process
polys = sort_quad_boxes(polys) # 02 plain code
strips = [crop(page, p) for p in polys] # 02 plain code
order = argsort([w / h for h, w in strips]) # what PaddleOCR does before batching
texts = rec.predict([strips[i] for i in order], batch_size=6)
return unsort(texts, order), polys # 03 network + CTCFirst attempt: same boxes, same strips, same models, but a few lines differ. Recognition runs in batches of six, and every strip in a batch is padded to the widest one. The padding changes what the network sees for short strips.
| # | by hand | PaddleOCR |
|---|---|---|
| 14 | «+39 351739 5315» | «+39 351 739 5315» |
| 17 | «V» | «» |
| 28 | «9» | «四» |
| 31 | «05/2023-PRESENTE» | «05/2023 - PRESENTE» |
| 38 | «2022- 2024» | «2022 -2024» |
| 48 | «06/2025-08/2025» | «06/2025 -08/2025» |
0 HÉCTOR ARÍSTIDES 1 05/10/2026 2 LICEA BEATÓN 3 ECONOMISTA 4 DESCRIZIONE 5 Economista 6 con 7 solida 8 esperienza 9 nell'estrazione, 10 modellazione 11 CONTATTO 12 interpretazione dei dati, con un focus sulla modellazione economica. 13 Appassionato di web scraping e automazione, utilizzo queste competenze per 14 +39 351 739 5315 15 trasformare i dati in conoscenza applicata alle scienze sociali. Negli ultimi anni 16 ho sviluppato (Python) e seguito progetti innovativi basati sull’intelligenza 17 18 [email protected] 19 artificiale. Dispongo di competenze in machine learning, analisi di embeddings, 20 clustering e visualizzazione dei dati, con particolare attenzione allintegrazione 21 Rende, Cosenza 22 tra approcci classici/statistici ed Al generativa. Per approfondire le mie 23 competenze pratiche, puoi consultare il mio Portfolio Interattivo: 24 25 Interactive Portfolio 26 https://data-mia.org 27 ESPERIENZA LAVORATIVA 28 四 29 Github 30 Wish S.R.L 31 05/2023 - PRESENTE 32 Steam Account 33 Data Scientist 34 • Sviluppo e implementazione di modelli di machine learning 35 ISTRUZIONE 36 Implementazione di modelli di IA 37 • Pulizia e preparazione dei dati per analisi approfondite 38 2022 -2024 39 Utilizzo di linguaggi di programmazione come Python e R per analisi 40 UNIVERSITA DELLA CALABRIA 41 statistiche 42 ITALIA 43 • Analisi e interpretazione dei risultati della applicazione di modelli 44 statistici 45 Economia e Commercio 46 47 UNICAL (DISCAG) 48 06/2025 -08/2025 49 2013 - 2018 50 UNIVERSIDAD DE ORIENTE 51 Master Gestione della transizione verde e dei rischi climatici 52 CUBA 53 • Docente di Python per Analisi di Dati nel Master Gestione della 54 Economia 55 transizione verde e dei rischi climatici 56 COMPETENZE 57 58 Universidad de Oriente 59 08/2018-09/2021 60 Professore 61 • Analisi dei dati 62 • Professore Istruttore a tempo pieno, Economia Cubana. 63 Conoscenza delle teorie economiche 64 Competenze in statistica 65 CERTIFICATI E CORSI 66 Pensiero critico 67 Programmazione Python 68 Programmazione R 69 Curso completo de Python: Programación en Python desde cero 70 Deploy di Workflow IA 71 Udemy 72 Web Scraping 73 C# Total - Programador Experto en 28 días 74 • SPARQL 75 Udemy 76 LINGUE 77 PUBBLICAZIONI 78 Spagnolo (Madrelingua) 79 Italiano (Fluent) 80 Inglese (Fluent) 81 Employment and Self-Employment in the Santiago de Cuba Province. 82 Anuario Facultad de Ciencias Económicas y Empresariales
05a · Layout
PP-DocLayout_plus-L does not read either. It decides that something is a title, a paragraph or a picture purely from how it looks: position, size, weight and white space around it.
PP-StructureV3 reads a YAML with a threshold per class (0.3 for titles, 0.4 for text, 0.5 for most others), turns NMS on, and merges boxes class by class.

- ReadImage
- (1685, 1191, 3)
- Resize
- (800, 800, 3)
- Normalize
- (800, 800, 3)
- ToCHWImage
- (3, 800, 800)
- network
- RT-DETR-L · 130 MB · 6336 ms
- out
- 300 × [class, score, x1, y1, x2, y2]
Unlike the text detector, this one does not keep the aspect ratio: the page is squashed to 800×800, and a scale factor maps the boxes back. It always returns 300 candidates, most of them noise with a tiny score. All of the filtering above is code.
05b · Regions & order
PP-DocBlockLayout is the same kind of detector with a single class: Region. It shows what belongs together (dashed). Then plain rules pour blocks into regions, smallest region first: a block joins at ≥ 60 % overlap and the region snaps to its blocks. Leftover blocks share a SupplementaryRegion. Out-of-flow blocks such as page numbers and headers each get their own, which is why that region always scores exactly 1.00.
HÉCTOR ARÍSTIDES LICEA BEATÓN

CONTATTO
+39 351 739 5315
Rende, Cosenza
Interactive Portfolio
四Github
Steam Account
ISTRUZIONE
2022 -2024
UNIVERSITA DELLA CALABRIA
ITALIA
Economia e Commercio
2013 - 2018
UNIVERSIDAD DE ORIENTE
CUBA
Economia
COMPETENZE
• Analisi dei dati
Conoscenza delle teorie economiche
Competenze in statistica
Pensiero critico
Programmazione Python
Programmazione R
Deploy di Workflow IA
Web Scraping
• SPARQL
LINGUE
Spagnolo (Madrelingua)
Italiano (Fluent)
Inglese (Fluent)
ECONOMISTA
DESCRIZIONE
Economista con solida esperienza nell'estrazione,modellazione interpretazione dei dati, con un focus sulla modellazione economica.Appassionato di web scraping e automazione, utilizzo queste competenze per trasformare i dati in conoscenza applicata alle scienze sociali. Negli ultimi anni ho sviluppato (Python) e seguito progetti innovativi basati sull’intelligenza artificiale. Dispongo di competenze in machine learning, analisi di embeddings,clustering e visualizzazione dei dati, con particolare attenzione allintegrazione tra approcci classici/statistici ed Al generativa. Per approfondire le mie competenze pratiche, puoi consultare il mio Portfolio Interattivo:https://data-mia.org
ESPERIENZA LAVORATIVA
Wish S.R.L
05/2023 - PRESENTE
Data Scientist
• Sviluppo e implementazione di modelli di machine learning
Implementazione di modelli di IA
• Pulizia e preparazione dei dati per analisi approfondite
Utilizzo di linguaggi di programmazione come Python e R per analisi statistiche
• Analisi e interpretazione dei risultati della applicazione di modelli statistici
UNICAL (DISCAG)
06/2025 -08/2025
Master Gestione della transizione verde e dei rischi climatici
• Docente di Python per Analisi di Dati nel Master Gestione della transizione verde e dei rischi climatici
Universidad de Oriente
08/2018-09/2021
Professore
• Professore Istruttore a tempo pieno, Economia Cubana.
CERTIFICATI E CORSI
Curso completo de Python: Programación en Python desde cero Udemy
C# Total - Programador Experto en 28 días Udemy
PUBBLICAZIONI
Employment and Self-Employment in the Santiago de Cuba Province.Anuario Facultad de Ciencias Económicas y Empresariales
Each block becomes Markdown by label: doc_title → #, paragraph_title → ##, text → a paragraph, image → <img>, table → HTML. Blocks labelled number, header, header_image, footer, footer_image, aside_text are dropped.
06a · Image or table?
- image0.848
- header0.272
- paragraph_title0.059
- text0.049
- image0.047

An image block is cropped and saved next to the Markdown. Any text the OCR found inside it is discarded.
<img src="imgs/img_in_image_box_65_63_328_322.jpg">text · titlesCollect the OCR lines inside the block → paragraph or heading.imageCrop to imgs/img_in_image_box_x1_y1_x2_y2.jpg → <img>.tableCrop → classifier → structure model → match OCR lines to cells → HTML.chart · formula · sealOnly with their own recognisers switched on, which this run did not.number · header · footerKept for the order, dropped from the Markdown.
There is no separate "is this a picture?" model, so a dark scan could in principle look like one big photo. That is what the giant-image filter in 05a is for: an image box covering more than 93 % of a portrait page is dropped. Here the labels survive the darkening.
06b · Table parser
Results
- Every plain-code step (DB post-process, sorting, cropping, CTC decoding, layout post-process, region rules, both table parsers) was rewritten and asserted identical to PaddleX on all three pages.
- Chained by hand, the pipeline first agreed with PaddleOCR on 206 of 217 lines. The 11 differences came from batching: PaddleOCR sorts strips by aspect ratio and pads each batch of six to its widest strip. Doing the same gives 217/217.
- Only the networks are learned: 2.0 MB for the text detector and 4.6 MB for the recogniser, 130 MB each for the layout and region detectors. Everything around them is geometry and bookkeeping.
- The two pages of the same ICCD form take different routes: page 1 is classified as a wired table (69 %) and goes through a cell detector, page 2 as wireless (69 %) and is parsed end to end by the structure model.
- The page re-runs the same post-processing live in the browser: DB on the shipped probability maps, CTC on the recogniser's columns, the layout filters on all 300 raw candidates, the region rules and the table assembly.
Technical explanation
One script runs every stage in a throw-away Docker image with PaddlePaddle 3.3 and PaddleOCR 3.7. Each hand-written step is asserted equal to PaddleX's own, and the build stops if one differs.
- Asserted
- Detection tensor, DB boxes, sort, crops, CTC text and score, layout post-process, regions, table cell boxes and HTML
- Shipped
- Page images, the detector's probability maps (16-bit PNG), the top-3 symbols per CTC column, all 300 layout candidates, region and table outputs
- Size
- About 4 MB for three pages, loaded one stage at a time
This portfolio is served from a Raspberry Pi. The full PP-StructureV3 stack needs gigabytes of RAM, has poor ARM support, and takes seconds to minutes per page on a CPU. It does not belong on the Pi.
It does not need to be there either. The networks ran once at build time. Everything this page lets you change happens after them, and that is exactly the code that was rewritten, so the browser can run it.
Conclusion
- Most of an OCR pipeline is not AI. Out of a dozen stages only the networks are learned. Thresholds, geometry, sorting, decoding and matching rules are plain code, and that is where most of the behaviour you can tune lives.
- The surprises were in the glue: different defaults for the same model in two entry points, batch padding changing the text, a rule that lets one line feed two blocks, and two pages of the same form sent to two different table parsers.
- Knowing each piece makes the system repairable. A bad line can now be traced to its box, its strip, its columns or its block, and fixed at that step, instead of swapping the whole library.
- The same method works for any packaged model: isolate, record inputs and outputs, rewrite the code around the network, and prove it identical before changing anything.