# pptopic 说明

将 PowerPoint 演示文稿导出为长图的工具。

## 功能

- 将 PPTX 文件的所有幻灯片垂直拼接为一张长图
- 支持 JPG 和 PNG 格式输出
- 支持自定义输出宽度和目录
- 内置图片优化功能，使用图片优化引擎进行无损压缩

## 系统要求

- Windows 系统（使用 win32com 调用 PowerPoint）
- Python >= 3.13
- Microsoft PowerPoint

## 新手使用说明

如果你是第一次使用命令行工具，请按以下步骤操作。

### 准备工作

- **PowerPoint**：需要安装 Microsoft PowerPoint（Office 2016 或更新版本）
- **网络连接**：安装过程中需要下载工具
- **理解命令行工具**：你需要理解命令行的基本操作，包括文件路径、参数传递等。

### PowerShell的基本知识

PowerShell在Windows中是自带的，所以一般情况下无需额外安装。如果你不知道如何打开，可以在开始菜单搜索 "PowerShell"，通常就能看见，点击后即可打开。

在PowerShell中跳转目录，只需要输入 `cd` 加上目录路径即可。目录路径可以从资源管理器中在地址栏中复制。如果你的目录路径中包含空格，需要在路径中添加引号。

```powershell
# 这是一个例子
cd "C:\Users\User SomeX\Desktop\OneFolder"
```

### 第一步：安装 uv

`uv` 是一个 Python 包管理器，用来安装 pptopic 及其依赖。

打开 PowerShell（在开始菜单搜索 "PowerShell"），进入本项目的目录：

```powershell
cd "<你的解压目录>\pptopic"
```

赋予PowerShell执行权限：

```powershell
Set-ExecutionPolicy Bypass -Scope CurrentUser
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

运行项目自带的安装脚本：

```powershell
.\uv-installer.ps1
```

该脚本会自动下载最新版本的 uv 并添加到系统 PATH。如果你在中国大陆，脚本已内置 GitHub 加速镜像，无需额外配置。

安装完成后，**关闭并重新打开 PowerShell**，验证安装：

```powershell
uv --version
```

> - 如果你已安装 [scoop](https://scoop.sh/)，也可以直接 `scoop install uv`。
> - 如果想安装特定版本的 uv，可以在运行脚本前设置环境变量：`$env:UV_INSTALLER_VERSION = "0.11.20"`

### 第二步：安装 Python

使用 uv 安装 Python 3.13 或更新版本：

```powershell
uv python install 3.13
```

### 第三步（可选）：安装 pngquant 图片优化工具

虽然是可选安装，但我超级建议你安装，因为ppt导出后，图片通常较大，不进行图片无损压缩，会导致文件大小过大。

如果你需要对导出的图片进行压缩优化，运行：

```powershell
.\install-pngquant.ps1
```

该脚本会：
1. 如果你已安装 scoop → 通过 scoop 安装 pngquant
2. 如果没有 scoop → 自动下载并安装到 `%APPDATA%\pngquant`，并添加到 PATH

安装完成后，**重新打开 PowerShell**，验证安装：

```powershell
pngquant --version
```

> - 自定义安装目录：`.\install-pngquant.ps1 -InstallDir "D:\Tools\pngquant"`
> - 强制重新安装：`.\install-pngquant.ps1 -Force`

### 第四步：安装pptopic

```powershell
uv tool install -e .
```

### 第五步：开始使用

```powershell
# 导出 PPTX 为长图
pptopic export presentation.pptx

# 优化图片
pptopic optimize image.png

# 工作中常用命令：导出 PPTX 为长图并优化图片
# 其中，29999是微信接受的最大高度
pptopic export presentation.pptx --optimize --max-height 29999 -o result.png
```

至此安装完成。如果任何步骤遇到问题，请参考下方详细说明。

## 一般安装说明

### 安装 pptopic

```bash
git clone https://git.lyz.one/SidneyZhang/pptopic.git
cd pptopic
uv tool install -e .
```

### 安装 uv

项目使用 `uv` 进行安装和项目管理，如果你没有安装，这里提供一个简单的安装指引：

只是简单安装，可以使用项目自带的安装脚本（推荐）：

```powershell
.\uv-installer.ps1
```

该脚本自动检测 uv 最新版本，支持国内 GitHub 加速镜像下载（`mirror.ghproxy.com`、`ghproxy.net`），并自动将 uv 添加到系统 PATH。

也可以通过 scoop 安装：

```bash
scoop install uv
```

或者使用官方提供的安装脚本：

```bash
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

请注意，上述脚本都需要相关的脚本运行权限，否则无法正常运行，一般如下操作即可获取相关权限：

```powershell
Set-ExecutionPolicy Bypass -Scope CurrentUser
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

## 使用

### 导出 PPTX 为长图

```bash
# 基本用法
pptopic export presentation.pptx

# 详细说明
pptopic export --help
```

### 单独优化图片

```bash
# 优化图片
pptopic optimize image.png

# 详细说明
pptopic optimize --help
```

## 图片优化

为了获得最佳的图片压缩效果，推荐使用 [pngquant](https://pngquant.org/) 进行图片压缩。

### 安装脚本

可以使用提供的 PowerShell 脚本安装 pngquant：

```powershell
.\install-pngquant.ps1
```

该脚本支持两种安装方式：

1. **已安装 scoop** → 通过 `scoop install pngquant` 安装
2. **未安装 scoop** → 从 pngquant 官网下载并安装到 `%APPDATA%\pngquant`，自动添加到 PATH

```powershell
# 自定义安装目录
.\install-pngquant.ps1 -InstallDir "D:\Tools\pngquant"

# 强制重新安装
.\install-pngquant.ps1 -Force

# 不修改 PATH ，将无法全局使用这个工具
.\install-pngquant.ps1 -NoModifyPath
```

也可以直接使用 scoop 安装 pngquant，或者手动下载安装。

```bash
scoop install pngquant
```

或从 [pngquant.org](https://pngquant.org/) 下载 Windows 版本手动配置。

## License

MIT License