# luatos-font-tools

**Repository Path**: openLuat/luatos-font-tools

## Basic Information

- **Project Name**: luatos-font-tools
- **Description**: 用于给luatos中使用的字库进行编辑、裁剪的工具
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-06
- **Last Updated**: 2026-03-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# luatos-font-tools

`luatos-font-tools` 是一个面向 LuatOS 的开源字库工具项目。

当前首个版本聚焦于 `.ttf` 字体裁剪，目标是让用户通过命令行快速生成只包含所需字符的精简字库，减少体积，方便在 LuatOS 场景中使用。后续会继续扩展到更贴近 LuatOS 的字库处理流程，包括 `bin` 字库相关能力。

## 项目特性

- 仅支持 `.ttf` 输入与 `.ttf` 输出
- 支持按文本内容裁剪字体
- 支持按文本文件裁剪字体
- 支持按 Unicode 列表或范围裁剪字体
- 默认保留较安全的 `.notdef` 和布局闭包策略
- 可选去除 hinting 以进一步压缩输出文件
- 默认自动改写 subset 字体名称，避免与原字体重名冲突

## 安装

### 开发者用户

如果你需要参与开发、调试代码或运行测试，建议使用可编辑安装：

```bash
git clone https://gitee.com/openLuat/luatos-font-tools.git
cd luatos-font-tools
```

```bash
python -m pip install -e .
```

如果还需要运行测试，请安装开发依赖：

```bash
python -m pip install -e .[dev]
```

### 普通使用用户

如果你只是想直接使用命令行工具，可以在仓库目录中执行：

```bash
git clone https://gitee.com/openLuat/luatos-font-tools.git
cd luatos-font-tools
```

```bash
python -m pip install .
```

安装完成后即可直接使用：

```bash
luatos_font_tools --help
```

## 使用说明

### 1. 按文本直接裁剪

```bash
luatos_font_tools -i ./font.ttf -o ./font_mini.ttf --text "你好LuatOS123"
```

### 2. 按 Unicode 范围裁剪

```bash
luatos_font_tools -i ./font.ttf --unicodes U+4F60,U+597D,U+0041-0043
```

### 3. 按文本文件裁剪

```bash
luatos_font_tools -i ./font.ttf --text-file ./examples/sample_chars.txt --drop-hinting
```

### 4. 查看帮助

```bash
luatos_font_tools --help
```

### 5. 使用 `examples` 目录中的示例字库和字符文件

仓库已经在 `examples` 目录中放入了可直接测试的字体和字符文件，可以直接执行：

```bash
luatos_font_tools -i ./examples/MiSans-Demibold.ttf -o ./examples/MiSans-Demibold_mini.ttf --text-file ./examples/sample_chars.txt --verbose
```

如果只想先验证流程而不写出文件，可以使用：

```bash
luatos_font_tools -i ./examples/MiSans-Demibold.ttf --text-file ./examples/sample_chars.txt --dry-run
```

## 命令参数

- `-i, --input`：输入 `.ttf` 文件路径
- `-o, --output`：输出 `.ttf` 文件路径，默认生成 `input_mini.ttf`
- `--text`：直接指定要保留的字符文本
- `--text-file`：从 UTF-8 文本文件中读取要保留的字符
- `--unicodes`：指定要保留的 Unicode 码点或范围
- `--unicodes-file`：从 UTF-8 文件中读取 Unicode 码点或范围
- `--ignore-missing-unicodes`：当字体中缺少请求码点时不报错
- `--no-layout-closure`：关闭布局特性带来的额外字形扩展
- `--drop-hinting`：移除 hinting 数据以减小输出体积
- `--name-mode keep|subset`：保留原字体名称或自动改写为 subset 名称
- `--dry-run`：只执行校验和内存裁剪，不写出文件
- `--verbose`：输出更详细的处理结果

## 当前限制

- 当前版本只支持 `.ttf`
- 暂不支持 `.otf`、`.woff`、`.woff2`、`.ttc`
- 暂不支持 `bin` 字库生成
- 暂不支持按 glyph name / gid 裁剪

## 开发与测试

安装开发依赖后运行：

```bash
pytest
```

当前仓库中也可以直接使用 `tests/ttf` 下的真实字体文件进行验证，例如：

```bash
luatos_font_tools -i "tests/ttf/MiSans-Demibold.ttf" -o "tests/ttf/MiSans-Demibold_mini.ttf" --text "你好LuatOS123" --verbose
```

## 规划

- 增加更适合 LuatOS 的默认裁剪策略
- 支持按 glyph / gid 方式裁剪
- 增加 `bin` 字库处理链路
- 增加更多测试样本和回归测试

## 参考项目与致谢

当前仓库的设计与实现参考或使用了以下项目，在此表示感谢：

- [`fontTools`](https://github.com/fonttools/fonttools)：本项目当前 TTF 裁剪能力直接建立在 `fontTools` 的字体解析与 subsetting 能力之上
- [`pyftsubset`](https://fonttools.readthedocs.io/en/latest/subset/index.html)：本项目的命令行能力和整体思路参考了 `fontTools` 中的 `pyftsubset`
- [`MiSans`](https://hyperos.mi.com/font/zh/)：测试阶段使用了 `MiSans` 字体样本进行真实裁剪验证

感谢上述开源项目、文档与字体资源提供的能力支持。