Skip to content

Add opt-in drawing PDF views and Markdown reports - #2689

Open
Çağdaş Yürekli (cagdasyurekli) wants to merge 2 commits into
microsoft:mainfrom
cagdasyurekli:feat/pdf-drawing-markdown
Open

Çağdaş Yürekli (cagdasyurekli) wants to merge 2 commits into
microsoft:mainfrom
cagdasyurekli:feat/pdf-drawing-markdown

Conversation

@cagdasyurekli

@cagdasyurekli Çağdaş Yürekli (cagdasyurekli) commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Vector drawing PDFs can return successful Markdown containing isolated labels while omitting drawing lines and SHX annotation text. Add an explicit local --pdf-drawing-mode / pdf_drawing_mode=True path that returns located native/SHX labels, raster page views, and an English Markdown limitations report. Existing conversion defaults remain unchanged.

markitdown drawing.pdf --pdf-drawing-mode -o drawing.md

This produces drawing.md, drawing.report.md, and drawing.assets/page-1.png, etc. Output destinations must be new; existing files, symlink destinations, and source overwrites are refused. Publication stages the files, creates destinations exclusively using hard links, and rolls back on failure. The filesystem must support hard links. --conversion-report selects another report path; stdout requires explicit --keep-data-uris and a report path.

The API returns result.assets and result.conversion_report without filesystem writes. ZIP members retain distinct image names and reports, and drawing render failures propagate instead of becoming successful text-only conversion. The optional MCP argument returns inline views and the report without file writes. Drawing mode runs before PDF plugin/cloud fallback selection; the CLI rejects combinations with Azure conversion flags.

This is not lossless or semantic drawing reconstruction. CropBox page views use up to 200 DPI, capped at 8192 pixels on the longest edge; fine detail may be lost. Reports give MediaBox/CropBox bounds and limitations without claiming exhaustive detection. There is no OCR, unit/scale inference, dimension association, or external model call. Angled lettering may have imperfect word grouping. All page PNGs remain in memory, so large drawings can be resource-heavy. Visual consumers must receive image pixels explicitly.

Validation on the review candidate (Python 3.12):

  • Full core suite: 1,075 passed, 57 skipped using the existing CI skip conditions; OCR: 108 passed; MCP: 22 passed, run as separate packages.
  • Black 23.7.0 and git diff --check passed. Drawing tests now live in the existing test_pdf.py per the test-organization guide; all drawing test functions were preserved, and the MCP fixture reference was updated.
  • Independent review found no blocking issue. Additional checks verified rollback after the third publication link fails, the 8192-pixel cap on a real large-page PDF, and propagation of a second ZIP member's render failure. A rotated/cropped synthetic page view was visually inspected.
  • Earlier implementation validation included failing-before/passing-after regressions and seven public PDFs covering 56 pages. No third-party PDFs or generated assets are committed.

Scope versus main: net +338 production lines, +337 test lines, and +59 documentation lines for the drawing path, safe output publication, and integration coverage; no new runtime or test dependencies. This readiness follow-up changes only test organization (net -5 lines).

Core/plugin placement and the public assets/report shape remain open to maintainer review. This contribution is independent of #2668; related overlapping proposals are #1398 and #2055.

Refs #2688.

@cagdasyurekli
Çağdaş Yürekli (cagdasyurekli) marked this pull request as ready for review October 15, 2026 09:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant