feat(layout): add opt-out for dropping pictures that coincide with tables (#3922)

[Anai-Guo]

Fixes #3922

Problem

Since 2.103.0 (#3523, extended by #3536 and #3789) LayoutPostprocessor._handle_cross_type_overlaps drops a PICTURE cluster whose bbox nearly coincides with a TABLE cluster (IoU > 0.8), keeping only the structured TABLE.

That is the right call in the common case, but there is no way to opt out. Dropping the picture also removes the only signal that there is an image there — including the region's rendered crop. As reported in #3922, some pipelines use that crop as a safety net: when TableFormer extracts a table badly, a vision-model description of the same region recovers the content. With the picture gone, the fallback is gone too.

Change

Add remove_pictures_coinciding_with_tables to BaseLayoutPostprocessorOptions, defaulting to True so current behaviour is unchanged. When set to False, the coinciding PICTURE is kept alongside the TABLE.

The option lives on the layout-postprocessor options rather than on PdfPipelineOptions (as sketched in the issue), because that is where the deduplication actually runs and where the sibling toggles (keep_empty_clusters, skip_cell_assignment, create_orphan_clusters) already live.

The table itself is untouched — this only controls whether the duplicate PICTURE survives.

Tests

tests/test_layout_postprocessor.py gains test_cross_type_overlaps_keeps_coinciding_picture_when_opted_out, asserting both clusters survive when the option is disabled. The three existing cross-type tests build a half-initialized postprocessor via object.__new__, so they now also set processor.options; their assertions are unchanged.

Verified locally against the postprocessor as it stands on main (byte-identical to the file in this PR's base):

• new test against unpatched postprocessor → fails (picture removed despite the opt-out)
• new test against patched postprocessor → passes
• the three pre-existing cross-type tests → pass, default behaviour unchanged

The ML-backed integration test tests/test_layout_picture_table_overlap.py keeps passing unchanged, since the default stays True.

ruff 0.15.12 (check + format, repo pyproject.toml) reports nothing new relative to main on the three touched files.

🤖 Generated with Claude Code

[github-actions]

✅ DCO Check Passed

Thanks @Anai-Guo, 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)(?:\(.+\))?(!)?: