Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

feat(svg_to_pptx): add optional conversion trace

hugohe31e7cf24c0578
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
index cc132fb8..36476c9e 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_context.py
@@ -3,6 +3,7 @@
from __future__ import annotations
from pathlib import Path
+from typing import Any
from xml.etree import ElementTree as ET
from dataclasses import dataclass, field
@@ -50,6 +51,9 @@ class ConvertContext:
# editable text frame with multiple <a:p>. Off preserves the original
# one-line-per-textbox behavior and the SVG's exact pixel layout.
merge_paragraphs: bool = False
+ # Optional per-element conversion diagnostics. Shared by child contexts so
+ # callers can inspect native / skipped / unsupported decisions per slide.
+ trace_events: list[dict[str, Any]] | None = None
def next_id(self) -> int:
"""Allocate the next shape ID."""
@@ -150,6 +154,7 @@ class ConvertContext:
# anim_targets is intentionally a fresh list on the child;
# only the root-level context's list is read by the builder.
merge_paragraphs=self.merge_paragraphs,
+ trace_events=self.trace_events,
)
def sync_from_child(self, child_ctx: ConvertContext) -> None:
diff --git a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
index 09d13fed..8fb5438e 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/drawingml_converter.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import math
import re
from pathlib import Path
+from typing import Any
from xml.etree import ElementTree as ET
from .drawingml_context import ConvertContext, ShapeResult
@@ -347,17 +348,44 @@ def collect_defs(root: ET.Element) -> dict[str, ET.Element]:
def convert_element(elem: ET.Element, ctx: ConvertContext) -> ShapeResult | None:
"""Dispatch an SVG element to the appropriate converter."""
tag = elem.tag.replace(f'{{{SVG_NS}}}', '')
+ elem_id = elem.get('id')
+
+ def trace(decision: str, **metadata: Any) -> None:
+ if ctx.trace_events is None:
+ return
+ event: dict[str, Any] = {
+ 'tag': tag,
+ 'decision': decision,
+ }
+ if elem_id:
+ event['id'] = elem_id
+ event.update(metadata)
+ ctx.trace_events.append(event)
converter = _CONVERTERS.get(tag)
if converter:
try:
- return converter(elem, ctx)
+ result = converter(elem, ctx)
except Exception as e:
+ trace('error', error=str(e))
raise SvgNativeConversionError(f'Failed to convert <{tag}>: {e}') from e
+ if result:
+ shape_match = re.search(r'<p:cNvPr id="(\d+)"', result.xml)
+ metadata: dict[str, Any] = {}
+ if shape_match:
+ metadata['shape_id'] = int(shape_match.group(1))
+ if result.bounds_emu is not None:
+ metadata['bounds_emu'] = list(result.bounds_emu)
+ trace('native', **metadata)
+ else:
+ trace('skip', reason='empty-or-non-rendering')
+ return result
if tag in _NON_VISUAL_TAGS:
+ trace('skip', reason='non-visual')
return None
+ trace('unsupported')
raise SvgNativeConversionError(f'Unsupported visual SVG element <{tag}>')
@@ -392,6 +420,7 @@ def convert_svg_to_slide_shapes(
slide_num: int = 1,
verbose: bool = False,
merge_paragraphs: bool = False,
+ trace_out: list[dict[str, Any]] | None = None,
) -> tuple[str, dict[str, bytes], list[dict[str, str]], list]:
"""Convert an SVG file to a complete DrawingML slide XML.
@@ -403,6 +432,7 @@ def convert_svg_to_slide_shapes(
(same x, dy clustered around one base line-height) become a
single editable text frame with multiple <a:p>. Default False
preserves the SVG's exact line layout (one textbox per line).
+ trace_out: Optional list populated with one per-slide trace dictionary.
Returns:
(slide_xml, media_files, rel_entries, anim_targets) where:
@@ -415,6 +445,8 @@ def convert_svg_to_slide_shapes(
"""
tree = ET.parse(str(svg_path))
root = tree.getroot()
+ trace_events: list[dict[str, Any]] | None = [] if trace_out is not None else None
+ trace_steps: list[dict[str, Any]] = []
# Expand <use data-icon="..."/> placeholders in-memory so this dispatcher
# can consume svg_output/ directly. Standard renderers and this converter
@@ -425,6 +457,8 @@ def convert_svg_to_slide_shapes(
if icons_dir.exists():
from .use_expander import expand_use_data_icons
expanded = expand_use_data_icons(root, icons_dir)
+ if expanded:
+ trace_steps.append({'action': 'expand-use-data-icons', 'count': expanded})
if verbose and expanded:
print(f' Expanded {expanded} <use data-icon="..."/> placeholder(s)')
@@ -437,8 +471,14 @@ def convert_svg_to_slide_shapes(
# merge_paragraphs (opt-in) additionally folds mergeable paragraph blocks
# into a single annotated <text> for downstream multi-<a:p> conversion.
from .tspan_flattener import flatten_positional_tspans
- if flatten_positional_tspans(tree, merge_paragraphs=merge_paragraphs) and verbose:
- print(' Flattened positional <tspan> into independent <text>')
+ flattened = flatten_positional_tspans(tree, merge_paragraphs=merge_paragraphs)
+ if flattened:
+ trace_steps.append({
+ 'action': 'flatten-positional-tspans',
+ 'merge_paragraphs': merge_paragraphs,
+ })
+ if verbose:
+ print(' Flattened positional <tspan> into independent <text>')
unsupported = _collect_unsupported_visuals(root)
if unsupported:
@@ -454,6 +494,7 @@ def convert_svg_to_slide_shapes(
slide_num=slide_num,
svg_dir=Path(svg_path).parent,
merge_paragraphs=merge_paragraphs,
+ trace_events=trace_events,
)
shapes: list[str] = []
@@ -491,6 +532,21 @@ def convert_svg_to_slide_shapes(
if verbose:
print(f' Converted {converted} elements, skipped {skipped}')
+ if trace_out is not None:
+ trace_out.append({
+ 'slide_num': slide_num,
+ 'svg': str(svg_path),
+ 'summary': {
+ 'converted': converted,
+ 'skipped': skipped,
+ 'media_files': len(ctx.media_files),
+ 'relationships': len(ctx.rel_entries),
+ 'animation_targets': len(ctx.anim_targets),
+ },
+ 'preprocess': trace_steps,
+ 'events': trace_events or [],
+ })
+
shapes_xml = '\n'.join(shapes)
slide_xml = f'''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
index a9ab7f83..7a4c883b 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import hashlib
+import json
import mimetypes
import os
import re
@@ -307,6 +308,7 @@ def create_pptx_with_native_svg(
cache_dir: Path | None = None,
workers: int | None = None,
merge_paragraphs: bool = False,
+ conversion_trace_path: Path | None = None,
) -> bool:
"""Create a PPTX file with native SVG.
@@ -334,6 +336,7 @@ def create_pptx_with_native_svg(
narration_audio: Optional dict mapping SVG stem to narration audio file.
use_narration_timings: Whether to set slide auto-advance from audio duration.
narration_padding: Extra seconds added after each narration before advancing.
+ conversion_trace_path: Optional JSON path for native conversion diagnostics.
Returns:
Whether all slides were successfully created.
@@ -446,6 +449,7 @@ def create_pptx_with_native_svg(
narration_slides_created: set[int] = set()
audio_exts_used: set[str] = set()
mixed_animation_offset = 0
+ conversion_trace: list[dict[str, Any]] | None = [] if conversion_trace_path else None
for i, svg_path in enumerate(svg_files, 1):
slide_num = i
@@ -458,6 +462,7 @@ def create_pptx_with_native_svg(
convert_svg_to_slide_shapes(
svg_path, slide_num=slide_num, verbose=verbose,
merge_paragraphs=merge_paragraphs,
+ trace_out=conversion_trace,
)
)
slide_transition, slide_transition_duration, slide_auto_advance = (
@@ -803,9 +808,23 @@ def create_pptx_with_native_svg(
zf.write(file_path, arcname)
shutil.move(str(temp_output_path), str(output_path))
+ if conversion_trace_path and conversion_trace is not None:
+ conversion_trace_path.parent.mkdir(parents=True, exist_ok=True)
+ payload = {
+ 'output': str(output_path),
+ 'slide_count': len(svg_files),
+ 'slides': conversion_trace,
+ }
+ conversion_trace_path.write_text(
+ json.dumps(payload, ensure_ascii=False, indent=2),
+ encoding='utf-8',
+ )
+
if verbose:
print()
print(f"[Done] Saved: {output_path}")
+ if conversion_trace_path and conversion_trace is not None:
+ print(f" Trace: {conversion_trace_path}")
print(f" Succeeded: {success_count}, Failed: {len(svg_files) - success_count}")
if use_compat_mode and has_any_image:
print(f" Mode: Office compatibility mode (supports all Office versions)")
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
index 5725de59..c6cce244 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
@@ -158,6 +158,10 @@ Recorded narration:
'PowerPoint (one textbox per paragraph instead of per line) at '
'the cost of strict SVG line layout fidelity — PowerPoint re-wraps '
'merged paragraphs to fit the box width. Off by default.')
+ parser.add_argument('--conversion-trace', action='store_true', default=False,
+ help='Write a JSON diagnostics report next to the native PPTX '
+ '(<output>.trace.json). Records per-slide SVG element '
+ 'conversion decisions for debugging.')
parser.add_argument('--svg-snapshot', action='store_true', default=False,
help='Also emit the SVG-rendered snapshot pptx alongside the native pptx in exports/ '
'(named <project>_<ts>_svg.pptx). Off by default — the native pptx is the '
@@ -513,6 +517,10 @@ Recorded narration:
output_path=native_path,
use_native_shapes=True,
svg_files=native_files,
+ conversion_trace_path=(
+ native_path.with_name(native_path.name + '.trace.json')
+ if args.conversion_trace else None
+ ),
**shared_kwargs,
)
success = success and ok