npm package: @sakitam-gis/font-maker-cli
Description: Command-line tool for converting TrueType/OpenType fonts to MapLibre GL glyph PBF format
Latest version: 1.0.0

# Font Maker CLI

一个高性能、跨平台的命令行工具，用于将 TrueType (`.ttf`) 和 OpenType (`.otf`) 字体转换为 MapLibre GL/Mapbox GL 兼容的字形 PBF（Protocol Buffer）格式。

## 特性

- 🚀 **高性能**：使用 Worker 线程并行处理
- 🌍 **跨平台**：支持 Windows、macOS 和 Linux
- 📦 **批量处理**：同时转换多个字体
- 🎯 **多类输出**：支持目录结构或压缩包导出
- 💡 **字体信息**：转换前查看字体元数据

## 安装

### 前置要求

- Node.js >= 18.0.0
- npm 或 yarn

### 本地安装

```bash
npm install
npm run build
```

### 全局安装

```bash
npm install -g .
```

## 使用方法

### 转换字体

将一个或多个字体文件转换为字形 PBF 格式：

```bash
# 转换单个字体
font-maker convert path/to/font.ttf

# 转换多个字体
font-maker convert font1.ttf font2.otf font3.ttf

# 指定输出目录
font-maker convert font.ttf -o ./output

# 使用更多并行任务
font-maker convert font.ttf -j 8

# 导出为 ZIP 文件
font-maker convert font.ttf -f zip

# 详细输出
font-maker convert font.ttf -v
```

### 选项

- `-o, --output <dir>`：输出目录（默认：`./output`）
- `-j, --jobs <number>`：并行任务数（默认：CPU 核心数）
- `-v, --verbose`：详细输出
- `-f, --format <type>`：输出格式：`dir`（默认）或 `zip`

### 字体信息

显示字体文件的信息：

```bash
font-maker info path/to/font.ttf
```

这将显示：
- 字体名称和家族
- 字体样式
- 字形数量
- 字体格式（TrueType、OpenType 等）

## 输出格式

该工具生成 PBF 格式的字形范围，与 MapLibre GL 和 Mapbox GL 兼容：

```
output/
├── FontName/
│   ├── 0-255.pbf
│   ├── 256-511.pbf
│   ├── 512-767.pbf
│   └── ... (最多到 65280-65535.pbf)
```

每个 PBF 文件包含 256 个字符的 Unicode 范围的字形。

## 性能

CLI 工具针对性能进行了优化：

- **并行处理**：默认利用所有 CPU 核心
- **Worker 线程**：使用 Node.js workers 进行高效的多线程处理
- **内存高效**：流式处理数据以避免内存膨胀
- **WASM 加速**：使用 WebAssembly 进行字体渲染

### 基准测试

典型转换时间（现代硬件）：

| 字体大小 | 单个字体 | 10 个字体（并行） |
|---------|---------|------------------|
| 小型 (< 1MB) | ~2-3秒 | ~5-7秒 |
| 中型 (1-5MB) | ~5-8秒 | ~12-18秒 |
| 大型 (> 5MB) | ~10-15秒 | ~25-35秒 |

## 与 MapLibre GL 集成

转换后，在你的 MapLibre GL 应用中使用字体：

```typescript
const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    glyphs: 'http://localhost:8080/fonts/{fontstack}/{range}.pbf',
    sources: { /* ... */ },
    layers: [
      {
        id: 'labels',
        type: 'symbol',
        layout: {
          'text-field': '{name}',
          'text-font': ['YourFontName']
        }
      }
    ]
  }
});
```

## 示例

### 将多个字体转换为 ZIP

```bash
font-maker convert \
  fonts/Roboto-Regular.ttf \
  fonts/Roboto-Bold.ttf \
  fonts/OpenSans-Regular.ttf \
  -o ./glyphs \
  -f zip \
  -v
```

### 使用最大并行度批量处理

```bash
font-maker convert fonts/*.ttf -j 16 -o ./output
```

### 转换前检查字体

```bash
# 首先检查字体信息
font-maker info fonts/MyFont.ttf

# 如果没问题就转换
font-maker convert fonts/MyFont.ttf
```

## 架构

```
┌─────────────┐
│  CLI 入口   │
└──────┬──────┘
       │
       v
┌─────────────────┐
│  字体转换器      │
└──────┬──────────┘
       │
       v
┌─────────────────────────────┐
│   Worker 线程池             │
│  ┌──────┐ ┌──────┐ ┌──────┐│
│  │Worker│ │Worker│ │Worker││
│  │  1   │ │  2   │ │  N   ││
│  └──┬───┘ └──┬───┘ └──┬───┘│
└─────┼────────┼────────┼─────┘
      │        │        │
      v        v        v
┌─────────────────────────────┐
│    WASM 字体处理器           │
│   (sdfglyph + FreeType)     │
└─────────────────────────────┘
```

## 故障排除

### "找不到模块 @rollup/rollup-win32-x64-msvc"

如果在安装过程中遇到此错误：

```bash
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps
```

### WASM 模块加载失败

确保 `sdfglyph.wasm` 文件存在于 `app/public` 目录中：

```bash
ls -la ../app/public/sdfglyph.wasm
```

如果缺失，重新构建 WASM 模块：

```bash
cd ..
./build_wasm.sh
```

### 内存不足

对于非常大的字体或大量并行任务：

```bash
# 减少并行任务数
font-maker convert large-font.ttf -j 2

# 或者增加 Node.js 内存
NODE_OPTIONS="--max-old-space-size=4096" font-maker convert large-font.ttf
```

## 开发

### 项目结构

```
cli/
├── src/
│   ├── index.ts          # CLI 入口点
│   ├── converter.ts      # 字体转换逻辑
│   ├── worker.ts         # Worker 线程实现
│   ├── wasmLoader.ts     # WASM 模块加载器
│   ├── writer.ts         # 输出文件写入器
│   └── fontInfo.ts       # 字体元数据读取器
├── dist/                 # 编译后的 JavaScript（生成）
├── package.json
├── tsconfig.json
└── README.md
```

### 构建

```bash
npm run build
```

### 开发模式运行

```bash
npm run dev -- convert font.ttf
```

## 相关项目

- [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js)
- [Font Maker Web 应用](../app) - 基于浏览器的版本
- [node-fontnik](https://github.com/mapbox/node-fontnik) - 替代字体转换器