Table Cell Text Matching#

Overview#

After TableFormer predicts a table grid, Docling must assign raw text extracted from the PDF page into each predicted cell. This assignment is done via bounding-box overlap thresholds — a purely geometric mechanism with no typographic awareness, no user-configurable parameters, and no observability when text fails to match.

There are two distinct code paths depending on which model version is active:

• TableFormer V1 (table_structure_model.py) — delegates to TFPredictor.multi_table_predict(do_matching=True) from docling-ibm-models. When do_matching=False, the fallback is page._backend.get_text_in_rect(bbox).
• TableFormer V2 (table_structure_model_v2.py) — implements matching inline via _match_text().

The Overlap Thresholds#

V2: _match_text() — hardcoded at 0.3#

_match_text() iterates every TextCell from the layout cluster and accepts it into a predicted cell if:

intersection_over_self(text_cell_bbox, predicted_cell_bbox) > 0.3

The textcell_overlap=0.3 parameter appears in the _do_prediction_on_image_to_table signature 1 and is passed directly when called from predict_tables 2. It is not exposed in any public options class — there is no field for it in TableStructureV2Options 3.

A known defect is documented inline 4: text cells can be assigned to multiple predicted cells — the first match wins, and a cell is not marked as consumed, leading to possible duplication or misassignment in adjacent cells.

get_text_in_rect() — hardcoded at 0.5#

The fallback path in both models calls get_text_in_rect() on the page backend. This method independently applies intersection_over_self > 0.5 against textline_cells 5. This threshold is also hardcoded with no exposure in any options class.

V1: do_matching in TFPredictor#

V1 passes tokens (PDF word-cells scaled to 2×) to TFPredictor.multi_table_predict(do_matching=self.do_cell_matching) 6. The matching logic itself lives in docling-ibm-models/tableformer/data_management/matching_post_processor.py, not in the Docling repo.

Configurable Surface: do_cell_matching#

The only user-accessible control is do_cell_matching: bool = True, present in both:

• TableStructureOptions (V1) 7
• TableStructureV2Options (V2) 8

Setting do_cell_matching=False bypasses the overlap matching entirely and falls back to get_text_in_rect() for every cell. The inline comment warns this can break output when PDF cells span multiple table columns 9. Empirically, disabling it is worse on most corpora 10.

There is no option to adjust the threshold value.

Silent Data Loss#

When a PDF text cell falls below the overlap threshold for every predicted grid cell, it is silently dropped. No warning is emitted, no counter is incremented, and the cell does not appear in table_cells. Because the layout postprocessor has already transferred the text cluster into the TABLE cluster's children (removing it from regular_clusters), the dropped text also does not appear in body.children or markdown output.

Failure modes by cause#

The containment mechanism#

LayoutPostprocessor._process_special_clusters removes text clusters that overlap a TABLE bbox by >80% from regular_clusters and transfers them to the TABLE's children 11. Once inside the TABLE cluster, the text has only one exit route: the TableFormer grid. If the grid does not absorb it, the text is lost.

V1's _pick_orphan_cells() gap#

In docling-ibm-models, MatchingPostProcessor._pick_orphan_cells() attempts to rescue orphan PDF cells — but only when the cell falls inside both a row band and a column band of the predicted grid. A cell that matches no band is discarded silently 10. PR #159 in docling-ibm-models addresses the "row-band-match but no column-band" case; the no-band-at-all case remains open.

Known Proposals & Workarounds#

For formula-bearing table cells specifically, the plain-text fallback is unrecoverable for cells with Private Use Area (PUA) font glyphs; a proposed do_table_cell_formula_enrichment opt-in stage is under discussion 13.

Key Files#