114 lines
2.5 KiB
Markdown
114 lines
2.5 KiB
Markdown
|
# SVG to PNG 渲染工具
|
|||
|
|
|
|||
|
|
## 功能
|
|||
|
|
|
|||
|
|
将 SVG 矢量图文件渲染为 PNG 位图，解决本机缺少 SVG 渲染工具、FFmpeg 无 SVG 解码器的问题。
|
|||
|
|
|
|||
|
|
## 依赖
|
|||
|
|
|
|||
|
|
- Python 3.8+
|
|||
|
|
- CairoSVG 2.9.0+
|
|||
|
|
- Pillow 12.0.0+
|
|||
|
|
- 系统 cairo 库（macOS: `brew install cairo`）
|
|||
|
|
|
|||
|
|
## 安装
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. 安装系统 cairo 库（macOS）
|
|||
|
|
brew install cairo
|
|||
|
|
|
|||
|
|
# 2. 安装 Python 依赖
|
|||
|
|
pip install cairosvg Pillow
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 用法
|
|||
|
|
|
|||
|
|
### 单文件转换
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 基本用法（自动读取 SVG 原始尺寸）
|
|||
|
|
python tools/svg-to-png.py input.svg output.png
|
|||
|
|
|
|||
|
|
# 指定输出宽度（高度等比缩放）
|
|||
|
|
python tools/svg-to-png.py input.svg output.png --width 1920
|
|||
|
|
|
|||
|
|
# 指定输出高度（宽度等比缩放）
|
|||
|
|
python tools/svg-to-png.py input.svg output.png --height 1080
|
|||
|
|
|
|||
|
|
# 指定缩放因子（基于 SVG 原始尺寸放大/缩小）
|
|||
|
|
python tools/svg-to-png.py input.svg output.png --scale 2
|
|||
|
|
|
|||
|
|
# 透明背景
|
|||
|
|
python tools/svg-to-png.py input.svg output.png --background none
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 批量转换
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 转换目录下所有 SVG 文件
|
|||
|
|
python tools/svg-to-png.py ./svg-dir/ ./png-dir/ --batch
|
|||
|
|
|
|||
|
|
# 批量转换并指定缩放因子
|
|||
|
|
python tools/svg-to-png.py ./svg-dir/ ./png-dir/ --batch --scale 2
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 作为模块导入
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
from tools.svg_to_png import convert_svg_to_png
|
|||
|
|
|
|||
|
|
# 转换单个文件
|
|||
|
|
convert_svg_to_png("input.svg", "output.png", scale=2)
|
|||
|
|
|
|||
|
|
# 指定宽度（高度等比）
|
|||
|
|
convert_svg_to_png("input.svg", "output.png", width=1920)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 路径
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
video-ai-system/tools/svg-to-png.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 视频处理流水线集成
|
|||
|
|
|
|||
|
|
在视频处理流水线中，使用该工具将 SVG 字幕/特效渲染为 PNG 序列，再通过 FFmpeg 合成到视频中：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 1. 渲染 SVG 字幕为 PNG 序列
|
|||
|
|
python tools/svg-to-png.py ./subtitles/ ./subtitles-png/ --batch --width 1920
|
|||
|
|
|
|||
|
|
# 2. 用 FFmpeg 将 PNG 序列合成到视频
|
|||
|
|
ffmpeg -i input.mp4 -i ./subtitles-png/frame-%04d.png -filter_complex overlay output.mp4
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 故障排查
|
|||
|
|
|
|||
|
|
### OSError: no library called "cairo-2" was found
|
|||
|
|
|
|||
|
|
**原因**：Python 找不到系统 cairo 库。
|
|||
|
|
|
|||
|
|
**解决**：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# macOS（Apple Silicon）
|
|||
|
|
export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"
|
|||
|
|
|
|||
|
|
# macOS（Intel）
|
|||
|
|
export DYLD_LIBRARY_PATH="/usr/local/lib:$DYLD_LIBRARY_PATH"
|
|||
|
|
|
|||
|
|
# 然后重新运行
|
|||
|
|
python tools/svg-to-png.py input.svg output.png
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 建议在 `~/.zshrc` 中添加：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# video-ai-system SVG 渲染工具依赖
|
|||
|
|
export DYLD_LIBRARY_PATH="/opt/homebrew/lib:$DYLD_LIBRARY_PATH"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 更新记录
|
|||
|
|
|
|||
|
|
- 2026-06-23：初始版本，支持单文件/批量 SVG→PNG 转换
|