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
docs(create-template): define explicit SVG picture normalization
hugohe335f89f269545
diff --git a/AGENTS.md b/AGENTS.mdindex 20a5d7a4..a9cb6f73 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -71,6 +71,8 @@ python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --impython3 skills/ppt-master/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names a,b,c --trim --alphapython3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemonpython3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>+# Explicit create-template normalization: selected complex <g> -> one SVG picture asset / <image>+python3 skills/ppt-master/scripts/extract_svg_pictures.py "<svg_file>" --select "<group_id>" --resource-root "<workspace>" --images-dir "<workspace>/picture-assets" --inplace# create-template review deck (workspace root may be global or project-scoped)python3 skills/ppt-master/scripts/template_preview_pptx.py <template_workspace>python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animationdiff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.mdindex 129efe84..c825199c 100644--- a/docs/powerpoint-svg-mapping.md+++ b/docs/powerpoint-svg-mapping.md@@ -136,6 +136,7 @@ preset selection and authoring behavior are documented in| PowerPoint feature | Project representation | PPTX result | Import and fidelity | Validation boundary ||---|---|---|---|---|| Picture | `<image>` with explicit positive dimensions and exactly one project-asset or image data-URI source | `p:pic`, media part, and relationship | Reconstructed as `<image>` | Source must resolve, use a registered format, and contain decodable bytes matching its MIME/extension; invalid frames or media fail before packaging |+| Explicit complex-SVG picture | A direct `<image>` referencing a tight, self-contained `.svg` created from one exact `<g id>` by `extract_svg_pictures.py` during `create-template` normalization | One `p:pic` backed by SVG media | Reconstructed as one `<image>`; its internal paths are not promoted to separate PowerPoint shapes | Selection is explicit and limited to `standard` / `fidelity`; no import, repetition, Master/Layout, finalize, or export heuristic may convert a group into this representation automatically || Stretch picture to frame | `preserveAspectRatio="none"` | Stretched native picture frame | `Native-stable` | `none` must stand alone; it intentionally changes the source aspect ratio || Crop picture to fill | One registered alignment plus explicit `slice` | Native `a:srcRect` crop | `Native-stable` when source dimensions are readable | Alignment is case-sensitive; unknown modes and extra tokens are errors || Fit picture inside frame | Omitted default, or one registered alignment plus explicit `meet` | Native fitted picture frame | `Native-normalized` | Alignment-only shorthand is compatible input that receives a normalization recommendation |@@ -237,6 +238,7 @@ The importer reconstructs supported PowerPoint semantics into the same project v| Custom geometry | `<path>` || Text body | `<text>` and `<tspan>` runs/paragraphs || Picture | `<image>`, or the registered nested crop representation |+| SVG picture with raster compatibility fallback | `<image>` sourced from the `asvg:svgBlip` relationship; the ordinary `a:blip` relationship is used only when the SVG relationship or media part is unavailable || Connector | Expanded line/path preview plus connector/frame/topology evidence || Group | `<g>` || Supported native table/chart | Visible fallback plus native-object metadata |diff --git a/docs/zh/powerpoint-svg-mapping.md b/docs/zh/powerpoint-svg-mapping.mdindex e8ea9a96..7df53913 100644--- a/docs/zh/powerpoint-svg-mapping.md+++ b/docs/zh/powerpoint-svg-mapping.md@@ -131,6 +131,7 @@ PowerPoint 意图| PowerPoint 功能 | 项目表达 | PPTX 结果 | 回导与保真度 | 校验边界 ||---|---|---|---|---|| 图片 | 具有显式正尺寸且只含一个项目资产或图片 data URI 源的 `<image>` | `p:pic`、media part 与 relationship | 重建为 `<image>` | 源必须可解析、采用已登记格式,并包含与 MIME/扩展名相符的可解码字节;非法 frame 或媒体会在封装前失败 |+| 显式复杂 SVG 图片 | `create-template` 归一化期间,由 `extract_svg_pictures.py` 从一个精确 `<g id>` 生成紧边界、自包含 `.svg`,再以直接 `<image>` 引用 | 一个以 SVG media 为源的 `p:pic` | 回导为一个 `<image>`;内部 path 不会提升成独立 PowerPoint 形状 | 仅允许 `standard` / `fidelity` 显式选择;导入、重复检测、Master/Layout、finalize 与 export 均不得自动把组转换成这种表达 || 图片拉伸填满框 | `preserveAspectRatio="none"` | 原生拉伸 picture frame | `Native-stable` | `none` 必须单独出现;它会有意改变源宽高比 || 图片裁剪填充 | 一个已登记对齐值加显式 `slice` | 原生 `a:srcRect` 裁剪 | 源尺寸可读时为 `Native-stable` | 对齐值区分大小写;未知模式与额外 token 为 error || 图片适应框 | 省略时使用默认值,或一个已登记对齐值加显式 `meet` | 原生 fitted picture frame | `Native-normalized` | 仅写对齐值是兼容输入,Checker 会给出规范化建议 |@@ -232,6 +233,7 @@ sidecar 工作流见 [`animations.md`](../../skills/ppt-master/references/animat| 自定义几何 | `<path>` || 文本体 | `<text>` 与 `<tspan>` run/段落 || 图片 | `<image>`,或已登记嵌套 crop 表达 |+| 同时带栅格兼容预览的 SVG 图片 | 优先使用 `asvg:svgBlip` relationship 重建 `<image>`;仅当 SVG relationship 或 media part 不可用时才使用普通 `a:blip` relationship || 连接符 | expanded 线/path preview 加 connector/frame/topology 证据 || 组 | `<g>` || 受支持原生表格/图表 | 可见 fallback 加原生对象 metadata |diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex aa092f51..2dd834cc 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -45,7 +45,7 @@ python3 scripts/update_repo.py|------|-----------------|---------------|| Conversion | `source_to_md.py`, `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py`, `pptx_to_svg.py` | [docs/conversion.md](./docs/conversion.md) || Project management | `project_manager.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py` | [docs/project.md](./docs/project.md) |-| SVG pipeline | `preset_shape_svg.py`, `svg_authoring_view.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `animation_config.py`, `notes_to_audio.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native preset authoring](../references/native-shape-authoring.md) |+| SVG pipeline | `preset_shape_svg.py`, `svg_authoring_view.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `extract_svg_pictures.py`, `animation_config.py`, `notes_to_audio.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native preset authoring](../references/native-shape-authoring.md) || PPTX transitions | `pptx_transitions.py` | [docs/pptx-transitions.md](./docs/pptx-transitions.md) || PPTX animations | `pptx_animations.py`, `animation_config.py` | [docs/pptx-animations.md](./docs/pptx-animations.md) || Spec maintenance | `update_spec.py` | [docs/update_spec.md](./docs/update_spec.md) |@@ -146,10 +146,16 @@ the normative contract and[`references/native-shape-authoring.md`](../references/native-shape-authoring.md)for selection and authoring guidance.-Post-processing and export:+Create-template/source normalization (optional; never part of automatic export):```bashpython3 scripts/extract_svg_assets.py <svg_dir> --icons-dir <icons_dir> --inplace --id-prefix <prefix> # optional: shrink imported/reference SVGs before AI review+python3 scripts/extract_svg_pictures.py "<svg_file>" --select "<group_id>" --resource-root "<workspace>" --images-dir "<picture_assets_dir>" --inplace # optional create-template normalization: one selected group -> one SVG picture+```++Post-processing and export:++```bashpython3 scripts/total_md_split.py <project_path>python3 scripts/finalize_svg.py <project_path>python3 scripts/svg_to_pptx.py <project_path>diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex 2a5c8ee5..0fc465db 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -247,6 +247,14 @@ python3 scripts/pptx_to_svg.py deck.pptx --strict| `layered` | Only the layered `svg/` view and inheritance metadata || `flat` | One self-contained slide SVG per page under `svg/` |+For Office pictures that carry both a raster compatibility preview on+`a:blip` and an editable SVG relationship in `asvg:svgBlip`, import resolves+the SVG relationship first. The raster relationship is used only when the SVG+relationship or media part cannot be read. The template manifest uses the same+relationship preference for asset identity; its existing missing-media gate+remains strict rather than silently treating the raster preview as the+template's canonical asset.+Import is tolerant by default because the source deck is user-owned or comesfrom third-party authoring tools. Recovery happens at the narrowest safeboundary: first omit only an unsupported property or feature; if that is notdiff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 286838f9..912744f6 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -48,6 +48,54 @@ is owned by [`shared-standards.md`](../../references/shared-standards.md), withauthoring guidance in[`native-shape-authoring.md`](../../references/native-shape-authoring.md).+## `extract_svg_pictures.py`++Normalize one deliberately selected complex SVG object into one PowerPoint+picture. The command accepts exact `<g id>` values only, writes each group as a+tight standalone SVG asset, embeds its local image/CSS dependencies, and+replaces the source group at the same parent index with one `<image>`. Native+export therefore emits one `p:pic` backed by SVG media.++```bash+python3 scripts/extract_svg_pictures.py \+ "<workspace>/authoring-svg/<layered_svg_file>.svg" \+ --select "<group_id>" \+ --resource-root "<workspace>" \+ --images-dir "<workspace>/picture-assets" \+ --inplace+```++Imported PowerPoint groups normally provide `data-pptx-frame`, which is used+as the picture bounds. For a large standalone SVG without frame metadata, the+tool measures the selected group with Playwright; use repeated+`--bounds ID=x,y,width,height` values when browser measurement is unavailable+or when effect overflow needs an explicit frame. `--padding` expands the+chosen bounds. The generated `*_picture_asset_inventory.json` records the+bounds source, asset hash, copied definition ids, and embedded local resources.+Nested selections are accepted only through metadata-only `<g>` ancestors.+When an ancestor carries a transform, style, clip, opacity, or other visual+attribute, select that outer group instead; this prevents applying the ancestor+effect once inside the SVG asset and again to the replacement `<image>`.+Scripts, `foreignObject`, SVG animation, remote resources, and external SVG+fragment references fail closed; local image/CSS resources must stay inside+the declared `--resource-root` and are embedded into the asset.++This operation belongs only to an explicit `create-template` normalization+decision in `standard` or `fidelity` mode. It does not choose groups, detect+repetition, infer a Master/Layout, or run during ordinary import, free+generation, mirror restoration, finalize, or export. Placeholder, native+single-shape, table/chart, icon-placeholder, and authored-preset groups are+rejected because they already own a different semantic route.++Do not confuse this tool with `extract_svg_assets.py`:++- `extract_svg_assets.py` is a model-readability optimization. It replaces+ heuristic vector runs with `<use data-icon>`, then re-inlines them before+ export so the PPTX still contains native shapes.+- `extract_svg_pictures.py` is an explicit representation change. It replaces+ only named groups with `<image>`, so each result intentionally remains one+ editable PowerPoint picture rather than individually editable paths.+## Recommended PipelineRun these steps in order:diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.mdindex 3df1c4f6..b2d83c43 100644--- a/skills/ppt-master/workflows/create-template.md+++ b/skills/ppt-master/workflows/create-template.md@@ -151,6 +151,45 @@ python3 skills/ppt-master/scripts/extract_svg_assets.py "<import_workspace>/authThe projected SVGs in `<import_workspace>/authoring-svg/` / `<import_workspace>/authoring-svg-flat/` are rewritten in place with compact `<use data-icon="..."/>` placeholders. Extracted assets live directly under `<import_workspace>/icons/`; `icons/` must contain only icon/vector assets, not rewritten page SVGs or inventories. The inventory is written beside the processed projection directory. The existing icon embedding path re-inlines the extracted assets before final export, preserving multi-color artwork and non-square viewBox geometry as native SVG shapes. Text-bearing groups are never extracted; text must stay readable/editable in the working SVG. Extraction triggers on either many drawable elements or a large pure-vector XML block, so long single-path illustrations are factored out too. Pure-vector decoration runs inside text-bearing groups use a lower size threshold, allowing card borders and decorative paths to be extracted without hiding text. Referenced defs (`gradient` / `pattern` / `filter` / `clipPath` / `marker`) are copied into each asset and namespaced so the asset is self-contained after re-inline. If both layered and flat views are processed into the same icon directory, keep distinct `--id-prefix` values to avoid asset ID collisions. `--clean-stale` removes only stale generated assets for the current SVG filenames and prefix; it is safe in this import workspace but should not be used against a shared hand-curated icon directory without a specific prefix.+**Explicit complex-SVG picture normalization (optional; `standard` / `fidelity` only)**:++When one imported native group is deliberately being retained as one complex+SVG picture rather than rebuilt as editable paths, select its exact id in the+lightweight projection and normalize it explicitly:++```bash+python3 skills/ppt-master/scripts/extract_svg_pictures.py \+ "<import_workspace>/authoring-svg/<layered_svg_file>.svg" \+ --select "<group_id>" \+ --resource-root "<import_workspace>" \+ --images-dir "<import_workspace>/picture-assets" \+ --inplace+```++Repeat `--select` for multiple independent sibling groups. The tool uses an+imported `data-pptx-frame` when present; otherwise it measures the target with+Playwright, or accepts `--bounds ID=x,y,width,height`. It creates a tight,+self-contained SVG under `picture-assets/`, embeds reachable local resources,+and replaces the group at the same z-order with one `<image>`. If the object is+chosen for a final Master or Layout, copy that asset into the project image+pool and author the final fixed atom as a direct `<image>` with+`data-pptx-layer="master|layout"`; export then creates one `p:pic`.+Nested targets are allowed only below metadata-only grouping wrappers. If an+ancestor carries a transform, style, clip, opacity, or other visual attribute,+select that outer group so the effect is not applied twice.++This is a semantic representation decision, not an import heuristic. Never run+it automatically, never select groups by repetition, and never use it to infer+Master/Layout ownership. Do not apply it to placeholders, individual imported+native shapes, native table/chart fallbacks, icon placeholders, or compact+authored presets. `mirror` must keep the source native group/picture identity+and therefore must not use this normalization. The original lossless `svg/`+and `svg-flat/` trees remain unchanged and authoritative.++`extract_svg_assets.py` remains a different operation: it factors vectors out+for model readability and re-inlines them as native shapes before export. It+does not turn those vectors into a picture.+**Read order during analysis**:| Mode | Required read set |@@ -214,6 +253,13 @@ python3 skills/ppt-master/scripts/svg_authoring_view.py "<normalized_svg_source>python3 skills/ppt-master/scripts/extract_svg_assets.py "<svg_analysis_workspace>/authoring-svg" --icons-dir "<svg_analysis_workspace>/icons" --inplace --id-prefix source --min-decoration-bytes 3000 --clean-stale```+If the source contains one deliberately selected complex subtree that should+remain a single SVG picture, apply the explicit normalization above only to the+analysis projection. Set `--resource-root` to the narrowest workspace directory+that contains both the projection and every local dependency referenced by the+selected group. This does not authorize automatic group selection or mutation+of the user's original SVG directory.+Then `ls` the analysis workspace and `Read` every cleaned `authoring-svg/*.svg` to extract:- canvas size (`viewBox` on the root `<svg>`)