wiltonesten-web/codeximage-to-editable-ppt-v1/codeximage-to-editable-ppt-v1

V1 Direct Refined Image-PPT-to-Editable-PPT Skill

Scope and positioning

This skill is designed specifically for image-based PPT/PPTX files and slide screenshots. In this context, an image-based PPT means each slide is mainly or entirely composed of one full-slide raster image, a screenshot, or multiple raster layers. The goal is not to recover original PowerPoint vector objects. The goal is to:

1. extract or render each raster slide page at high quality;
2. visually decompose the raster page into independent PNG elements;
3. identify text-only PNG elements;
4. export all PNG elements into page-level folders;
5. generate a detailed manifest;
6. rebuild a PPTX from independent PNG elements plus editable text boxes and native PowerPoint shapes.

Do not optimize this skill for native-object PPT recovery. This skill assumes the visible slide is a raster image that must be decomposed visually.

V1 is more opinionated than the baseline optimized skill: the direct OCR-based recomposed_from_elements.pptx is not the primary deliverable. It is a reference and backup artifact. The primary deliverable is a refined editable rebuild.

Core workflow

Use this staged workflow:

V1 direct refined rebuild contract

For every input slide, produce a refined editable rebuild as the primary result whenever practical. Do this regardless of whether the slide is English, Chinese, mixed-language, or mostly visual.

The default V1 behavior is:

1. Run baseline decomposition first to create source pages, element crops, review overlays, manifests, and a rough recomposed PPTX.
2. Inspect the baseline manifest, review overlay, and rough recomposed preview if available.
3. Do not hard-convert unreliable OCR text into the final deck. Use the source image as the visual ground truth.
4. Crop complex graphics, icons, diagrams, scientific illustrations, photos, logos, and expensive-to-redraw chart artwork as independent PNG elements.
5. Recreate titles, labels, descriptions, captions, legends, coordinate labels, axis labels, table text, and other readable text as editable PowerPoint text boxes.
6. Rebuild simple structure with native PowerPoint objects: page backgrounds, panels, rounded rectangles, straight lines, dashed dividers, arrows, color blocks, chart axes, ticks, bars, badges, table/grid borders, and simple symbols.
7. Export a PowerPoint-rendered preview of the refined PPTX.
8. Adjust font size, text-box width, position, line breaks, and object geometry until severe overlap, clipping, and ugly wrapping are resolved.
9. Write the full artifact bundle: refined PPTX, source page, split PNG elements, ZIP, manifest CSV/JSON, review overlay, quality preview, diff image, and quality report.

Only skip the refined rebuild when the user explicitly asks for automatic decomposition only, dry-run planning, or raw element extraction without PPTX polishing.

Language and OCR capability gate

Before trusting OCR output for editable text conversion, explicitly check whether the local OCR runtime can recognize the slide language.

1. Inspect the input visually or from filenames/context for the dominant text language.
2. Check available OCR languages, for example with pytesseract.get_languages(config="") when using Tesseract.
3. If the slide contains Chinese text but chi_sim or another suitable Chinese OCR package is unavailable, mark OCR as insufficient for Chinese text.
4. In that case, still run baseline decomposition for visual element discovery, source-page export, element crops, review overlays, and manifests, but do not rely on OCR-recognized Chinese text for the final editable PPTX.
5. Prefer a refined editable rebuild: use the raster slide as the visual reference, crop complex artwork as independent PNG elements, and manually or programmatically recreate the Chinese text as editable PowerPoint text boxes.
6. Record the reason in the manifest and quality notes, for example ocr_language_missing_chi_sim, manual_text_reconstruction, or ocr_gibberish_replaced.

Failure triggers that require refined rebuild instead of direct OCR recomposition:

• recognized text is mostly gibberish, romanized fragments, punctuation, or unrelated English;
• multiple unrelated text zones are merged into one large OCR element;
• text is merged with icons, charts, tables, or decorative backgrounds;
• Chinese text is present but the OCR runtime only exposes eng/osd;
• PowerPoint preview shows severe wrapping, overlap, or clipped editable text;
• chart labels, axis labels, captions, or legends are too small or dense for reliable OCR.

Refined editable rebuild workflow as the default final output

For any language, including English and Chinese, do not treat the direct OCR-based recomposed PPTX as the final result by default. Produce two outputs whenever practical:

1. the baseline automated output from decompose_visual_elements.py;
2. a curated *_refined_editable.pptx and matching *_refined_editable_output/ folder.

The refined rebuild must follow this pattern:

1. Run baseline decomposition first with review outputs enabled.
2. Inspect visual_elements_manifest.csv, the detected-element overlay, and, when possible, a PowerPoint-exported PNG preview.
3. Define the slide's visual regions: title/header, panels, tables, charts, legends, icons, figures, captions, footers, and decorative lines.
4. Do not hard-convert unreliable OCR text into editable text. Use the source image as ground truth, and use OCR only as an aid when it is visibly correct.
5. Crop complex graphics, icons, diagrams, photos, logos, scientific illustrations, and expensive-to-redraw chart artwork as independent PNG elements.
6. Rebuild titles, labels, captions, descriptions, coordinate/axis labels, legends, table text, and other readable text as editable PowerPoint text boxes.
7. Rebuild simple design structure as editable PowerPoint objects: backgrounds, panels, rounded rectangles, lines, dashed dividers, arrows, chart axes, bars, color blocks, table/grid borders, badges, labels, and simple symbols.
8. Preserve wording, line breaks, approximate alignment, color, and hierarchy.
9. For Chinese text, default to a common CJK-capable font such as Microsoft YaHei, SimHei, or the closest font already used by the deck. Use conservative font sizes because PowerPoint export often renders CJK text larger than screenshot pixels imply.
10. For English text, still inspect OCR output and preview rendering. If OCR text is wrong, merged, clipped, or badly wrapped, manually or programmatically reconstruct it as editable text from the source image.
11. Export a rendered preview of the rebuilt PPTX, inspect it visually, then adjust font scale, text-box width, line breaks, and object positions until there is no severe overlap or clipping.
12. Write the same artifact family as the baseline workflow: source page, split PNG elements, ZIP, CSV/JSON manifest, review overlay, quality preview, diff image, and quality report.
13. Name the refined deck and folder predictably, for example slide_08_refined_editable.pptx and slide_08_refined_editable_output/.

The refined rebuild is the primary V1 deliverable. Do not present a direct OCR-based PPTX as the primary result unless the user explicitly asks for automatic output only.

Recommended implementation pattern for refined rebuilds

When using Python and python-pptx, use a deterministic per-slide rebuild script so that edits can be repeated and improved.

The script should:

• define the source image size and target PowerPoint slide size;
• provide pixel-to-EMU conversion helpers;
• crop complex visual assets into split_png_elements/<page_id>/;
• insert those crops as independent pictures, not as one full-slide screenshot;
• create editable text boxes for reliable or manually reconstructed text;
• create editable PowerPoint shapes for panels, dividers, arrows, chart bars, badges, and simple icons when feasible;
• write visual_elements_manifest.csv and .json with the same minimum fields as the normal workflow;
• create a review overlay with element bounding boxes;
• export or accept a PowerPoint-rendered preview and write a lightweight diff-based quality report;
• keep the script beside the task output only when it helps reproducibility.

Use manual text reconstruction only for text that can be read from the source image or from a user-provided reference. If text is unreadable, keep it as PNG and mark manual_review_required.

For the detailed checklist and implementation pattern, read references/refined_rebuild_workflow.md before performing a refined rebuild.

Batch processing contract

When the user asks to process multiple files, a folder, repeated batches, or any task that may require more than one decomposition run, do not rely on conversation memory to remember batch parameters or manually loop over commands.

Use scripts/run_batches.py as the batch entrypoint. If the requested batch behavior is not supported yet, modify scripts/run_batches.py first, then run it. Keep batch behavior in the script rather than in ad hoc chat instructions.

The batch runner must:

1. collect input files from explicit file paths or input directories;
2. group inputs into batches of two files by default (--batch-size 2);
3. create one stable batch folder per batch group, such as batch_001_2_items/;
4. automatically write exactly one fixed-template batch_instruction.md inside each batch folder before execution;
5. write the batch instruction with the batch rules, the input list, one shared parameter block, one command per input item, expected outputs, and status fields;
6. execute item commands through the global worker pool rather than sequentially;
7. write batch_run.log for each batch;
8. write batch_summary.csv and batch_summary.json at the batch root.
9. after all item runs succeed, merge every item recomposed_from_elements.pptx into merged_recomposed_from_elements.pptx at the batch root, strictly following the original input order, not parallel completion order.

Default parallelism:

• --batch-size 2: put two input files in each batch.
• --batch-workers 2: keep at most two batches active at the same time.
• --workers: max concurrent item processes. If omitted, compute it as batch-size * batch-workers, so the default is 4 concurrent item processes.
• Preserve batch-level organization even when item execution is parallel: each batch still has one batch_instruction.md and one batch_run.log.
• Final merge is enabled by default. Use --no-merge only when the user explicitly does not want a combined deck.

Default command pattern:

python scripts/run_batches.py input_folder_or_files \
  --outdir batch_output \
  --batch-size 2 \
  --batch-workers 2 \
  --dpi 300 \
  --granularity fine \
  --ocr \
  --ocr-lang chi_sim+eng \
  --ocr-confidence-threshold 75 \
  --editable-text \
  --review \
  --quality-check

For planning or QA without running decomposition, use --dry-run. This still generates every batch_instruction.md and the batch summary.

Final merged output:

• merged_recomposed_from_elements.pptx: combined deck at the batch root.
• merge_report.csv and merge_report.json: ordered merge audit showing each input item, item PPTX path, manifest path, inclusion status, and slide count.

Stage 1 - Input inspection and page source extraction