Recover ruled-table cells from drawn column slots

Drive table cell recovery off where columns physically start and end
rather than off text alignment, so fully ruled tables recover reliably.

- Flow each detected table region through XY-cut reading order as a
  placeholder block (like images and lists), then resolve it back to a
  TableElement/RegionElement after classification, fixing paragraph vs
  table ordering without a separate insertion heuristic.
- Add a ruled-slot fallback: when leaf recovery from repeated word
  centres fails the confidence gate, place each word into the x-range
  its centre falls in between drawn vertical separators.
- Merge collinear horizontal rule fragments to one y-level before using
  them as logical-row boundaries, so a rule split at a column gap still
  bounds rows.
- Trim a wide empty left rule overhang off the detected box so a blank
  drawn left margin is not read as a first column (left only; a short
  last column legitimately leaves a wide right gap).
- Split a rule band that stacks several whole records, merge dash-only
  continuation lines into the record above, drop a permanently empty
  leading column, and read a wrapped cell's words top-then-left.

Consolidate the duplicated baseline clustering and stacked-record
splitting from LogicalRowBuilder and TableCellRecovery into a shared
TableRowGrouping helper; the record test stays per-caller as a delegate.
Add XML summaries on the new private members.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Author: diluculo

src/PdfStruct.Tests/LogicalRowBuilderTests.cs

@@ -94,6 +94,29 @@ public void Build_RuledGrid_BandsAreLogicalRowsAcrossWrappedLines()
         Assert.Contains("label", rows[0].Select(w => w.Text));
     }
 
+    [Fact]
+    public void Build_RuledGrid_SplitsMultipleCompleteRecordsInsideOneBand()
+    {
+        // Dense tables may omit the rule between adjacent body rows. If each
+        // baseline opens the row-label column and carries data columns, they are
+        // separate records, not a wrapped cell.
+        var ruleYs = new List<double> { 712, 690, 668, 646 };
+        var words = new List<TableCellRecovery.Word>
+        {
+            W("Alice", 80, 705), W("91", 200, 705),
+            W("Bob", 80, 697), W("82", 200, 697),
+            W("Cara", 80, 679), W("77", 200, 679),
+            W("Dana", 80, 657), W("73", 200, 657),
+        };
+        var region = new BoundingBox(60, 646, 260, 712);
+
+        var rows = LogicalRowBuilder.Build(words, region, ruleYs);
+
+        Assert.Equal(4, rows.Count);
+        Assert.Equal(["Alice", "91"], rows[0].Select(w => w.Text).ToArray());
+        Assert.Equal(["Bob", "82"], rows[1].Select(w => w.Text).ToArray());
+    }
+
     private static TableCellRecovery.Word W(string text, double centerX, double centerY, double width = 24, double height = 8) =>
         new(new BoundingBox(centerX - width / 2, centerY - height / 2, centerX + width / 2, centerY + height / 2), text);
 }

src/PdfStruct.Tests/TableCellRecoveryTests.cs

@@ -115,6 +115,76 @@ public void Recover_NoInteriorRules_SingleBandRecoversLeafColumns()
         Assert.All(rows, r => Assert.All(r.Cells, c => Assert.Equal(1, c.ColumnSpan)));
     }
 
