Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

Fix: attach figure captions by adjacency, not nearest figure centre (#21448)

CCLUCKY572eb775e249
diff --git a/internal/deepdoc/parser/pdf/table/merge_captions.go b/internal/deepdoc/parser/pdf/table/merge_captions.go
index f4264aa8b9..b24f362461 100644
--- a/internal/deepdoc/parser/pdf/table/merge_captions.go
+++ b/internal/deepdoc/parser/pdf/table/merge_captions.go
@@ -62,7 +62,7 @@ func MergeCaptions(sections []pdf.Section) []pdf.Section {
// classified there. Without this skip, CaptionKind's text patterns would
// classify a figure whose embedded text starts with a caption marker
// (图1 …, Figure 1: …) as its own caption, and findNearestParent would
- // match it to ITSELF (CollectFigures includes it — center distance 0) —
+ // match it to ITSELF (CollectFigures includes it — distance 0) —
// the figure would become its own merge target and be removed with the
// caption, deleting the image from the output (go_bug
// figure-self-caption-deleted).
@@ -132,10 +132,46 @@ func MergeCaptions(sections []pdf.Section) []pdf.Section {
return out
}
-// maxCaptionGap is the squared centre distance (PDF points²) beyond which a
-// caption is not attached to a candidate parent: 40000 — about 200pt (~7cm).
+// maxCaptionGap is the squared gap (PDF points²) beyond which a figure caption
+// is not attached to a candidate parent: 40000 — about 200pt at zero horizontal
+// offset. See captionGapDistance for how the gap is measured.
const maxCaptionGap = 40000.0
+// captionGapDistance returns the squared gap between a caption box and a
+// candidate parent: the vertical gap between the two boxes (0 when their Y
+// bands overlap) plus the horizontal offset between their centres. It also
+// returns that vertical gap, which callers use as the adjacency signal on its
+// own.
+//
+// The vertical part is edge-to-edge because a parent's CENTRE says nothing
+// about adjacency: a caption just above a 69pt diagram is 12pt from that
+// diagram's edge but further from its centre than from the centre of a short
+// equation on the other side of the caption (go_bug
+// diagram-caption-attached-to-equation, issue #21389), and a caption above a
+// tall cross-page table is hundreds of points from the table's centre while
+// touching its edge (go_bug tall-table-caption-dropped). The horizontal part
+// compares centres so that a narrow caption above a wide table is ranked by
+// how far it is from the table's middle, not punished twice for the table's
+// width.
+//
+// Equation identity is not available here: DLA maps equations to
+// LayoutTypeFigure and Section drops the "equation-N" LayoutNo, so adjacency
+// is the only signal this layer can rank on. That is enough for the reported
+// case (a caption between its diagram and an equation), but a caption placed
+// nearer the equation than its own diagram will still attach to the equation.
+func captionGapDistance(caption, target pdf.Position) (dist, gapY float64) {
+ if caption.Bottom <= target.Top {
+ gapY = target.Top - caption.Bottom
+ } else if caption.Top >= target.Bottom {
+ gapY = caption.Top - target.Bottom
+ }
+ dx := (target.Left+target.Right)/2 - (caption.Left+caption.Right)/2
+ if dx < 0 {
+ dx = -dx
+ }
+ return gapY*gapY + dx*dx, gapY
+}
+
// occupiesPage reports whether a section's recorded positions place it on
// `page`, and whether the section carries page metadata at all. Page-local
// coordinates repeat on every page (every page has a caption band at roughly
@@ -161,8 +197,8 @@ func occupiesPage(s pdf.Section, page int) (onPage, hasPages bool) {
}
// nearestFigureIn returns the index in `sections` of the figure closest to
-// caption by page-local centre distance, or -1 when none is within
-// maxCaptionGap.
+// caption by page-local gap (see captionGapDistance), or -1 when none is
+// within maxCaptionGap.
//
// Candidates are read straight off `sections` and the section index is tracked
// directly. A position box is NOT a figure's identity: page-local coordinates
@@ -172,7 +208,7 @@ func occupiesPage(s pdf.Section, page int) (onPage, hasPages bool) {
//
// requirePage restricts candidates to figures that occupy the caption's page.
// Without it the search is page-blind, and the nearest figure by page-local
-// centre is usually on a DIFFERENT page. A figure with no page metadata stays a
+// gap is usually on a DIFFERENT page. A figure with no page metadata stays a
// candidate in both modes, so a caller that must not lose text (the
// table-caption fallback) cannot be defeated by missing metadata — see
// occupiesPage.
@@ -187,8 +223,6 @@ func nearestFigureIn(sections []pdf.Section, caption pdf.Section, requirePage bo
}
}
cp := caption.Positions[0]
- ccx := (cp.Left + cp.Right) / 2
- ccy := (cp.Top + cp.Bottom) / 2
// Candidates are ranked in two tiers so a figure recorded on the caption's
// own page always beats a page-less one: tier 0 is occupied-by-capPage,
@@ -213,10 +247,7 @@ func nearestFigureIn(sections []pdf.Section, caption pdf.Section, requirePage bo
continue
}
}
- tp := t.Positions[0]
- cx := (tp.Left + tp.Right) / 2
- cy := (tp.Top + tp.Bottom) / 2
- dist := (cx-ccx)*(cx-ccx) + (cy-ccy)*(cy-ccy)
+ dist, _ := captionGapDistance(cp, t.Positions[0])
if tier < bestTier || (tier == bestTier && dist < bestDist) {
bestTier, bestDist, bestIdx = tier, dist, i
}
@@ -237,23 +268,18 @@ func nearestFigureIn(sections []pdf.Section, caption pdf.Section, requirePage bo
// figure instead of being dropped. Returns the index in `sections`, or -1
// when no parent is in range.
func findNearestParent(caption pdf.Section, sections []pdf.Section, captionType string) int {
- // maxCaptionVGap is the vertical band within which a caption attaches to a
- // table regardless of its horizontal offset. A narrow caption (e.g. a short
- // Chinese label) sitting directly above a much wider table has a large dx to
- // the table's center; dx² alone can exceed maxCaptionGap and wrongly reject
- // the match, dropping a legitimate caption. Vertical adjacency (small gapY)
- // is the primary signal that the caption belongs to that table; dx only
- // discriminates between candidate tables, which findTables already resolves
- // via min-distance. Keep this in line with the vertical tolerance implied by
- // maxCaptionGap when dx≈0 (~200pt).
+ // maxCaptionVGap is the vertical gap within which a table caption attaches
+ // regardless of its horizontal offset: vertical adjacency is the signal
+ // that the caption belongs to that table, and dx only ranks candidates
+ // within the band. A narrow caption (e.g. a short Chinese label) above a
+ // much wider table has a large centre offset; rejecting it on the combined
+ // distance would drop a legitimate caption. The figure search below has no
+ // such offset escape — but it needs none: an unattached figure caption
+ // stays a standalone section, so it is never lost. 200pt matches the
+ // vertical tolerance maxCaptionGap allows at dx≈0.
const maxCaptionVGap = 200.0
if captionType == pdf.LayoutTypeTable {
- idx, dist, gapY := findTables(sections, caption)
- // Attach a vertically-adjacent caption even when it is horizontally
- // offset from the (often much wider) table's center. See
- // maxCaptionVGap for the rationale (narrow captions above wide
- // tables, e.g. icbccs '请求参数').
- if idx >= 0 && (dist < maxCaptionGap || gapY <= maxCaptionVGap) {
+ if idx := findTables(sections, caption, maxCaptionVGap); idx >= 0 {
return idx
}
// No table in range: fall through to the figure search below —
@@ -262,8 +288,8 @@ func findNearestParent(caption pdf.Section, sections []pdf.Section, captionType
}
// Two-pass figure search (see nearestFigureIn). Page-local coordinates
// repeat on every page, so proximity alone picks a figure on the wrong
- // page: Figure 1's caption on page 0, page-local centre (415,474), matched
- // a formula figure on page 13 at (417,480) — dist²=45, ~7pt.
+ // page: Figure 1's caption on page 0 and a formula figure on page 13
+ // carried page-local boxes within a few points of each other.
//
// A genuine FIGURE caption is restricted to its own page: when no figure
// shares that page it stays a standalone section, which MergeCaptions keeps
@@ -283,29 +309,30 @@ func findNearestParent(caption pdf.Section, sections []pdf.Section, captionType
return -1
}
-// findTables returns the nearest section whose LayoutType is table, by
-// distance from the caption to the table's NEAREST EDGE (top/bottom) plus
-// horizontal center offset. Restricting to table sections (not all sections)
-// prevents a caption sitting in the left margin — far from the table's
-// horizontal center — from matching a nearer non-table section (e.g. another
-// caption) and being wrongly dropped.
+// findTables returns the nearest table section within maxGapY of the caption's
+// vertical edge. Restricting to table sections (not all sections) prevents a
+// caption sitting in the left margin — far from the table's horizontal centre —
+// from matching a nearer non-table section (e.g. another caption) and being
+// wrongly dropped. The vertical limit is applied BEFORE ranking: a table
+// beyond it must not win the ranking and then be rejected, because an eligible
+// table further away in the combined metric would never be considered. Gap
+// alone gates tables (any horizontal offset is allowed), so ranking then only
+// breaks ties between tables that are all in range.
//
-// The distance is edge-based, NOT center-based: a cross-page table is one tall
-// merged section, so its CENTER is far from a caption sitting just above/below
-// it — center-distance exceeded maxCaptionGap and the caption was dropped
-// (real content loss, e.g. 13's 'Extended Financial Report' / 14's 'Table 1:
-// Revenue'). A caption just above the table (gap to its top) or just below
-// (gap to its bottom) has a small edge distance and attaches; one that
-// vertically overlaps the table has gap 0.
-func findTables(sections []pdf.Section, caption pdf.Section) (int, float64, float64) {
+// Ranking uses captionGapDistance, whose vertical part is edge-based: a
+// cross-page table is one tall merged section, so its CENTRE is far from a
+// caption sitting just above/below it — centre distance exceeded
+// maxCaptionGap and the caption was dropped (real content loss, e.g. 13's
+// 'Extended Financial Report' / 14's 'Table 1: Revenue'). A caption just above
+// the table (gap to its top) or just below (gap to its bottom) has a small
+// edge gap and attaches; one that vertically overlaps the table has gap 0.
+func findTables(sections []pdf.Section, caption pdf.Section, maxGapY float64) int {
bestIdx := -1
bestDist := 1e9
- bestGapY := 0.0
if len(caption.Positions) == 0 {
- return bestIdx, bestDist, bestGapY
+ return bestIdx
}
cp := caption.Positions[0]
- ccx := (cp.Left + cp.Right) / 2
// Page-scope guard: a caption attaches to a table only on its OWN page (a
// table whose page set includes the caption's page — a genuine cross-page
// merged table carries multiple Position entries, one per spanned page, so
@@ -329,15 +356,6 @@ func findTables(sections []pdf.Section, caption pdf.Section) (int, float64, floa
continue
}
tp := t.Positions[0]
- // Vertical gap to the table's nearest edge. A caption fully above the
- // table measures the gap to the top; fully below, to the bottom;
- // vertically overlapping the table, the gap is 0.
- gapY := 0.0
- if cp.Bottom <= tp.Top {
- gapY = tp.Top - cp.Bottom
- } else if cp.Top >= tp.Bottom {
- gapY = cp.Top - tp.Bottom
- }
if capKnown {
// Page-scope guard: a caption attaches to a table only on a page
// the table actually occupies. A genuine cross-page MERGED table
@@ -356,19 +374,16 @@ func findTables(sections []pdf.Section, caption pdf.Section) (int, float64, floa
continue
}
}
- // Horizontal center offset: a caption far to the side ranks worse.
- dx := (tp.Left+tp.Right)/2 - ccx
- if dx < 0 {
- dx = -dx
+ dist, gapY := captionGapDistance(cp, tp)
+ if gapY > maxGapY {
+ continue
}
- dist := gapY*gapY + dx*dx
if dist < bestDist {
bestDist = dist
- bestGapY = gapY
bestIdx = i
}
}
- return bestIdx, bestDist, bestGapY
+ return bestIdx
}
// appendRawCaptions concatenates caption texts onto a non-table section
diff --git a/internal/deepdoc/parser/pdf/table/merge_captions_caption_test.go b/internal/deepdoc/parser/pdf/table/merge_captions_caption_test.go
index 12a9c51189..3b3aba8ede 100644
--- a/internal/deepdoc/parser/pdf/table/merge_captions_caption_test.go
+++ b/internal/deepdoc/parser/pdf/table/merge_captions_caption_test.go
@@ -183,6 +183,40 @@ func TestMergeCaptions_TallTableCaptionNearEdgeAttaches(t *testing.T) {
}
}
+// TestMergeCaptions_FarTableDoesNotOutrankEligibleTable locks the vertical
+// limit as a pre-filter. Ranking alone can hand the caption to a table just
+// past maxCaptionVGap (its combined distance is smaller because dx is tiny),
+// and the attachment predicate then rejects the whole search — although a
+// touching table with a large centre offset is in range. Distance: far table
+// 201pt gap + 16pt dx ≈ 40657; wide table 0pt gap + 266pt dx ≈ 70756.
+func TestMergeCaptions_FarTableDoesNotOutrankEligibleTable(t *testing.T) {
+ far := pdf.Section{
+ Text: "<table><tr><td>far</td></tr></table>", LayoutType: pdf.LayoutTypeTable,
+ Positions: []pdf.Position{{PageNumbers: []int{0}, Left: 300, Right: 400, Top: 427, Bottom: 500}}}
+ wide := pdf.Section{
+ Text: "<table><tr><td>wide</td></tr></table>", LayoutType: pdf.LayoutTypeTable,
+ Positions: []pdf.Position{{PageNumbers: []int{0}, Left: 200, Right: 1000, Top: 226, Bottom: 300}}}
+ caption := pdf.Section{
+ Text: "Table 2: Wide", LayoutType: pdf.DLALabelTableCaption,
+ Positions: []pdf.Position{{PageNumbers: []int{0}, Left: 280, Right: 388, Top: 213, Bottom: 226}}}
+ result := MergeCaptions([]pdf.Section{far, wide, caption})
+ if len(result) != 2 {
+ t.Fatalf("expected 2 sections (two tables, caption consumed), got %d: %v", len(result), textsOf(result))
+ }
+ attached := false
+ for _, s := range result {
+ if strings.Contains(s.Text, "<caption>Table 2: Wide</caption>") {
+ attached = true
+ if !strings.Contains(s.Text, "wide") || strings.Contains(s.Text, "far") {
+ t.Errorf("caption attached to the wrong table: %q", s.Text)
+ }
+ }
+ }
+ if !attached {
+ t.Errorf("caption dropped because the out-of-range table won the ranking: %v", textsOf(result))
+ }
+}
+
// TestMergeCaptions_CaptionOtherPageDoesNotAttach locks the page-scope guard:
// a caption clearly ABOVE or BELOW a table's Y band on a DIFFERENT page must
// NOT attach. The edge-distance alone is page-local-coordinate blind — a
@@ -583,9 +617,9 @@ func TestMergeCaptions_ProperNounCrossReferenceLandsInCaption(t *testing.T) {
// TestMergeCaptions_FigureCaptionOtherPageDoesNotAttach locks the figure-side
// page-scope guard (go_bug figure-caption-cross-page-attached). Page-local
// coordinates repeat on every page, so the figure search used to match on
-// page-local distance alone: here the page-2 caption's page-local centre is
-// CLOSER to the page-0 figure (dist²=13225) than to the page-2 figure it
-// belongs to (dist²=21025). The caption was therefore glued to the page-0
+// page-local gap alone: here the page-2 caption's page-local box is CLOSER to
+// the page-0 figure (50pt gap) than to the page-2 figure it belongs to (80pt
+// gap). The caption was therefore glued to the page-0
// figure — pages away — and its own figure was left with no caption at all.
func TestMergeCaptions_FigureCaptionOtherPageDoesNotAttach(t *testing.T) {
sections := []pdf.Section{
@@ -762,8 +796,8 @@ func TestMergeCaptions_IdenticalBoxOtherPageNotChosen(t *testing.T) {
func TestMergeCaptions_SamePageFigureBeatsPageLessNearer(t *testing.T) {
sections := []pdf.Section{
// page-less figure, much CLOSER to the caption than the same-page one:
- // dist² 56 against the same-page figure's 6006, so distance alone would
- // pick it.
+ // it overlaps the caption's Y band (edge gap 0) against the same-page
+ // figure's 20pt, so distance alone would pick it.
{Text: "page-less chart", LayoutType: pdf.LayoutTypeFigure, Image: "np",
Positions: []pdf.Position{{Left: 100, Right: 400, Top: 500, Bottom: 540}}},
{Text: "same-page chart", LayoutType: pdf.LayoutTypeFigure, Image: "sp",
diff --git a/internal/deepdoc/parser/pdf/table/merge_captions_figure_distance_test.go b/internal/deepdoc/parser/pdf/table/merge_captions_figure_distance_test.go
new file mode 100644
index 0000000000..66291d26ac
--- /dev/null
+++ b/internal/deepdoc/parser/pdf/table/merge_captions_figure_distance_test.go
@@ -0,0 +1,92 @@
+package table
+
+import (
+ "strings"
+ "testing"
+
+ pdf "ragflow/internal/deepdoc/parser/pdf/type"
+)
+
+func figureSection(text string, left, right, top, bottom float64) pdf.Section {
+ return pdf.Section{
+ Text: text, LayoutType: pdf.LayoutTypeFigure, Image: "img",
+ Positions: []pdf.Position{{PageNumbers: []int{10}, Left: left, Right: right, Top: top, Bottom: bottom}},
+ }
+}
+
+// TestMergeCaptions_FigureCaptionAttachesToAdjacentDiagram locks issue #21389:
+// a diagram caption sits BETWEEN the diagram above it (12pt above the
+// caption) and an equation below it (31pt below). Both are figure media, and
+// the equation is shorter, so its CENTRE is nearer to the caption's centre than
+// the taller diagram's centre is — centre distance handed the caption to the
+// equation. Adjacency is the real signal: the caption belongs to the diagram it
+// is vertically closest to.
+func TestMergeCaptions_FigureCaptionAttachesToAdjacentDiagram(t *testing.T) {
+ sections := []pdf.Section{
+ figureSection("Bus diagram", 260, 420, 132, 201),
+ figureSection("Rp(min) = ...", 279, 399, 257, 283),
+ {Text: "Figure 12. I2C bus", LayoutType: pdf.DLALabelFigureCaption,
+ Positions: []pdf.Position{{PageNumbers: []int{10}, Left: 280, Right: 388, Top: 213, Bottom: 226}}},
+ }
+ result := MergeCaptions(sections)
+
+ diagram, equation := -1, -1
+ for i, s := range result {
+ switch {
+ case strings.Contains(s.Text, "Bus diagram"):
+ diagram = i
+ case strings.Contains(s.Text, "Rp(min)"):
+ equation = i
+ }
+ }
+ if diagram < 0 || equation < 0 {
+ t.Fatalf("figure sections lost; got %v", textsOf(result))
+ }
+ if !strings.Contains(result[diagram].Text, "Figure 12. I2C bus") {
+ t.Errorf("caption did not attach to the adjacent diagram: %q", result[diagram].Text)
+ }
+ if strings.Contains(result[equation].Text, "Figure 12.") {
+ t.Errorf("caption wrongly attached to the equation below it: %q", result[equation].Text)
+ }
+}
+
+// TestMergeCaptions_TallFigureCaptionNearEdgeAttaches pins the metric itself:
+// a caption 120pt above a 400pt-tall figure is 327.5pt from its CENTRE (beyond
+// maxCaptionGap) but only 120pt from its top EDGE, so it must still attach —
+// the same tall-parent case findTables already handles for cross-page tables.
+func TestMergeCaptions_TallFigureCaptionNearEdgeAttaches(t *testing.T) {
+ sections := []pdf.Section{
+ figureSection("tall chart", 100, 400, 300, 700),
+ {Text: "Figure 6: tall chart", LayoutType: pdf.DLALabelFigureCaption,
+ Positions: []pdf.Position{{PageNumbers: []int{10}, Left: 100, Right: 400, Top: 165, Bottom: 180}}},
+ }
+ result := MergeCaptions(sections)
+
+ if len(result) != 1 {
+ t.Fatalf("expected 1 section (figure with caption), got %d: %v", len(result), textsOf(result))
+ }
+ if !strings.Contains(result[0].Text, "Figure 6: tall chart") {
+ t.Errorf("caption near a tall figure's edge was dropped: %q", result[0].Text)
+ }
+}
+
+// TestMergeCaptions_DistantFigureCaptionStaysStandalone bounds the tolerance in
+// the other direction: a caption 201pt from every figure's edge is outside
+// maxCaptionGap and must not be glued to a figure it does not belong to. The
+// caption section survives on its own — an unattached figure caption is kept,
+// not dropped.
+func TestMergeCaptions_DistantFigureCaptionStaysStandalone(t *testing.T) {
+ sections := []pdf.Section{
+ figureSection("unrelated chart", 100, 400, 300, 400),
+ {Text: "Figure 7: somewhere else", LayoutType: pdf.DLALabelFigureCaption,
+ Positions: []pdf.Position{{PageNumbers: []int{10}, Left: 100, Right: 400, Top: 601, Bottom: 617}}},
+ }
+ result := MergeCaptions(sections)
+
+ if len(result) != 2 {
+ t.Fatalf("caption outside maxCaptionGap must stay standalone, got %d sections: %v", len(result), textsOf(result))
+ }
+ if strings.Contains(result[0].Text, "Figure 7") {
+ t.Errorf("distant caption was glued to the figure: %q", result[0].Text)
+ }
+}