---

name: images-to-ppt

description: 把图片文件夹转换为「一页一图」的 PPTX。当用户要求"上传/提供一个图片文件夹并生成 PPT"、"把文件夹里的图片做成 PPT"、"图片批量转 PPT"、"一张图一张幻灯片"时使用本技能。支持 png/jpg/jpeg/bmp/gif/webp/tif/tiff，图片按文件名自然顺序排列（img2 在 img10 之前），每张图片独占一页、保持宽高比居中铺满。

---



# Images To Ppt



## Overview



将用户提供的图片文件夹转换为完整 PPTX：每张图片一页幻灯片，按文件名顺序排列，图片保持原始宽高比、等比缩放居中铺满页面（等价于 PowerPoint「适应幻灯片」）。由 `scripts/images_to_ppt.py` 完成转换，脚本已处理格式兼容（webp 自动转 PNG）。



## Workflow



1. **确认输入**：获取图片文件夹路径。若用户未提供路径，先请其提供；不要编造路径。

2. **检查依赖**：脚本需要 `python-pptx` 与 `pillow`。运行前先验证可用环境：

   ```bash

   python -c "import pptx, PIL" 2>/dev/null && echo OK || pip install python-pptx pillow

   ```

   Windows 下建议使用受管 Python 环境（见本机二进制目录），避免污染系统环境。

3. **运行脚本**：

   ```bash

   python scripts/images_to_ppt.py <图片文件夹> <输出.pptx> [选项]

   ```

   不传输出路径时，默认输出到文件夹同级、与文件夹同名的 `.pptx`。

4. **验证输出**：用 python-pptx 读取生成的 pptx，确认：(a) 页数 = 图片数（若加了标题页则 +1）；(b) 每页恰好 1 张图片；(c) 图片顺序与文件名顺序一致。

5. **交付**：用 `present_files` 展示生成的 `.pptx`，并简要说明页数、比例与排序规则。



## Script Usage



```bash

python images_to_ppt.py <图片文件夹> [输出.pptx] \

    [--size 16:9|4:3] \

    [--background #RRGGBB] \

    [--page-numbers] \

    [--margin 英寸] \

    [--title 文本]

```



| 参数 | 说明 | 默认 |

|---|---|---|

| `--size` | 幻灯片比例 | `16:9` |

| `--background` | 背景色（3/6 位十六进制，可带 `#`） | `FFFFFF` |

| `--page-numbers` | 每页右下角显示 `n / N` 页码 | 关闭 |

| `--margin` | 图片与页面边缘留白（英寸） | `0.0` |

| `--title` | 可选，首张图片页前插入一张标题页 | 无 |



### 常用场景



- 默认转换（16:9、白底、图片铺满）：

  ```bash

  python images_to_ppt.py ./photos ./photos.pptx

  ```

- 4:3 比例 + 页码，适合打印：

  ```bash

  python images_to_ppt.py ./photos ./photos.pptx --size 4:3 --page-numbers

  ```

- 深色背景 + 标题页：

  ```bash

  python images_to_ppt.py ./photos ./photos.pptx --background 1F1F1F --title "产品图集"

  ```



## Behavior Notes



- **排序**：按文件名「自然顺序」排序（`img2.png` 排在 `img10.png` 之前），与文件夹内显示顺序一致。若用户要求按文件修改时间或其他顺序，在调用前明确告知并按其要求调整。

- **只处理顶层**：子文件夹会被忽略，不递归。

- **格式兼容**：python-pptx 原生不支持 webp，脚本用 Pillow 自动转为 PNG 插入；转换产物是临时文件，用后即删，不污染源文件夹。

- **隐藏文件**：以 `.` 开头的文件（含临时文件）会被跳过。

- **小图**：图片始终等比放大铺满页面，不做 1:1 限制；这符合"一页一图"的展示需求。

- **失败兜底**：若某张图片损坏无法读取，脚本打印警告并跳过该页，不中断整体转换；完成后汇报跳过的文件。