[Bee] Support for Truncated Img Files and Reading Order Improvement

[SanjanaNagwekar]

Requested feature

1. Support for truncated/corrupted JPEG image files

Docling currently fails with an error when attempting to convert truncated image files (files where the image data is incomplete or partially corrupted). These files are valid enough to be rendered and processed by tools that use PIL's LOAD_TRUNCATED_IMAGES flag, but Docling's image loading pipeline does not account for this case.

The requested feature is for Docling to gracefully handle truncated image files by enabling PIL's ImageFile.LOAD_TRUNCATED_IMAGES = True (or an equivalent fallback strategy) so that conversion can proceed rather than failing outright. This mirrors what many production pipelines already do and would allow Docling to return a best-effort result instead of an error.

Sample truncated img file 1: https://ibm.box.com/s/gmie28q7no5flf0gdcb88k04auskye0e
Sample truncated img file 2: https://ibm.box.com/s/76ok5w6soyxagwdwf56cbu755xtneruc

2. Reading order improvement for mixed handwritten + machine-printed documents with rotation

When processing the JPG image file that contains both handwritten and machine-printed text with slight rotational skew (even when autorotation_correction=True is set), the reading order of the output is incorrect. Specifically, sentences that span both handwritten and machine-printed segments have their words interleaved out of sequence. We are processing this file with Docling + custom OCR.

Incorrect output: https://ibm.box.com/s/d26efi48coq4ffoxoekp7s7sciup9ve8

[sriharan0804]

Hi @SanjanaNagwekar, I’m interested in working on the truncated/corrupted JPEG handling part of this issue.

From the description, it looks like Docling currently fails when PIL encounters incomplete JPEG data, while enabling ImageFile.LOAD_TRUNCATED_IMAGES = True or adding a fallback strategy could allow best-effort conversion.

I can start by reproducing the failure with the provided sample images, then look for the correct image-loading path in Docling and add a small fix with tests.

For the reading-order improvement, I understand that may require a deeper layout/OCR ordering change, so I’d like to focus first on the truncated image support if that sounds okay.

[zeweihan]

Both of these are worth implementing, but the second one (reading-order corruption in mixed handwritten/printed text) is the one that bites hardest in production — and "reading order is wrong" undersells why.

Reading-order errors are silent semantic corruption, not cosmetic shuffling. The screenshot shows words that are all present and correctly OCR'd individually, but interleaved out of sequence. The downstream signature of that is exactly the failure mode that's hardest to catch: every word has a valid prov.bbox and a high OCR confidence, the character count matches the source, and a human skimming might not notice — but a sentence with its words reordered reads as different content. In a RAG pipeline, that reordered sentence gets embedded and retrieved as an authoritative statement of something the document never actually said. There's no "wrong" confidence score, no missing-content signal — the content survived, the order (which is the meaning at the sentence level) silently drifted. That's the same "plausible-but-wrong beats obviously-broken" class as numeric-coercion in table cells (#3698) and merged-cell value misattribution, just at the text-sequence layer instead of the table-structure layer.

Why mixed handwritten + machine-printed is the worst case. The two text sources are processed by different OCR paths (or different sub-models within one engine), and the reading-order reconstruction merges their outputs. If each path is individually correct but the merge orders them by spatial position without accounting for the handwritten block being a continuation of the machine-printed line (or vice versa), the interleaving is systematic, not random — the same sentence breaks the same way every time, which means it propagates consistently into the index and a regression test that checks "did we get the right words" will pass while the actual reading order is wrong. The rotation skew compounds this because it perturbs the bounding-box y-coordinates that most reading-order heuristics sort on, so a line that spans a rotation boundary gets its segments reordered by a coordinate that no longer reflects true vertical position.

For the truncated-image request — yes, but stamp it. Enabling LOAD_TRUNCATED_IMAGES = True is the right call for "don't crash, do your best," but the partial fill PIL applies is silent — the caller gets pixels back and can't tell which rows were inferred vs. read. For any image that carries operative content (a signature page, a stamped exhibit, an annotated clause), "best-effort reconstruction" should be an informed choice, not a silent one. The cheap companion: when a truncated image is loaded with the fallback, emit a per-image flag (image_truncated: True, optionally with the byte offset where truncation was detected) so a downstream consumer can route that image to a review queue instead of treating the reconstructed pixels as ground truth. The same principle as emitting a warning when an unsupported backend option is silently ignored (#3671) — silent best-effort is the most dangerous failure mode because it looks identical to success.

For the reading-order case specifically, even without fixing the underlying merge logic, a per-line reading-order confidence (does this line's word sequence match a plausible left-to-right reading given the bbox positions, or did the merge reorder segments?) would turn the silent corruption into a surfaceable signal — a pipeline operator could then assert "no lines with anomalous reading order entered the chunk index" rather than discovering six months later that a corpus of mixed-source documents was silently misordered.