pdf-questions-to-ppt

name

pdf-questions-to-ppt

description

Convert any worksheet, exercise-set, exam, question-bank, scanned, mixed-layout, or multi-page PDF into a PowerPoint with one complete top-level question per slide. Use when the user asks to split a PDF into questions, screenshot every problem into PPT/PPTX, preserve formulas and diagrams, merge cross-page questions, or save a same-name PPTX beside the source PDF. Automatically propose question boundaries for text PDFs and fall back to coordinate-grid visual review for scans or irregular layouts.

PDF Questions To PPT

Preserve questions as high-resolution images. Aim to handle every PDF through two paths: propose boundaries automatically when the text layer is useful, or define them visually when it is not. Never sacrifice correctness for unattended automation.

Workflow

1. Resolve the exact source PDF. Never reuse a prior PDF's coordinates or question count.
2. Run scripts/inspect_pdf.py in a temporary directory. Review contact sheets, coordinate-grid previews, page sizes, and text coverage.
3. For text-rich PDFs, run scripts/propose_question_spec.py to create a draft crop spec. Treat review_required: true literally.
4. For scans, handwriting, unusual numbering, overlapping cards, or low-confidence drafts, determine top-level question units from the grid previews and write the spec manually.
5. Review every draft boundary. Keep all subparts, formulas, diagrams, choices, blanks, and cross-page continuations with their top-level question. Remove section titles, page numbers, answers, and neighboring questions.
6. Run scripts/build_question_ppt.py. It safely trims outer white space, joins multi-part questions, reports edge-content risks, and validates the PPTX.
7. Inspect all generated question contact sheets. Rebuild after correcting every clipped, contaminated, duplicated, missing, or unreadably small crop.
8. Confirm slide count equals the visually verified top-level question count. Preserve the source PDF and remove temporary artifacts.

Do not claim completion based only on automatic detection or structural validation. The invariant is one complete top-level question per slide.

Inspect

python "$SKILL_DIR/scripts/inspect_pdf.py" "D:\path\source.pdf" --out "D:\tmp\pdf-inspect"

Outputs include:

• preview-*.webp: page previews
• grid-*.webp: previews with PDF-point coordinates every 50 points
• page-*.png: detailed renders; for PDFs over 30 pages these are skipped by default to control disk usage
• contact-sheet*.webp: paginated overview
• text-blocks.json: page sizes, text blocks, text coverage, and scan-like flags

Use --detail-pages all, none, or a range such as 1-5,9,12-14 to control detailed renders.

Propose A Draft Spec

python "$SKILL_DIR/scripts/propose_question_spec.py" "D:\path\source.pdf" --output "D:\tmp\draft-spec.json"

The proposer recognizes common Arabic, Chinese, English, Question, Q, 第...题, 例..., and circled-number markers. It uses numbering sequences, section-heading penalties, columns, and page flow to propose crops. It intentionally ignores parenthesized markers such as (1) by default because they are usually subparts.

If questions is empty or mode is visual-required, use grid previews. If candidates are rejected or confidence is below 0.75, inspect them explicitly. Automated multi-column and cross-page results always require close review.

Crop Spec

{
  "questions": [
    {
      "id": "question-1",
      "parts": [
        {"page": 1, "rect": [40, 120, 550, 280]}
      ]
    },
    {
      "id": "question-2",
      "layout": "vertical",
      "parts": [
        {"page": 1, "rect": [40, 650, 550, 760]},
        {"page": 2, "rect": [40, 20, 550, 180]}
      ]
    }
  ]
}

Coordinates are [left, top, right, bottom] in PDF points; pages are 1-based. Extra _detection fields from the proposer are informational and ignored by the builder. Use "trim": false on a question only when safe white-space trimming removes meaningful light content. Use layout: "horizontal" only when it materially improves reading order.

Build And Review

python "$SKILL_DIR/scripts/build_question_ppt.py" "D:\path\source.pdf" "D:\tmp\reviewed-spec.json" --preview "D:\tmp\questions.webp" --qa-report "D:\tmp\qa.json"

Defaults: same-directory same-stem .pptx, white 16:9 slides, 3.5x render scale, safe outer-white-space trimming, and vertical joining. Useful options:

• --output: choose another PPTX path
• --slide-size wide|standard: choose 16:9 or 4:3
• --keep-crops: retain individual PNGs
• --no-trim: disable safe trimming globally
• --trim-threshold and --trim-padding: tune trimming for faint or scanned content
• --strict-qa: fail when crop-edge warnings remain

The QA report flags non-white content touching source crop edges, empty crops, extreme aspect ratios, and pictures that become very small on a slide. These are review signals, not proof of an error.

General Rules

• Create a new spec for every PDF. Never store source-specific specs in this Skill.
• Use one slide per top-level question, not per PDF page or per subpart.
• Prefer a generous crop before review; let safe trimming remove only outer blank space.
• For scans without text, rely on grid previews. OCR is optional, never required for preserving the original image.
• For mixed page sizes and rotations, use each page's own coordinates from text-blocks.json.
• For two-column pages, verify reading order and diagrams that cross column boundaries.
• For long PDFs, review paginated contact sheets and render detailed pages in batches.
• A password-protected PDF requires an authorized password before processing.

Dependencies

Require PyMuPDF, Pillow, and python-pptx. Install missing packages only with user authorization when network access is required.