Skip to content

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

fix(deepdoc): keep native PDF text when OCR detection misses it (#21399)

jay777211b8ab33c2c90
diff --git a/internal/deepdoc/parser/pdf/layout/chars_boxes.go b/internal/deepdoc/parser/pdf/layout/chars_boxes.go
index 29cdb0fc04..7607498893 100644
--- a/internal/deepdoc/parser/pdf/layout/chars_boxes.go
+++ b/internal/deepdoc/parser/pdf/layout/chars_boxes.go
@@ -37,6 +37,11 @@ func CharsToBoxes(chars []pdf.TextChar, pageNum int, sortByTop bool) []pdf.TextB
boxes := make([]pdf.TextBox, 0, len(lines))
for _, line := range lines {
+ // GroupCharsToLines sorts by Bottom (or Top), so a raised superscript
+ // arrives before the base line and LineToTextBox would prepend it
+ // ("2I C" instead of "I2C"). Re-order each line X-first within fuzzy Y
+ // bands before assembling text and splitting columns.
+ sortLineByXY(line)
thr := threshold
if thr > 100 {
// No significant column gaps on this page → use per-line threshold.
@@ -53,6 +58,49 @@ func CharsToBoxes(chars []pdf.TextChar, pageNum int, sortByTop bool) []pdf.TextB
return boxes
}
+// sortLineByXY orders one line's glyphs by X inside fuzzy Y bands (half the
+// median glyph height), falling back to Y across clearly different baselines.
+// Superscripts/subscripts stay at their text position instead of sorting to
+// the start of the line.
+//
+// Bands are assigned before sorting: a pairwise |Top difference| comparator is
+// not transitive (Top 0/4/8 with band 5 forms a cycle), and sort.SliceStable
+// requires a strict weak ordering.
+func sortLineByXY(chars []pdf.TextChar) {
+ if len(chars) < 2 {
+ return
+ }
+ band := util.MedianCharHeight(chars) * 0.5
+ if band <= 0 {
+ return
+ }
+ type glyph struct {
+ char pdf.TextChar
+ band int
+ }
+ glyphs := make([]glyph, len(chars))
+ for i, c := range chars {
+ glyphs[i] = glyph{char: c}
+ }
+ sort.SliceStable(glyphs, func(i, j int) bool { return glyphs[i].char.Top < glyphs[j].char.Top })
+ bandIdx := 0
+ for i := 1; i < len(glyphs); i++ {
+ if math.Abs(glyphs[i].char.Top-glyphs[i-1].char.Top) >= band {
+ bandIdx++
+ }
+ glyphs[i].band = bandIdx
+ }
+ sort.SliceStable(glyphs, func(i, j int) bool {
+ if glyphs[i].band != glyphs[j].band {
+ return glyphs[i].band < glyphs[j].band
+ }
+ return glyphs[i].char.X0 < glyphs[j].char.X0
+ })
+ for i := range chars {
+ chars[i] = glyphs[i].char
+ }
+}
+
// perLineXGapThreshold computes a dynamic X-gap threshold for column
// splitting within a single line (fallback when page has few gaps).
func perLineXGapThreshold(chars []pdf.TextChar) float64 {
diff --git a/internal/deepdoc/parser/pdf/layout/chars_boxes_test.go b/internal/deepdoc/parser/pdf/layout/chars_boxes_test.go
index dd0059c3fb..02c39f0b4b 100644
--- a/internal/deepdoc/parser/pdf/layout/chars_boxes_test.go
+++ b/internal/deepdoc/parser/pdf/layout/chars_boxes_test.go
@@ -145,3 +145,41 @@ func TestLineToTextBox(t *testing.T) {
}
})
}
+
+// TestCharsToBoxesKeepsSuperscriptInPlace pins the X-first ordering inside a
+// fuzzy Y band. GroupCharsToLines sorts by Bottom, so a raised superscript
+// arrives before the base line; without the re-order it is emitted at the
+// start of the line ("2I C" instead of "I2C").
+func TestCharsToBoxesKeepsSuperscriptInPlace(t *testing.T) {
+ chars := []pdf.TextChar{
+ {X0: 8, X1: 13, Top: 0, Bottom: 10, Text: "C", PageNumber: 0},
+ {X0: 5, X1: 8, Top: -3, Bottom: 2, Text: "2", PageNumber: 0}, // superscript
+ {X0: 0, X1: 5, Top: 0, Bottom: 10, Text: "I", PageNumber: 0},
+ }
+ boxes := CharsToBoxes(chars, 0, false)
+ if len(boxes) != 1 {
+ t.Fatalf("boxes = %d, want 1", len(boxes))
+ }
+ if boxes[0].Text != "I2C" {
+ t.Fatalf("Text = %q, want 'I2C' (superscript stays between I and C)", boxes[0].Text)
+ }
+}
+
+// TestCharsToBoxesOrdersChainedBaselinesTransitively pins a strict weak
+// ordering. A pairwise |Top difference| comparator cycles for Top 0/4/8 with
+// band 5 (0<4, 4<8, but 8 is not within 5 of 0), which sort.SliceStable does
+// not permit; bands are assigned before sorting instead.
+func TestCharsToBoxesOrdersChainedBaselinesTransitively(t *testing.T) {
+ chars := []pdf.TextChar{
+ {X0: 10, X1: 15, Top: 0, Bottom: 10, Text: "A", PageNumber: 0},
+ {X0: 5, X1: 10, Top: 4, Bottom: 14, Text: "B", PageNumber: 0},
+ {X0: 0, X1: 5, Top: 8, Bottom: 18, Text: "C", PageNumber: 0},
+ }
+ boxes := CharsToBoxes(chars, 0, false)
+ if len(boxes) != 1 {
+ t.Fatalf("boxes = %d, want 1", len(boxes))
+ }
+ if boxes[0].Text != "CBA" {
+ t.Fatalf("Text = %q, want 'CBA' (one chained band in X order)", boxes[0].Text)
+ }
+}
diff --git a/internal/deepdoc/parser/pdf/native_text_test.go b/internal/deepdoc/parser/pdf/native_text_test.go
new file mode 100644
index 0000000000..b6673fdc93
--- /dev/null
+++ b/internal/deepdoc/parser/pdf/native_text_test.go
@@ -0,0 +1,77 @@
+package pdf
+
+import (
+ "image"
+ "strings"
+ "testing"
+
+ pdf "ragflow/internal/deepdoc/parser/pdf/type"
+)
+
+// TestOCRMergeChars_KeepsUncoveredNativeText pins the fix for the merge path:
+// characters no detect box covers are emitted as native line boxes instead of
+// being dropped. main dropped them, so figure labels and rotated text vanished.
+func TestOCRMergeChars_KeepsUncoveredNativeText(t *testing.T) {
+ p := NewParser(pdf.DefaultParserConfig())
+ page := image.NewRGBA(image.Rect(0, 0, 300, 100))
+ mock := &MockDocAnalyzer{
+ Healthy: true,
+ OCRBoxes: []pdf.OCRBox{{X0: 200, Y0: 60, X1: 260, Y1: 60, X2: 260, Y2: 80, X3: 200, Y3: 80}},
+ OCRTexts: []pdf.OCRText{{Text: "Bitmap", Confidence: 0.9}},
+ }
+ // Two native lines left of every detect box.
+ chars := []pdf.TextChar{
+ {X0: 10, X1: 18, Top: 10, Bottom: 18, Text: "S", PageNumber: 0},
+ {X0: 18, X1: 26, Top: 10, Bottom: 18, Text: "C", PageNumber: 0},
+ {X0: 26, X1: 34, Top: 10, Bottom: 18, Text: "L", PageNumber: 0},
+ {X0: 10, X1: 18, Top: 30, Bottom: 38, Text: "S", PageNumber: 0},
+ {X0: 18, X1: 26, Top: 30, Bottom: 38, Text: "D", PageNumber: 0},
+ {X0: 26, X1: 34, Top: 30, Bottom: 38, Text: "A", PageNumber: 0},
+ }
+ boxes := p.ocrMergeChars(t.Context(), page, chars, mock, 0, 1)
+ var texts []string
+ for _, b := range boxes {
+ texts = append(texts, b.Text)
+ }
+ joined := strings.Join(texts, "|")
+ if !strings.Contains(joined, "SCL") || !strings.Contains(joined, "SDA") || !strings.Contains(joined, "Bitmap") {
+ t.Fatalf("boxes = %q, want native SCL/SDA plus OCR Bitmap", joined)
+ }
+}
+
+// TestOCRMergeChars_AssemblesFormulaInOneBox pins the box granularity: glyphs
+// on different baselines inside one detect box are assembled into that box
+// (main's behavior) instead of being split into per-line boxes, which used to
+// shred formulas into "( − ( ))", "VDD", "VOL", "max".
+func TestOCRMergeChars_AssemblesFormulaInOneBox(t *testing.T) {
+ p := NewParser(pdf.DefaultParserConfig())
+ page := image.NewRGBA(image.Rect(0, 0, 200, 60))
+ mock := &MockDocAnalyzer{
+ Healthy: true,
+ OCRBoxes: []pdf.OCRBox{{X0: 0, Y0: 0, X1: 150, Y1: 0, X2: 150, Y2: 20, X3: 0, Y3: 20}},
+ OCRTexts: []pdf.OCRText{{Text: "OCR", Confidence: 0.9}},
+ }
+ // Base glyphs plus a raised "max" (smaller, higher baseline) in one box.
+ chars := []pdf.TextChar{
+ {X0: 0, X1: 10, Top: 2, Bottom: 12, Text: "V", PageNumber: 0},
+ {X0: 10, X1: 20, Top: 2, Bottom: 12, Text: "D", PageNumber: 0},
+ {X0: 20, X1: 30, Top: 2, Bottom: 12, Text: "D", PageNumber: 0},
+ {X0: 30, X1: 40, Top: 4, Bottom: 12, Text: "V", PageNumber: 0},
+ {X0: 40, X1: 50, Top: 4, Bottom: 12, Text: "O", PageNumber: 0},
+ {X0: 50, X1: 60, Top: 4, Bottom: 12, Text: "L", PageNumber: 0},
+ {X0: 60, X1: 65, Top: 0, Bottom: 6, Text: "m", PageNumber: 0},
+ {X0: 65, X1: 70, Top: 0, Bottom: 6, Text: "a", PageNumber: 0},
+ {X0: 70, X1: 75, Top: 0, Bottom: 6, Text: "x", PageNumber: 0},
+ }
+ boxes := p.ocrMergeChars(t.Context(), page, chars, mock, 0, 1)
+ if len(boxes) != 1 {
+ t.Fatalf("boxes = %d, want one assembled formula box: %+v", len(boxes), boxes)
+ }
+ text := boxes[0].Text
+ posVDD := strings.Index(text, "VDD")
+ posVOL := strings.Index(text, "VOL")
+ posMAX := strings.Index(text, "max")
+ if posVDD < 0 || posVOL < 0 || posMAX < 0 || !(posVDD < posVOL && posVOL < posMAX) {
+ t.Fatalf("assembled text = %q, want VDD before VOL before max", text)
+ }
+}
diff --git a/internal/deepdoc/parser/pdf/parser_ocr.go b/internal/deepdoc/parser/pdf/parser_ocr.go
index 456d2e9cdd..4701d7314a 100644
--- a/internal/deepdoc/parser/pdf/parser_ocr.go
+++ b/internal/deepdoc/parser/pdf/parser_ocr.go
@@ -339,7 +339,62 @@ func (p *Parser) ocrMergeChars(ctx context.Context, pageImg image.Image, chars [
return nil
}
boxChars := matchCharsToBoxes(boxes, chars)
- return p.buildTextBoxes(ctx, pageImg, boxes, boxChars, doc, scale, pageNum)
+ result := p.buildTextBoxes(ctx, pageImg, boxes, boxChars, doc, scale, pageNum)
+
+ // Detection must not decide which native text survives: chars outside
+ // every detect box are emitted as native line boxes. Main dropped them.
+ if uncovered := charsOutsideDetectBoxes(chars, boxes); len(uncovered) > 0 {
+ result = append(result, lyt.CharsToBoxes(uncovered, pageNum, p.Config.SortByTop)...)
+ }
+
+ // Interleave native and uncovered boxes for TextMerge's left-to-right pass
+ // (FinalReadingOrderMerge re-sorts by Top afterwards).
+ sort.SliceStable(result, func(i, j int) bool {
+ if result[i].Top != result[j].Top {
+ return result[i].Top < result[j].Top
+ }
+ return result[i].X0 < result[j].X0
+ })
+ return result
+}
+
+// charsOutsideDetectBoxes returns the usable glyphs no detect box overlaps.
+// These are the characters main's merge path silently dropped when detection
+// missed their region (figure labels, marginalia, rotated text).
+func charsOutsideDetectBoxes(chars []pdf.TextChar, boxes []ocrDetectBox) []pdf.TextChar {
+ var out []pdf.TextChar
+ for _, c := range chars {
+ if strings.TrimSpace(c.Text) == "" || !usableNativeChar(c) {
+ continue
+ }
+ covered := false
+ for i := range boxes {
+ // Match matchCharsToBoxes' assignment threshold: a glyph it would
+ // not assign (overlap < 1e-6) must not be treated as covered here,
+ // or it would be consumed by neither path.
+ if charBoxOverlapRatio(c, boxes[i].x0, boxes[i].x1, boxes[i].y0, boxes[i].y1) >= 1e-6 {
+ covered = true
+ break
+ }
+ }
+ if !covered {
+ out = append(out, c)
+ }
+ }
+ return out
+}
+
+// usableNativeChar reports whether a glyph can be emitted as native text:
+// finite, non-degenerate geometry and a mapped (non-PUA/control) glyph.
+func usableNativeChar(c pdf.TextChar) bool {
+ if math.IsNaN(c.X0) || math.IsNaN(c.X1) || math.IsNaN(c.Top) || math.IsNaN(c.Bottom) ||
+ math.IsInf(c.X0, 0) || math.IsInf(c.X1, 0) || math.IsInf(c.Top, 0) || math.IsInf(c.Bottom, 0) {
+ return false
+ }
+ if c.X0 >= c.X1 || c.Top >= c.Bottom {
+ return false
+ }
+ return !util.IsGarbledChar(c.Text)
}
// ocrCoordinateScale returns the factor that converts image pixels into PDF
diff --git a/internal/deepdoc/parser/pdf/parser_test.go b/internal/deepdoc/parser/pdf/parser_test.go
index 6b72953107..e8a2c0a184 100644
--- a/internal/deepdoc/parser/pdf/parser_test.go
+++ b/internal/deepdoc/parser/pdf/parser_test.go
@@ -316,11 +316,13 @@ func TestOCR_MergeChars(t *testing.T) {
}
chars := []pdf.TextChar{{X0: 10, X1: 20, Top: 10, Bottom: 20, Text: "A", PageNumber: 0}}
boxes := p.ocrMergeChars(t.Context(), dummyImg, chars, mock, 0, pdf.DlaScale)
- if len(boxes) != 1 {
- t.Fatalf("expected 1 box (OCR), got %d", len(boxes))
+ // The OCR box is filled from the image; the native char no detect box
+ // covers is kept (detection must not drop native text).
+ if len(boxes) != 2 {
+ t.Fatalf("expected 2 boxes (OCR + uncovered native), got %d", len(boxes))
}
- if boxes[0].Text != "OCR" {
- t.Errorf("expected OCR text 'OCR', got %q", boxes[0].Text)
+ if boxes[0].Text != "A" || boxes[1].Text != "OCR" {
+ t.Errorf("expected native 'A' then OCR 'OCR', got %q,%q", boxes[0].Text, boxes[1].Text)
}
})
@@ -332,8 +334,9 @@ func TestOCR_MergeChars(t *testing.T) {
}
chars := []pdf.TextChar{{X0: 10, X1: 20, Top: 10, Bottom: 20, Text: "A", PageNumber: 0}}
boxes := p.ocrMergeChars(t.Context(), dummyImg, chars, mock, 0, pdf.DlaScale)
- if len(boxes) != 0 {
- t.Fatalf("expected 0 boxes (empty OCR), got %d", len(boxes))
+ // Empty OCR output is dropped; the uncovered native char survives.
+ if len(boxes) != 1 || boxes[0].Text != "A" {
+ t.Fatalf("expected 1 native box 'A', got %+v", boxes)
}
})