fix(pptx): read shapes in reading order (left-to-right within a row) - #2572
Open
Aimery Barrault (aImErYbArRaUlT) wants to merge 1 commit into
Open
Aimery Barrault (aImErYbArRaUlT) wants to merge 1 commit into
Aimery Barrault (aImErYbArRaUlT) wants to merge 1 commit into
Conversation
PptxConverter ordered shapes by (top, left), which sorts by top first and has no notion of "same row", so two-column bodies read right-then-left, right-aligned values jump ahead of their labels, and captions detach from figures. Shapes that overlap vertically are now grouped into row bands, read top-to-bottom and left-to-right within a band. A full-height spanner (a sidebar) beside a grid is lifted onto its horizontal side so the grid stays row-major; a full-width title that dips into the row below leads its band; and a full-width caption sharing a chart's or table's frame is read on the correct side of it. No shape is added or dropped; only the order changes. Applied to a slide's shapes and to group children.
Aimery Barrault (aImErYbArRaUlT)
force-pushed
the
fix/pptx-reading-order
branch
from
October 2, 2026 08:22
946b514 to
70e4e3f
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PptxConverter.convert()ordered shapes by (top, left), which sorts by top first and has no notion of "same row". So a two-column body reads its right column before its left, a right-aligned value (a date next to a job title) is read before its label, and a caption beside a figure detaches from it. A few EMU of difference intopis enough to reverse a row.A
_sort_shapes_reading_order()helper groups shapes that substantially overlap vertically into row bands, reads the bands top-to-bottom and the shapes left-to-right within a band. A full-height spanner (a sidebar) beside a grid is lifted onto its horizontal side so the grid stays row-major; a full-width title that dips into the row below leads its band; and a full-width caption sharing a chart's or table's frame is read on the correct side of it. No shape is added or dropped; only the order changes. Applied to a slide's shapes and to group children, and it preserves theNone/top-zero handling from #2408.Evidence
On a ground-truth benchmark (synthetic slides with a known reading order and seeded jitter; mean Spearman vs that order):
(top, left)The fix matches or beats the current order on every archetype, including the out-of-scope newspaper case. Across a 740-slide real-deck corpus (docling, Unstructured, Apache POI) no shape is ever dropped or duplicated, and the order changes only on the slides where the current top-first sort scrambles a row. Full numbers, the blind real-deck render result, and the benchmark script are in #2571.
The change is default-on on that basis; if you would rather gate it behind a kwarg until it has mileage, say so and I will switch it.
Limitation
It does not reconstruct column-major "newspaper" order: when a slide is laid out as several tall columns that each stack several boxes, the fix reads it row by row (left to right across the columns) rather than down one column before starting the next. There it improves on the current sort but does not fully solve the layout (the newspaper row above).
Tests
Added in
tests/test_pptx_reading_order.py(two-column, label/value, grid beside a sidebar, group recursion, title-over-row, caption-in-frame, a diagonal staircase, and three None-position units); the ordering tests fail on the old order and pass with the fix. Full suites pass.Note
This touches the same group-shape block in
_pptx_converter.pyas #2570, so whichever merges second will need a small rebase. I will rebase this onto main once #2570 lands.Fixes #2571.