Table Structure Parsing#

Table structure parsing in RAGFlow converts raw bounding-box detections from a vision model into a structured HTML table or natural-language sentence list. The pipeline runs through four stages: TSR inference → coordinate alignment → row/column assignment → span/header reconstruction.

The entry point is TableStructureRecognizer in deepdoc/vision/table_structure_recognizer.py, a subclass of Recognizer that classifies regions within a cropped table image into six labels: table, table column, table row, table column header, table projected row header, and table spanning cell.

Coordinate System Alignment#

TSR outputs coordinates relative to the cropped table image; OCR text boxes in self.boxes carry page-cumulative Y coordinates (absolute offsets across all preceding pages). These two spaces must be reconciled before overlap matching 1.

Key mechanics:

• page_cum_height is built in __images__() as a cumulative sum of per-page heights (in PDF-point units at 72 × zoomin DPI) 1.
• OCR boxes are lifted into cumulative space in _layouts_rec() via box["top"] += page_cum_height[page_number - 1] 1.
• TSR components stored in self.tb_cpns retain image-local coordinates — only text boxes are in cumulative space.

⚠️ Active bug (as of 2026-07): find_overlapped_with_threshold is called with text boxes (cumulative space) against TSR row structures (image-local space). Row-index ("R") assignment is only accidentally correct when the table sits near the top of the page where the two coordinate origins nearly coincide. Mid-page tables degrade more gracefully (null R, header span missed) but top-page tables can silently bind cells to the wrong rows 2.

Row, Column, and Spanning Cell Assignment#

_table_transformer_job() orchestrates the assignment:

These tags (R, H, C, SP) written onto each text box drive the downstream construct_table() call.

⚠️ Multi-page/multi-table column identity bug (as of 2026-07): layoutno is assigned per-page via enumerate(tbls), so every page's first table is "table-0". find_horizontally_tightest_fit only checks layoutno without the page number — a text box on page 2's "table-0" can incorrectly match columns from page 1's "table-0" 3. The proposed fix is to also compare page_number vs pn in the matching guard.

After raw TSR output is normalized, rows are aligned left/right and columns are aligned top/bottom using median/mean across detected elements 4.

construct_table(): Row/Column Grid, Span Calculation, and Header Inference#

construct_table() takes tagged text boxes and produces an HTML table or text sentences.

Grid Assembly#

Boxes are sorted by row (sort_R_firstly) then by column (sort_C_firstly for single-page, sort_X_firstly for cross-page tables) 5. Cross-page detection is a simple len(set([b["page_number"] for b in boxes])) > 1 check 6.

Single-value rows or columns (with ≥ 4 rows/columns total) are relocated to the nearest neighbor based on geometric distance, preventing phantom columns or rows from OCR noise 7.

Spanning Cell Calculation (__cal_spans)#

__cal_spans() computes colspan and rowspan for cells tagged "SP":

1. Compute per-column mean left/right bounds (clft, crgt) and per-row mean top/bottom bounds (rtop, rbtm) from the actual cell coordinates.
2. For each spanning-cell box, test every other column: a column j is included in the span if its midpoint falls inside the spanning cell's horizontal extent (H_left…H_right). The same midpoint test applies for rows using H_top…H_bott 8.
3. Convert the collected index lists into contiguous ranges and null-out covered cells in the grid (HTML mode) or aggregate their text (text mode) 9.

Header Inference#

Headers are inferred heuristically in construct_table():

• Content-type majority voting: blockType() classifies each cell as one of Dt (date), Nu (numeric), Ca (code/catalog), En (English), NE (numeric+text), Sg (single char), Tx/Lx (short/long text), Nr (name), or Ot (other) 10. The table's dominant type (max_type) is determined by Counter.
• A row is a header if more than 50% of its cells are either tagged H by TSR or contain non-numeric content in a predominantly numeric table 11.

Multi-Level Header Merging (__desc_table)#

In text (non-HTML) output mode, __desc_table() merges adjacent header rows:

• Missing cell fill: empty header cells are filled from the previous header row's values 12.
• Multi-level concatenation: for consecutive header rows, if headers[j][k] doesn't already contain headers[j-1][k], the two are concatenated with 的 (Chinese) or for (English) as separator, with the shorter string made the prefix 13.

Rotated Table Path#

When TABLE_AUTO_ROTATE=true, _ocr_rotated_tables() evaluates 0°/90°/180°/270° rotations via OCR confidence, then maps coordinates back through three stages: rotated image → original image (via _map_rotated_point()) → page-local (÷ ZM + table offset) → page-cumulative (+ page_cum_height[page_index]) 1.

Key Files#