+    [Fact]
+    public void Recover_RuledTable_TrimsCompletelyEmptyLeadingSlot()
+    {
+        // A ruled table can carry a decorative or over-wide leading slot before
+        // the real stub column. The recovered model should not preserve a
+        // permanently empty first column, because Markdown would render it as a
+        // blank column with no information.
+        var words = new List<TableCellRecovery.Word>
+        {
+            W("Method", 170, 700, 42), W("SVT", 270, 700, 28), W("IC15", 350, 700, 34),
+            W("ABBYY", 170, 686, 44), W("40.5", 270, 686, 30), W("-", 350, 686, 12),
+            W("Ours", 170, 672, 32), W("94.3", 270, 672, 30), W("68.8", 350, 672, 30),
+        };
+        var region = new BoundingBox(50, 660, 400, 712);
+        var boundaries = new List<double> { 120, 230, 320 };
+
+        var rows = TableCellRecovery.Recover(words, region, boundaries, [], pageNumber: 1);
+
+        Assert.Equal(3, rows.Count);
+        Assert.All(rows, row => Assert.Equal([1, 2, 3], row.Cells.Select(c => c.ColumnNumber).ToArray()));
+    }
+
+    [Fact]
+    public void Recover_RuledTable_SplitsStackedCompleteRecords()
+    {
+        // Dense ruled tables may have a rule band that visually contains more
+        // than one data record. Each baseline that has both a stub label and
+        // value columns must become its own table row.
+        var words = new List<TableCellRecovery.Word>
+        {
+            W("Alice", 90, 705, 34), W("91", 190, 705, 20),
+            W("Bob", 90, 697, 28), W("82", 190, 697, 20),
+            W("Cara", 90, 679, 34), W("77", 190, 679, 20),
+            W("Dana", 90, 657, 34), W("73", 190, 657, 20),
+        };
+        var region = new BoundingBox(60, 646, 230, 712);
+        var boundaries = new List<double> { 140 };
+        var ruleYs = new List<double> { 712, 690, 668, 646 };
+
+        var rows = TableCellRecovery.Recover(words, region, boundaries, ruleYs, pageNumber: 1);
+
+        Assert.Equal(4, rows.Count);
+        Assert.Equal(["Alice", "Bob", "Cara", "Dana"], rows.Select(r => CellText(r.Cells[0])).ToArray());
+        Assert.Equal(["91", "82", "77", "73"], rows.Select(r => CellText(r.Cells[1])).ToArray());
+    }
+
+    [Fact]
+    public void Recover_RuledTable_MergesDashOnlyContinuationIntoPreviousRecord()
+    {
+        // Some PDFs draw placeholder dashes on a slightly lower baseline. They
+        // are empty-value markers for the labelled record above, not standalone
+        // table rows.
+        var words = new List<TableCellRecovery.Word>
+        {
+            W("Alice", 90, 705, 34), W("91", 190, 705, 20),
+            W("-", 250, 697, 12),
+            W("Bob", 90, 679, 28), W("82", 190, 679, 20), W("73", 250, 679, 20),
+        };
+        var region = new BoundingBox(60, 668, 290, 712);
+        var boundaries = new List<double> { 140, 220 };
+        var ruleYs = new List<double> { 712, 701, 690, 668 };
+
+        var rows = TableCellRecovery.Recover(words, region, boundaries, ruleYs, pageNumber: 1);
+
+        Assert.Equal(2, rows.Count);
+        Assert.Equal("Alice", CellText(rows[0].Cells[0]));
+        Assert.Equal("-", CellText(rows[0].Cells[2]));
+        Assert.Equal("Bob", CellText(rows[1].Cells[0]));
+    }
+
     private static string CellText(TableCell cell) =>
         string.Join(" ", cell.Kids.OfType<ParagraphElement>().Select(p => p.Text.Content));
 

src/PdfStruct.Tests/TableReconciliationTests.cs

@@ -66,6 +66,8 @@ public void Parse_TableCaptionContinuation_IsNotClaimedAsTableRow()
 
         var table = doc.Kids.OfType<TableElement>()
             .Single(t => t.PageNumber == 6 && t.NumberOfColumns == 3);
+        Assert.True(caption.Id < table.Id);
+        Assert.Equal(table.Id, caption.LinkedContentId);
         var cellTexts = table.Rows
             .SelectMany(r => r.Cells)
             .SelectMany(c => c.Kids.OfType<ParagraphElement>())
@@ -103,6 +105,41 @@ public void Parse_TableTrailingNotes_AreReleasedNotClaimedAsTableContent()
         Assert.Contains(nonTableText, text => text.Contains(doi, StringComparison.Ordinal));
     }
 
