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

docs(create-template): define explicit SVG picture normalization

hugohe335f89f269545
diff --git a/AGENTS.md b/AGENTS.md
index 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 --im
python3 skills/ppt-master/scripts/slice_images.py <project_path>/images/<sheet>.png --grid RxC --names a,b,c --trim --alpha
python3 skills/ppt-master/scripts/svg_editor/server.py <project_path> --live --daemon
python3 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 animation
diff --git a/docs/powerpoint-svg-mapping.md b/docs/powerpoint-svg-mapping.md
index 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.md
index 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.md
index 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):
```bash
python3 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:
+
+```bash
python3 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.md
index 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 comes
from third-party authoring tools. Recovery happens at the narrowest safe
boundary: first omit only an unsupported property or feature; if that is not
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 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), with
authoring 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 Pipeline
Run these steps in order:
diff --git a/skills/ppt-master/workflows/create-template.md b/skills/ppt-master/workflows/create-template.md
index 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>/auth
The 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>`)