Layout Element Overlap Detection#

The Recognizer class in deepdoc/vision/recognizer.py provides a suite of static methods for computing and comparing spatial overlap between bounding boxes. These methods are the backbone of RAGFlow's document parsing pipeline, used to match OCR text boxes to layout regions, deduplicate overlapping detections, and align table cells.

All bounding boxes are represented as dicts with keys top, bottom, x0, x1.

Core Method: overlapped_area#

overlapped_area(a, b, ratio=True) computes the intersection area of two boxes. When ratio=True (the default), it returns the intersection divided by box a's own area — making it directional: it answers "what fraction of a is covered by b?"

This asymmetry is intentional. Calling it in both directions (overlapped_area(a, b) and overlapped_area(b, a)) provides a bidirectional overlap check — neither box can be dismissed as non-overlapping just because it is large relative to the other.

Bidirectional Comparison in layouts_cleanup#

layouts_cleanup(boxes, layouts, far=2, thr=0.7) deduplicates layout detections of the same type. For each candidate pair (layouts[i], layouts[j]) within a window of far elements, a match is confirmed only if both directional ratios meet the threshold 1:

overlapped_area(layouts[i], layouts[j]) >= thr
AND
overlapped_area(layouts[j], layouts[i]) >= thr

If the pair is a true duplicate, the method removes the one with the lower confidence score 2, or — if scores are absent — drops the layout that has less total OCR text content overlapping it 3.

Called from:

• layout_recognizer.py line 100 — post-processing detected layouts after model inference (standard backend)
• layout_recognizer.py line 401 — same, for Ascend backend
• pdf_parser.py line 510 — cleans table headers/rows with far=5, thr=0.6
• pdf_parser.py line 518 — cleans table columns with far=5, thr=0.5
• t_recognizer.py lines 61, 68 — same table cleanup in the standalone table HTML generator

Threshold-Gated Matching: find_overlapped_with_threshold#

find_overlapped_with_threshold(box, boxes, thr=0.3) finds the best-matching box from a list using a bidirectional tuple comparison: it selects the boxes[i] that maximizes (overlapped_area(box, boxes[i]), overlapped_area(boxes[i], box)) as a tuple, with both values needing to exceed the initial threshold thr 4. This ensures neither box is a small sliver merely touching the other.

Called from:

• layout_recognizer.py lines 115, 416 — tags OCR boxes with layout type (footer, header, reference, etc.) using thr=0.4
• pdf_parser.py lines 523, 529, 543 — assigns OCR boxes to table rows ("R"), header rows ("H"), and spanning cells ("SP") using thr=0.3
• t_recognizer.py lines 71, 77, 91 — same row/header/span assignments in the table HTML generator with thr=0.3

Fast Lookup: find_overlapped#

find_overlapped(box, boxes_sorted_by_y, naive=False) locates the single highest-overlap candidate in a Y-sorted list. With naive=False (default), it uses binary search to narrow the candidate window before a linear scan 5, making it efficient for large lists. With naive=True, it skips the binary search.

Called from:

• pdf_parser.py line 719 — clusters individual OCR characters into text boxes
• pdf_parser.py line 1338 — matches a bounding box against page layouts for figure/table crop extraction (uses naive=True)

Threshold Reference#

Key Files#