update at 2026-02-07 16:05:38

USAGE.md

@@ -1,44 +1,77 @@
-# 使用示例与说明
+# 使用说明
 
-## 🚀 快速开始
+本文覆盖两类使用方式：
 
-### 1. 安装依赖
+- Web 应用（推荐）：`frontend/` 图形界面
+- Python CLI：`font2svg.py` / `pic2svg.py`
+
+## 1. Web 应用
+
+### 1.1 安装依赖
+
+```bash
+pnpm -C frontend install
+```
+
+### 1.2 准备字体
+
+将字体放入：`frontend/public/fonts/`，支持多级目录，例如：
+
+```text
+frontend/public/fonts/
+  书法/
+    字体A.ttf
+  黑体/
+    字体B.otf
+```
+
+执行清单生成：
+
+```bash
+pnpm run prepare-fonts
+```
+
+该命令会重建：`frontend/public/fonts.json`
+
+### 1.3 启动与构建
+
+```bash
+pnpm run dev
+pnpm run build
+pnpm run preview
+```
+
+默认开发端口：`5174`。
+
+### 1.4 页面操作
+
+1. 左侧字体区搜索/勾选字体进入预览。
+2. 可点击收藏按钮加入“已收藏字体”。
+3. 顶部设置字号、颜色、输入内容。
+4. 右侧预览区点击条目可切换导出选择。
+5. 点击导出 `SVG` 或 `PNG`。
+
+导出规则：
+
+- 单个条目：直接下载
+- 多个条目：自动打包 ZIP
+- 文件名：`字体名_文本前8字符.扩展名`
+
+## 2. Python CLI
+
+### 2.1 安装依赖
 
 ```bash
 pip install -r requirements.txt
 ```
 
-### 2. 安装 potrace（必需）
+`pic2svg.py` 还需要 `potrace`：
 
 ```bash
 brew install potrace
 ```
 
-### 2.1 字体转SVG依赖
-
-```bash
-pip install fonttools uharfbuzz
-```
-
-### 3. 转换单个文件
-
-```bash
-python pic2svg.py images/your_image.png
-```
-
-### 3.1 指定输出目录
-
-```bash
-python pic2svg.py images/your_image.png --outdir output/
-```
-
-### 4. 批量转换
-
-```bash
-python pic2svg.py --indir images --outdir output
-```
-
-### 5. 字体转SVG
+### 2.2 字体转 SVG（font2svg.py）
 
 ```bash
 python font2svg.py --font path/to/font.ttf --text "Hello"
@@ -47,56 +80,53 @@ python font2svg.py --font path/to/font.ttf --text "Hello" --letter-spacing 20
 python font2svg.py --fontdir font --text "星程紫微" --outdir svg
 ```
 
-说明：单字体输出文件名根据 `--text` 自动生成；使用 `--fontdir` 时会加上字体名作为前缀。
+参数：
 
-## ⚙️ 参数说明
+- `--font`：单个字体文件（ttf/otf）
+- `--fontdir`：字体目录（批量处理）
+- `--text`：必填，渲染文字
+- `--outdir`：输出目录，不传则输出到当前目录
+- `--letter-spacing`：字距（字体单位）
 
-- `--threshold`：固定阈值（0-255），默认使用 Otsu 自动阈值。
-- `--indir`：输入目录（批量转换）。
-- `--outdir`：输出目录（自动创建，使用输入文件名.svg）。
-- `--turdsize`：抑制噪点面积阈值，越小保留细节越多。
-- `--opttolerance`：曲线优化容差，越大文件越小但可能失真。
-- `--unit`：坐标量化单位，`1` 表示不量化。
-- `--optimize-curves`：开启曲线优化（更小但可能略失真）。
-- `--circle-fit`：圆拟合误差阈值（相对半径），>0 启用圆替代。
-- `--font`：字体文件路径（ttf/otf）。
-- `--fontdir`：字体目录（遍历ttf/otf）。
-- `--text`：文字内容。
-- `--letter-spacing`：字距（字体单位），默认 0。
-
-## 🧩 常用配置示例
+### 2.3 图片转 SVG（pic2svg.py）
 
 ```bash
-# 保真优先（默认参数）
-python pic2svg.py images/your_image.png --turdsize 0 --opttolerance 0 --unit 1
-
-# 文件更小（可能略失真）
-python pic2svg.py images/your_image.png --optimize-curves --opttolerance 0.2
-
-# 需要固定阈值时
-python pic2svg.py images/your_image.png --threshold 128
-
-# 圆拟合简化（仅当轮廓接近圆时生效）
-python pic2svg.py images/your_image.png --circle-fit 0.02
-
-# 批量转换
+python pic2svg.py images/your_image.png
+python pic2svg.py images/your_image.png --outdir output/
 python pic2svg.py --indir images --outdir output
 ```
 
-## 🐛 常见问题
+常用参数：
 
-**Q: 细节丢失或断裂？**  
-A: 降低 `--turdsize`，关闭 `--optimize-curves`，必要时指定 `--threshold`。
+- `--threshold`：固定阈值（0-255），默认 Otsu
+- `--turdsize`：噪点抑制阈值
+- `--opttolerance`：曲线优化容差
+- `--unit`：坐标量化单位
+- `--optimize-curves`：启用曲线优化
+- `--circle-fit`：圆拟合误差阈值
 
-**Q: SVG 太大？**  
-A: 开启 `--optimize-curves`，或适当增大 `--opttolerance`。
+## 3. 常见问题
 
-**Q: 能否处理彩色图？**  
-A: 当前流程会转为灰度并二值化，只保留黑色区域。
+### Q1：前端看不到字体？
 
-**Q: 圆拟合过于粗糙？**  
-A: 减小 `--circle-fit` 或关闭圆拟合。
+按顺序检查：
 
-## 📄 License
+1. 字体是否放在 `frontend/public/fonts/`
+2. 是否执行了 `pnpm run prepare-fonts`
+3. `frontend/public/fonts.json` 是否包含对应条目
 
-MIT License - 自由使用和修改
+### Q2：导出 PNG 失败？
+
+通常是浏览器内存或 SVG 内容异常导致，建议：
+
+1. 降低字号后重试
+2. 先导出 SVG 验证生成是否正常
+3. 分批导出而不是一次全选过多字体
+
+### Q3：`pic2svg.py` 提示找不到 potrace？
+
+安装后确认：
+
+```bash
+which potrace
+```