# 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` is an open source font tooling project for LuatOS.

The current first release focuses on `.ttf` font subsetting. The goal is to let users quickly generate a compact font that only contains the characters they need through a command line interface, reducing size for LuatOS-related use cases. Future versions will continue to expand toward more LuatOS-oriented font processing workflows, including `bin` font support.

## Features

- Support `.ttf` input and `.ttf` output only
- Subset fonts by inline text
- Subset fonts by text file
- Subset fonts by Unicode list or Unicode ranges
- Keep safer defaults for `.notdef` and layout closure
- Optionally drop hinting to further reduce output size
- Rename subset font names by default to avoid collisions with the original font

## Install

### For developers

If you want to develop, debug, or run tests, clone the repository first:

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

Then install it in editable mode:

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

If you also need the test dependencies:

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

### For users

If you only want to use the CLI tool, clone the repository first:

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

Then install it normally:

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

After installation, you can run:

```bash
luatos_font_tools --help
```

## Usage

### 1. Subset by direct text

```bash
luatos_font_tools -i ./font.ttf -o ./font_mini.ttf --text "Hello LuatOS"
```

### 2. Subset by Unicode ranges

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

### 3. Subset by text file

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

### 4. Show help

```bash
luatos_font_tools --help
```

### 5. Use the sample font and character file from `examples`

The repository already includes a testable sample font and character file in `examples`, so you can run:

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

If you only want to verify the flow without writing the output file:

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

## CLI Options

- `-i, --input`: input `.ttf` file path
- `-o, --output`: output `.ttf` file path, defaults to `input_mini.ttf`
- `--text`: characters to keep directly from the command line
- `--text-file`: read characters to keep from a UTF-8 text file
- `--unicodes`: Unicode code points or ranges to keep
- `--unicodes-file`: read Unicode code points or ranges from a UTF-8 file
- `--ignore-missing-unicodes`: do not fail when requested code points are missing from the font
- `--no-layout-closure`: disable extra glyph expansion from layout features
- `--drop-hinting`: remove hinting data to reduce output size
- `--name-mode keep|subset`: keep original font names or rewrite them for the subset font
- `--dry-run`: validate and subset in memory without writing the output file
- `--verbose`: print more detailed processing information

## Current Limitations

- Only `.ttf` is supported in the current version
- `.otf`, `.woff`, `.woff2`, and `.ttc` are not supported yet
- `bin` font generation is not supported yet
- Glyph name / gid based subsetting is not supported yet

## Development and Testing

After installing the development dependencies, run:

```bash
pytest
```

You can also validate the tool with a real font file under `tests/ttf`, for example:

```bash
luatos_font_tools -i "tests/ttf/MiSans-Demibold.ttf" -o "tests/ttf/MiSans-Demibold_mini.ttf" --text "Hello LuatOS" --verbose
```

## Roadmap

- Add more LuatOS-oriented default subset strategies
- Support glyph / gid based subsetting
- Add a `bin` font processing pipeline
- Add more sample fonts and regression tests

## References and Thanks

This repository was designed and implemented with reference to or direct use of the following projects. Many thanks to them:

- [`fontTools`](https://github.com/fonttools/fonttools): the current TTF subsetting capability in this project is built directly on top of `fontTools` font parsing and subsetting features
- [`pyftsubset`](https://fonttools.readthedocs.io/en/latest/subset/index.html): the CLI design and overall workflow of this project are inspired by `pyftsubset` from `fontTools`
- [`MiSans`](https://hyperos.mi.com/font/zh/): used as a real font sample during testing and validation

Thanks to the maintainers and contributors of these open source projects, documents, and font resources.