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 转换
|