# 使用说明

本文覆盖两类使用方式：

- 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
```

`pic2svg.py` 还需要 `potrace`：

```bash
brew install potrace
```

### 2.2 字体转 SVG（font2svg.py）

```bash
python font2svg.py --font path/to/font.ttf --text "Hello"
python font2svg.py --font path/to/font.ttf --text "你好" --outdir output
python font2svg.py --font path/to/font.ttf --text "Hello" --letter-spacing 20
python font2svg.py --fontdir font --text "星程紫微" --outdir svg
```

参数：

- `--font`：单个字体文件（ttf/otf）
- `--fontdir`：字体目录（批量处理）
- `--text`：必填，渲染文字
- `--outdir`：输出目录，不传则输出到当前目录
- `--letter-spacing`：字距（字体单位）

### 2.3 图片转 SVG（pic2svg.py）

```bash
python pic2svg.py images/your_image.png
python pic2svg.py images/your_image.png --outdir output/
python pic2svg.py --indir images --outdir output
```

常用参数：

- `--threshold`：固定阈值（0-255），默认 Otsu
- `--turdsize`：噪点抑制阈值
- `--opttolerance`：曲线优化容差
- `--unit`：坐标量化单位
- `--optimize-curves`：启用曲线优化
- `--circle-fit`：圆拟合误差阈值

## 3. 常见问题

### Q1：前端看不到字体？

按顺序检查：

1. 字体是否放在 `frontend/public/fonts/`
2. 是否执行了 `pnpm run prepare-fonts`
3. `frontend/public/fonts.json` 是否包含对应条目

### Q2：导出 PNG 失败？

通常是浏览器内存或 SVG 内容异常导致，建议：

1. 降低字号后重试
2. 先导出 SVG 验证生成是否正常
3. 分批导出而不是一次全选过多字体

### Q3：`pic2svg.py` 提示找不到 potrace？

安装后确认：

```bash
which potrace
```