[wittjeff]

Standalone topic per #428: a clip box on text cells, and a contraction rule that uses it. Two commits, rebased on main (f4b12cf), no merge commits. This is the prototype proposed on #404 (2026-10-16, A/B updated 2026-10-29), now on current main.

Fixes #404. Refs docling-project/docling#4762 (the docling table matcher can place a clipped word by its clip box once it has one).

commit	fix
1	Every char, word and line cell carries the bounding box of the clip it was painted under (has_clip_bbox, clip_x0..clip_y1, page coordinates; pybind + PdfTextCell.clip_bbox when the installed docling-core has the field). Two consecutive glyphs under different clip boxes, of which at least one is cut by its own clip, never join into one word or one line. Clip paths are tracked even when shapes are skipped (DecodeConfig.keep_clips, default true), since docling computes shapes only when it renders pages.
2	The sanitizer that moves cells to the origin of the crop or media box moves the clip box with them; without it the box sat beside its glyphs on pages whose box does not start at (0, 0).

Why the words merged

contract() starts a new word when the normalized forward gap exceeds the word gap, and clamps the gap at zero, so a glyph that overlaps its predecessor can never start a word. In the issue's clipped-table.pdf, row 1's Z ends at x=130.5 and R starts at x=125.0: gap −5.5 pt, clamped to 0, one word AB-1001-XYZReplacement. The clip that hides the tail was tracked only in pdf_state<SHAPE> for the render instruction; the cell got nothing. And every path and clip operator in shape.h returned early without keep_shapes, which docling sets only when it renders pages, so a parse with render_pages=False had no clip at all.

What "cut" means

The corpus has producers that wrap every text run, or every glyph, in a clip that does not cut it; that clip only the one glyph which overflows a cell and draw the rest of the word unclipped; that draw ink-tight clips around punctuation; and that repaint glyphs under sliver clips a fraction of a point wide. So the rule is narrower than "different clip means different word": a glyph counts as cut when its clip hides more than a fifth of its extent along the writing axis, or of its em if that is larger; a clip box shorter than one em along that axis never cuts, since it cannot be a cell; and when only one of the two glyphs has a clip box, the other still belongs to it while it lies inside that box. Each of those producer patterns was a false positive of a simpler rule before its guard went in, and each has a unit test in tests/test_unit_clipped_cell_text.py (9 tests, synthetic PDFs built with tests/pdf_builder).

Changes made while rebasing on #437

• fix(text): word and cell segmentation fixes, consolidated per #428 #437 removed the crossed_explicit_space flag from the gap-profile loop (a semantic space now resets previous); the clip check moved onto the new condition in infer_unspaced_gap_profile().
• fix(text): word and cell segmentation fixes, consolidated per #428 #437 added a second seam loop, infer_spaced_word_gap(); it skips clip-boundary pairs the same way, so a cut tail under the next cell does not feed the median of a line's letter gaps.
• The pybind block and the render_instructions.h includes merged with feat: read the tagged-PDF structure tree and link text cells to marked content #337 and fix(render): stroke clipping, tiling patterns and soft masks, consolidated per #428 #439 textually; the renderer still receives the same clip state, now captured once per glyph and shared with the cell.

docling-core

The field is PdfTextCell.clip_bbox: Optional[BoundingBox], docling-project/docling-core#964 (the origin conversions move it with rect). docling-parse fills it only when the installed model has the field, so this PR does not raise the docling-core floor; the positional JSON record is unchanged.

Evidence and ground truth changes

I built main (f4b12cf) and this branch and dumped the word and line cells of every page of the regression page selection (tests/regression_page_selection.py: 453 documents, 950 pages, revision df881cc), with the parser configuration of test_reference_documents_from_filenames.

pages	identical	regrouped	text changed
950	928	22	0

Clips are common: on 350 of the 950 pages at least one word cell carries a clip box (114,123 word cells in all), and only the 22 pages below regroup, which is why the rule asks for a cut glyph and not merely for different clips.

Every regrouped page is the pattern of this issue, found in the corpus without looking for it: a table whose producer clipped cell text to the cell. Ground truth changes on the 22 pages below because the rule separates what a producer put into different boxes; no page changes for any other reason, and no text changes.

11024633002361155703-1.pdf, p1: results table, name column clipped at x=160.7: Christophen°1059 splits into Christophe + n°1059, and the line splits at the cell border

Ground truth changes because the clipped tail of a cell no longer joins the first word of the next cell.

words on p1:

before	after
Christophen°1059	Christophe / n°1059

11268045627910569931_002.pdf, pp. 1–3: region column clipped at x=216.7 (Yorke Peninsul, Outback - Nort is what the page shows): W12-<15 and Ma12-<15 split at the cell border, and those rows' lines split into the region cell and the months cell

Ground truth changes because the clipped tail of a cell no longer joins the first word of the next cell.

words on p1:

before	after
W12-<15 / Ma12-<15	W / 12-<15 / Ma / 12-<15