+    [Fact]
+    public void Parse_UtilizingLlm_RuledTablesRecoverCells()
+    {
+        var doc = ParseFixture("plos_utilizing_llm.pdf");
+
+        var tables = doc.Kids.OfType<TableElement>().ToList();
+        Assert.Equal(5, tables.Count);
+        Assert.All(tables, table =>
+        {
+            Assert.NotEmpty(table.Rows);
+            Assert.Empty(table.TextLines);
+            Assert.True(table.NumberOfRows >= 4);
+            Assert.True(table.NumberOfColumns >= 3);
+        });
+    }
+
+    [Fact]
+    public void Parse_GameBasedEducation_RuledResultTablesRecoverCells()
+    {
+        var doc = ParseFixture("plos_game_based_education.pdf");
+
+        var tables = doc.Kids.OfType<TableElement>().ToList();
+        Assert.Equal(5, tables.Count);
+        Assert.Equal(4, tables.Count(t => t.Rows.Count > 0));
+        Assert.Single(tables, t => t.Rows.Count == 0);
+
+        var beck = tables.Single(t => t.Rows
+            .SelectMany(r => r.Cells)
+            .Any(c => CellText(c).Contains("Beck Anxiety Inventory", StringComparison.Ordinal)));
+        Assert.Equal(3, beck.NumberOfRows);
+        Assert.Equal(6, beck.NumberOfColumns);
+        Assert.Contains(beck.Rows.SelectMany(r => r.Cells), c => CellText(c) == "Post-test");
+        Assert.Contains(beck.Rows.SelectMany(r => r.Cells), c => CellText(c).Contains("−7.04", StringComparison.Ordinal));
+    }
+
     private static string ElementText(ContentElement element) => element switch
     {
         ParagraphElement p => p.Text.Content,
@@ -112,6 +149,9 @@ public void Parse_TableTrailingNotes_AreReleasedNotClaimedAsTableContent()
         _ => string.Empty
     };
 
+    private static string CellText(TableCell cell) =>
+        string.Join(" ", cell.Kids.OfType<ParagraphElement>().Select(p => p.Text.Content));
+
     private static PdfDocument ParseFixture(string fixtureName)
     {
         var path = Path.Combine(AppContext.BaseDirectory, "Fixtures", fixtureName);

src/PdfStruct.Tests/TextAwareRuledTableDetectorTests.cs

@@ -115,6 +115,26 @@ public void Detect_GridColumnsWitnessedByVerticalRulesOnly_StillDetected()
         Assert.True(region.BoundingBox.Width > 250, "Region should span the ruled grid.");
     }
 
+    [Fact]
+    public void Detect_WideLeadingRuleOverhang_TrimsToPayloadStart()
+    {
+        // 1901 page 12 Table 9 has horizontal rules that start far left of the
+        // real payload. Other tables have only ordinary border padding; this
+        // wide empty overhang should not become a blank first table column.
+        var rules = new[] { HRule(50, 400, 200), HRule(50, 400, 170), HRule(50, 400, 140) };
+        var lines = new List<TextLineBlock>
+        {
+            Cell("Method", 140, 185), Cell("SVT", 240, 185), Cell("IC15", 330, 185),
+            Cell("ABBYY", 140, 158), Cell("40.5", 240, 158), Cell("-", 330, 158),
+            Cell("Ours", 140, 148), Cell("94.3", 240, 148), Cell("68.8", 330, 148),
+        };
+
+        var region = Assert.Single(TextAwareRuledTableDetector.Detect(lines, rules, []));
+
+        Assert.True(region.BoundingBox.Left > 100, "Wide empty leading rule overhang should be trimmed.");
+        Assert.True(region.BoundingBox.Left <= 140, "Trimmed box must still include the first payload column.");
+    }
+
     private static BoundingBox HRule(double left, double right, double y) => new(left, y, right, y + 0.5);
 
     private static BoundingBox VRule(double x, double bottom, double top) => new(x, bottom, x + 0.5, top);

src/PdfStruct/Analysis/Tables/LogicalRowBuilder.cs

@@ -2,6 +2,7 @@
 // Licensed under the Apache License, Version 2.0.
 
 using PdfStruct.Models;
+using BaselineRow = PdfStruct.Analysis.Tables.TableRowGrouping.BaselineRow;
 using Word = PdfStruct.Analysis.Tables.TableCellRecovery.Word;
 
 namespace PdfStruct.Analysis.Tables;
@@ -30,12 +31,6 @@ namespace PdfStruct.Analysis.Tables;
 /// </remarks>
 internal static class LogicalRowBuilder
 {
-    /// <summary>Two blocks share a baseline when their baselines differ by at most this factor of the smaller font height.</summary>
-    private const double RowBaselineToleranceFactor = 0.4;
-
-    /// <summary>Absolute floor, in PDF points, for the same-baseline tolerance.</summary>
-    private const double MinRowBaselineTolerance = 1.5;
-
     /// <summary>Two word centres within this factor of the word height are the same column.</summary>
     private const double ColumnToleranceFactor = 0.6;
 
@@ -70,7 +65,7 @@ public static List<List<Word>> Build(
         ArgumentNullException.ThrowIfNull(words);
         ArgumentNullException.ThrowIfNull(horizontalRuleYs);
 
-        var baselineRows = ClusterBaselineRows(words);
+        var baselineRows = TableRowGrouping.ClusterBaselineRows(words);
         if (baselineRows.Count <= 1) return baselineRows.Select(r => r.Words.ToList()).ToList();
 
         if (TryRuleBands(words, region, horizontalRuleYs, baselineRows.Count, out var bandRows))
@@ -79,41 +74,6 @@ public static List<List<Word>> Build(
         return MergeContinuations(baselineRows);
     }
 
-    /// <summary>Clusters words into baseline rows, top to bottom.</summary>
-    private static List<Row> ClusterBaselineRows(IReadOnlyList<Word> words)
-    {
-        var ordered = words.OrderByDescending(w => w.BoundingBox.CenterY).ToList();
-        var rows = new List<Row>();
-        var current = new List<Word>();
-        var baseline = 0.0;
-
-        foreach (var word in ordered)
-        {
-            var height = word.BoundingBox.Height;
-            if (current.Count == 0)
-            {
-                current.Add(word);
-                baseline = word.BoundingBox.CenterY;
-                continue;
-            }
-
-            var smaller = Math.Min(current.Min(w => w.BoundingBox.Height), height);
-            var tolerance = Math.Max(MinRowBaselineTolerance, RowBaselineToleranceFactor * smaller);
-            if (baseline - word.BoundingBox.CenterY <= tolerance)
-            {
-                current.Add(word);
-            }
-            else
-            {
-                rows.Add(MakeRow(current));
-                current = [word];
-                baseline = word.BoundingBox.CenterY;
-            }
-        }
-        if (current.Count > 0) rows.Add(MakeRow(current));
-        return rows;
-    }
-
     /// <summary>
     /// Buckets words into the bands a regular full-width rule grid draws. Returns
     /// <c>false</c> when the rules are not a per-row grid (too few bands, irregular
@@ -150,14 +110,30 @@ private static bool TryRuleBands(
         for (var i = 1; i < boundaries.Count; i++) heights.Add(boundaries[i - 1] - boundaries[i]);
         if (CoefficientOfVariation(heights) > MaxBandHeightCv) return false;
 
-        if (buckets.Count(band => band.Count > 0) >= baselineRowCount) return false;
+        bandRows = SplitRuleBands(buckets.Where(band => band.Count > 0).ToList());
+        if (bandRows.Count >= baselineRowCount) return false;
 
-        bandRows = buckets.Where(band => band.Count > 0).ToList();
         return bandRows.Count > 0;
     }
 
+    /// <summary>
+    /// A rule band is usually one logical row, but dense ruled tables sometimes
+    /// omit the interior rule between consecutive body records. Split only when
+    /// multiple baselines in the same band each open the anchor column and at
+    /// least one data column; label-only baselines remain wrapped cell text.
+    /// </summary>
+    private static List<List<Word>> SplitRuleBands(List<List<Word>> bands) =>
+        TableRowGrouping.SplitStackedRecords(bands, band =>
+        {
+            var tolerance = Math.Max(MinColumnTolerance, ColumnToleranceFactor * Median(band.Select(w => w.BoundingBox.Height)));
+            var anchor = band.Min(w => w.BoundingBox.CenterX);
+            return words =>
+                words.Any(w => w.BoundingBox.CenterX <= anchor + tolerance)
+                && words.Any(w => w.BoundingBox.CenterX > anchor + Math.Max(3 * tolerance, 12.0));
+        });
+
     /// <summary>Merges wrapped continuation rows into the row above, leaving new records and finer header levels as their own rows.</summary>
-    private static List<List<Word>> MergeContinuations(List<Row> baselineRows)
+    private static List<List<Word>> MergeContinuations(List<BaselineRow> baselineRows)
     {
         var tolerance = Math.Max(MinColumnTolerance, ColumnToleranceFactor * Median(baselineRows.SelectMany(r => r.Words).Select(w => w.BoundingBox.Height)));
         var stable = StableColumnCenters(baselineRows, tolerance);
@@ -166,7 +142,7 @@ private static List<List<Word>> MergeContinuations(List<Row> baselineRows)
         var anchor = stable[0];
         var medianGap = MedianBaselineGap(baselineRows);
 
-        var groups = new List<List<Row>>();
+        var groups = new List<List<BaselineRow>>();
         foreach (var row in baselineRows)
         {
             if (groups.Count == 0) { groups.Add([row]); continue; }
@@ -189,7 +165,7 @@ private static List<List<Word>> MergeContinuations(List<Row> baselineRows)
     /// or a finer header level (introducing columns the group lacks) fails both
     /// tests and stays a separate row.
     /// </summary>
-    private static bool IsContinuation(Row row, List<Row> group, double anchor, double tolerance)
+    private static bool IsContinuation(BaselineRow row, List<BaselineRow> group, double anchor, double tolerance)
     {
         if (row.Words.Any(w => w.BoundingBox.CenterX <= anchor + tolerance)) return false;
 
@@ -198,7 +174,7 @@ private static bool IsContinuation(Row row, List<Row> group, double anchor, doub
     }
 
     /// <summary>Returns the centres of word columns that recur across baseline rows, left to right.</summary>
-    private static List<double> StableColumnCenters(List<Row> rows, double tolerance)
+    private static List<double> StableColumnCenters(List<BaselineRow> rows, double tolerance)
     {
         var all = new List<(double Center, int Row)>();
         for (var r = 0; r < rows.Count; r++)
@@ -233,16 +209,13 @@ void Flush()
         return stable;
     }
 
-    private static double MedianBaselineGap(List<Row> rows)
+    private static double MedianBaselineGap(List<BaselineRow> rows)
     {
         var gaps = new List<double>();
         for (var i = 1; i < rows.Count; i++) gaps.Add(rows[i - 1].Baseline - rows[i].Baseline);
         return Median(gaps);
     }
 
-    private static Row MakeRow(List<Word> words) =>
-        new(words.Average(w => w.BoundingBox.CenterY), words);
-
     private static double CoefficientOfVariation(List<double> values)
     {
         if (values.Count == 0) return double.MaxValue;
@@ -259,7 +232,4 @@ private static double Median(IEnumerable<double> values)
         var mid = sorted.Count / 2;
         return sorted.Count % 2 == 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2.0;
     }
-
-    /// <summary>A baseline-grouped row of words.</summary>
-    private sealed record Row(double Baseline, IReadOnlyList<Word> Words);
 }