面向景观、建筑与室内精装修文本制作的 PowerPoint / WPS 演示图片原位替换加载项。
Picture Replace Tools 解决一个高频且耗时的制作问题：同一张方案图、效果图、材质图或分析图被放入多页 PPT 后，每页通常有不同的裁剪、构图、尺寸、旋转和图层关系。常规替换图片会破坏这些已经调好的版式，设计师只能逐页重新裁剪。
本加载项可将新图放回原位，并保留每个页面各自的裁剪效果；也可以从任意一个实例出发，一键替换当前演示文稿中全部同源图片。
项目同时提供两个宿主版本：PowerPoint 使用 VBA/PPAM；WPS 演示使用独立的 JavaScript wpp 加载项。两者共享相同的裁剪保护思路，但不把 PPAM 冒充成 WPS 插件。
选中一张图片并选择新文件，加载项会保留：
- 位置、显示尺寸与旋转；
- 水平/垂直翻转；
- 层级、形状名称和替代文字；
- 裁剪框、裁剪焦点与可见画面；
- 线条、阴影等常见形状格式。
当新旧图片宽高比接近时，裁剪几何会精确复用；宽高比差异明显时，使用 Cover 方式铺满原裁剪框，并尽可能保留原来的视觉焦点。
选中任意一个图片实例，点击“批量替换同图”，选择新图片。加载项会扫描当前 PPT 的全部幻灯片，识别使用同一原图的图片实例，并分别保留它们自己的裁剪与版式。
识别不依赖文件名或形状名：插件导出无裁剪预览，处理水平/垂直翻转，并使用 Windows WIA 将预览统一为 32×32 像素网格。严格字节匹配失败时，会以极小容差消除 PowerPoint 的像素取整误差；尺寸相同但内容不同的图片不会被替换。
- PowerPoint 和 WPS 均支持从剪贴板读取图片、截图或可粘贴为图片的对象。
- 单张模式保留当前图片的原位信息；批量模式把剪贴板图片作为新素材，替换全部同源实例。
- 剪贴板内容只在本机临时栅格化为 PNG，不上传素材；为空或格式不支持时安全失败，不删除目标图片。
- 总平面、分区放大、节点设计和效果图页可共用同一张底图，但每页展示不同区域；更新总图后，无需重新框选每一个节点。
- 植物意向、铺装、雨洪、慢行与场地分析图经常反复出现；替换新版图纸时可保持既有页面构图与版式节奏。
- 鸟瞰、总平、流线、功能分区、立面和节点页对同一素材有不同裁剪逻辑；批量更新可避免漏改某一页。
- 方案迭代频繁时，可将“改图后逐页排版”的重复劳动收敛为一次替换和一次视觉复核。
- 效果图、材料图、样板间摄影和节点详图常被多个空间页复用；保持每页原有的裁剪焦点，避免家具、墙面或材质展示偏移。
- 当供应商更新材质贴图、深化团队更新效果图时，版式人员无需重新恢复每个页面的视觉重点。
- 从 GitHub Release 下载
PictureReplaceTools.ppam。 - 关闭 PowerPoint，移除旧版同名加载项。
- 打开“文件 → 选项 → 加载项”。
- 在底部选择“PowerPoint 加载项”，点击“转到”。
- 点击“添加新项”，选择下载的
.ppam文件。 - 重启 PowerPoint；功能区将出现“图片工具”选项卡。
PowerPoint 会缓存已加载的 VBA。更新版本时必须先关闭 PowerPoint 并移除旧加载项。
WPS 版位于 wps_addin，遵循 WPS 官方 ribbon.xml + main.js 规范。开发调试需要 WPS Windows、Node.js 和 wpsjs：
cd wps_addin
npm install
npm run debug正式发布使用 npm run publish 生成 publish.html 与部署包。WPS 新版本推荐 publish.xml 流程；当前开发机未安装 WPS，因此 WPS 剪贴板与 FileSystem 仍需在目标 WPS 实机验收。
| 目标 | 操作 |
|---|---|
| 替换当前图片 | 选中单张图片 → 图片工具 → 原位替换图片 → 选择新图片 |
| 替换整份 PPT 的同一原图 | 选中任意实例 → 图片工具 → 批量替换同图 → 选择新图片 |
| 从剪贴板替换当前图片 | 复制图片/截图 → 选中目标 → 图片工具 → 剪贴板原位替换 |
| 从剪贴板批量替换 | 复制新图片 → 选中任意原图实例 → 图片工具 → 批量用剪贴板替换 |
- 所有识别、图片选择和替换都在本机 PowerPoint 中完成。
- 插件不上传 PPT、图片或素材，不需要网络连接。
- 批量识别仅扫描当前打开的演示文稿。
- 组合对象内部的图片暂不替换，完成提示会报告跳过的组合数量。
- 强艺术效果、透明度蒙版、复杂图片校正可能改变预览像素，导致同源图片被保守地跳过。
- 批量替换逐张执行；极少数形状替换失败时，已成功的项目不会自动回滚，提示会显示成功/失败数量。
- 含大量图片的长文档需要更多扫描时间；建议替换后快速浏览缩略图进行视觉复核。
| 文件 | 作用 |
|---|---|
modPictureReplace.bas |
加载项 VBA 核心逻辑 |
customUI.xml |
Ribbon“图片工具”选项卡 |
build_ppam.ps1 |
注入 VBA、打包并校验 PPAM |
inject_customui.py |
安全注入 Ribbon XML，避免 ZIP 包损坏 |
test_addin.ps1 |
合成场景端到端测试入口 |
test_real_deck.vbs |
对真实 PPTX 的批量识别回归测试 |
wps_addin/ |
WPS 演示 JavaScript 加载项源码与发布配置 |
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\build_ppam.ps1产物位于 dist\PictureReplaceTools.ppam。正式版本应作为 GitHub Release 附件发布，不应提交到源码仓库。
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\test_addin.ps1
cscript.exe //nologo .\test_real_deck.vbs <你的PPTX路径>合成回归覆盖：普通裁剪、宽高比变化、失败回滚、翻转、层级、多页同源批量替换、干扰图排除、剪贴板单张/批量替换、PPAM 加载与导出像素验证。
当前 Release 包已通过：
- PPAM ZIP 结构校验；
- PowerPoint 加载与宏执行；
- 合成端到端回归；
- 真实 PPTX 回归：3 个同源实例全部命中，不同图片不替换。
- WPS JS 加载项源码已完成静态校验；WPS 实机端到端尚待安装 WPS 的 Windows 环境验证。