3 pages; word cells 1389 → 1395, line cells 985 → 991.

1135949864700736255-1.pdf, p1: Japanese menu table: a dish name and its ingredient list, clipped to neighbouring cells, become two lines

Ground truth changes because a line no longer runs from a clipped cell into the next cell.

lines on p1:

before	after
ちくわの磯辺揚げ（じゃがいも、まいたけ） ちくわ、あおのり、小麦粉、じゃがいも、まいたけ、油	ちくわの磯辺揚げ（じゃがいも、まいたけ） / ちくわ、あおのり、小麦粉、じゃがいも、まいたけ、油

16470238655385139760-1.pdf, p1: Japanese table: the label 2-2 separates from the clipped neighbour cell

Ground truth changes because the clipped tail of a cell no longer joins the first word of the next cell.

words on p1:

before	after
建築物の環境効率（BEEランク&チャート）2-2	建築物の環境効率（BEEランク&チャート） / 2-2

9590626299437503566-1.pdf, p1: Japanese table: the unit kg separates from the clipped item name

Ground truth changes because the clipped tail of a cell no longer joins the first word of the next cell.

words on p1:

before	after
混合廃棄物(石膏ボード系混入物）kg	混合廃棄物(石膏ボード系混入物） / kg

ddf7d91a5a010970_0020.pdf, p1: header Crédits separates from the clipped header of the next column; words unchanged

Ground truth changes because a line no longer runs from a clipped cell into the next cell.

lines on p1:

before	after
Crédits OBSERVATIONS / Crédits OBSERVATIONS	Crédits / OBSERVATIONS / Crédits / OBSERVATIONS

3763025099401294496-2.pdf, pp. 2–15: roster whose name column clips long names: no word changes, lines such as MUNOZ, BRANDON SD split into the name cell and the school cell

Ground truth changes because a line no longer runs from a clipped cell into the next cell.

lines on p2:

before	after
MUNOZ, BRANDON SD / 0.0 MUNOZ, BRANDON SD / MUNOZ, BRANDON SD / 0.0 ARREOLA, NATHAN MON / ARREOLA, NATHAN MON	MUNOZ, BRANDON / SD / 0.0 MUNOZ, BRANDON / SD / MUNOZ, BRANDON

14 pages; word cells 12765 → 12765, line cells 8633 → 8826.

All pages

11024633002361155703-1.pdf p1, 11268045627910569931_002.pdf p1, 11268045627910569931_002.pdf p2, 11268045627910569931_002.pdf p3, 1135949864700736255-1.pdf p1, 16470238655385139760-1.pdf p1, 9590626299437503566-1.pdf p1, ddf7d91a5a010970_0020.pdf p1, 3763025099401294496-2.pdf p2, 3763025099401294496-2.pdf p3, 3763025099401294496-2.pdf p4, 3763025099401294496-2.pdf p5, 3763025099401294496-2.pdf p6, 3763025099401294496-2.pdf p7, 3763025099401294496-2.pdf p8, 3763025099401294496-2.pdf p9, 3763025099401294496-2.pdf p10, 3763025099401294496-2.pdf p11, 3763025099401294496-2.pdf p12, 3763025099401294496-2.pdf p13, 3763025099401294496-2.pdf p14, 3763025099401294496-2.pdf p15

Before/after images

Every page of the A/B whose word or line cells change. Page render: pypdfium2. Left: cells that main emits and this branch does not (red). Right: the cells that replace them (green and blue alternate, so adjacent cells stay apart). Images and script: pr-evidence/404-pr.

11024633002361155703-1.pdf, p1

11268045627910569931_002.pdf, pp. 1–3

1135949864700736255-1.pdf, p1

16470238655385139760-1.pdf, p1

9590626299437503566-1.pdf, p1

ddf7d91a5a010970_0020.pdf, p1

3763025099401294496-2.pdf, pp. 2–15

Known limits

• A non-rectangular clip is over-approximated by its box; fine for the table case, documented on the field.
• Text that overflows nothing keeps joining across cells when the glyphs do (row 2 of clipped-table.pdf, AB-1002 Gutter cleaning is one line as before); the words still carry their cell boxes.
• The knobs are the cut threshold (a fifth of max(extent, em)), the one-em minimum box width and the box-equality epsilon (CLIP_HIDDEN_FRACTION, CLIP_BBOX_EPS in cells.h); the A/B above is the evidence for them.
• The cost with shapes skipped is the path construction on pages that clip; not measured.

Checklist (#428)

• One topic per PR, rebased on main, no merge commits
• No superseded PRs (this is the first PR for Text clipped at a table-cell border loses the cell it belongs to #404)
• Regression dataset documents and pages named above; no dataset PR needed
• Before/after evidence for each cited page
• Rendering only: not applicable
• Blend2D only: not applicable
• Changes to existing ground truth listed with the reason for each page

🤖 Generated with Claude Code

[github-actions]

✅ DCO Check Passed

Thanks @wittjeff, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?: