Metadata-Version: 2.4
Name: vfbLib
Version: 0.12.0
Summary: Tools for converting FontLab Studio 5 (VFB) files.
Keywords: fonttools,vfb,vfbLib
Author: Jens Kutílek
Author-email: Jens Kutílek <webmail@kutilek.de>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: fonttools[ufo]>=4.65.0
Requires-Dist: orjson>=3.12.0,<4
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: ufolib2[json]>=0.18.1
Requires-Dist: ufonormalizer>=0.6.3
Requires-Dist: vfblib[toml] ; extra == 'all'
Requires-Dist: vfblib[yaml] ; extra == 'all'
Requires-Dist: sphinx>=9.0.0 ; extra == 'doc'
Requires-Dist: sphinx-rtd-theme>=3.1.0 ; extra == 'doc'
Requires-Dist: tomli-w>=1.2.0 ; extra == 'toml'
Requires-Dist: pyyaml>=6.0.3 ; extra == 'yaml'
Requires-Python: >=3.11
Project-URL: Bug Tracker, https://github.com/LucasFonts/vfbLib/issues
Project-URL: Changelog, https://github.com/LucasFonts/vfbLib/blob/main/CHANGELOG.md
Project-URL: Documentation, https://vfblib.readthedocs.io/en/latest/
Project-URL: Homepage, https://github.com/LucasFonts/vfbLib
Provides-Extra: all
Provides-Extra: doc
Provides-Extra: toml
Provides-Extra: yaml
Description-Content-Type: text/markdown

# vfbLib

Converter and deserializer for FontLab Studio 5 VFB files.

FontLab’s own `vfb2ufo` converter is from 2015, only outputs UFO v2, and
contains serious bugs that are never going to be fixed. Its support on macOS is
subject to Apple’s mercy (no native support for Apple Silicon).

That’s why in 2022 a single determined programmer, me, Jens Kutílek, armed with nothing
but a hex editor set out to rectify this situation. In late 2025, Yuri Yarmola let me
have a look at the original VFB code from FontLab. I am very grateful for his kindness.
Without Yuri’s help, I would probably never have figured out some parts of the format.

The VFB file format is described in
[FILEFORMAT](https://github.com/jenskutilek/vfbLib/blob/main/FILEFORMAT.md).

## Improvements Over vfb2ufo

- Outputs normalized UFO v3
- Outputs FontLab user data (font and glyph level)
- Mark colors are written to the official UFO v3 lib key
- Guideline data is written to the official UFO v3 elements
- Anchors are preserved in composite glyphs
- PostScript hinting is written correctly, but to the Adobe lib key
- TrueType hinting is supported in composite glyphs
- Supports more UFO font info attributes

## Command Line Script Usage

### vfb3ufo

Convert a VFB to one UFO per master. Command line options are compatible to
FontLab’s `vfb2ufo`, but not all of them are implemented yet.

```bash
$ vfb3ufo MyFile.vfb
```

will convert the file to `MyFile.ufo` in the same directory. Existing files will
not be overwritten unless you specify the `-fo` option.

```
vfb3ufo -h
usage: vfb3ufo [-h] [-p PATH] [-fo] [-g] [-j] [-k] [-ttx] [-64] [-s] [-n] [-nops] [-v] [-z] [-m]
               inputpath [outputpath]

vfb3ufo Converter Copyright (c) 2026 by LucasFonts

positional arguments:
  inputpath             input file path (.vfb)
  outputpath            output file path (.ufo[z])

options:
  -h, --help            show this help message and exit
  -p, --path PATH       output folder
  -fo, --force-overwrite
                        force overwrite
  -g, --keep-groups     don't move non-kerning groups from groups.plist to feature code
  -j, --json            serialize UFO as JSON; combine with -z to write JSON without line breaks/indentation
  -k, --add-kerning-groups
                        add kerning groups to feature code
  -64, --base64         write GLIF lib 'data' section using base64
  -s, --silent          no display (silent mode)
  -n, --no-normalize    don't normalize the UFOs (faster)
  -nops, --no-postscript-hints
                        Don't output PostScript hinting
  -v, --verbose         Log debugging output
  -z, --zip             write UFOZ (compressed UFO)
  -m, --minimal         parse only minimal amount of data, drop missing glyphs from groups, etc.

Options not implemented here, but present in the original vfb2ufo:

  -ttx, --ttx           convert binary OpenType Layout data using TTX-like format
```

### vfb2json

Generate a representation that closely adheres to the VFB structure.

```bash
$ vfb2json MyFile.vfb
```

will convert the file to `MyFile.vfb.json` in the same directory. Existing files will be
overwritten. This is probably mostly useful for debugging purposes.

```
vfb2json -h
usage: vfb2json [-h] [-d] [--header] [-m] [-p PATH] [-r] [-v] inputpath

vfb2json Converter Copyright (c) 2026 by LucasFonts

positional arguments:
  inputpath           input file path (.vfb)

options:
  -h, --help          show this help message and exit
  -d, --no-decompile  don't decompile data, output binary in JSON
  --header            only read the VFB header, not the actual data
  -m, --minimal       parse only minimal amount of data
  -p, --path PATH     output folder
  -r, --roundtrip     roundtrip data by decompiling and compiling again before saving
  -v, --verbose       Log debugging output
```

### vfb2tth

Export the TrueType hinting from a VFB in a custom format, either as JSON (default), TOML, or YAML.

```bash
$ vfb2tth MyFile.vfb
```

To make the TOML and YAML output options available, you must install with extras
`vfblib[toml]` or `vfblib[yaml]`, respectively.

```
usage: vfb2tth [-h] [-f FORMAT] [-p PATH] inputpath

vfb2tth Converter Copyright (c) 2024 by LucasFonts

positional arguments:
  inputpath            input file path (.vfb)

options:
  -h, --help           show this help message and exit
  -f, --format FORMAT  The output format: json (default), toml, or yaml
  -p, --path PATH      output folder
```

### vfbcu2qu

Convert a VFB file to quadratic using the `cu2qu` library.

```bash
$ vfbcu2qu MyFile.vfb
```

will convert the file and save it with the suffix `.qu.vfb` in the same directory.

```
vfbcu2qu -h
usage: vfbcu2qu [-h] [-p PATH] [-fo] [-m MAX_ERR_EM] inputpath [outputpath]

VFB Cubic to Quadratic Converter Copyright (c) 2023 by LucasFonts

positional arguments:
  inputpath             input file path (.vfb)
  outputpath            output file path (.vfb)

options:
  -h, --help            show this help message and exit
  -p, --path PATH       output folder
  -fo, --force-overwrite
                        force overwrite
  -m, --max-err-em MAX_ERR_EM
                        Maximum allowed error, relative to the font's units per em. Default is 0.001.
```

### vfbdiff

Generate a diff of two VFB files, either in unified diff or HTML format (extremely slow!).

```
vfbdiff -h
usage: vfbdiff [-h] [--html HTML] file1 file2

vfbdiff Copyright (c) 2024 by LucasFonts

positional arguments:
  file1        First input file path (.vfb)
  file2        Second input file path (.vfb)

options:
  -h, --help   show this help message and exit
  --html HTML  Output diff in HTML format to file path
```

### yuri

A helper tool to decode from/encode to the
"[encoded value](https://github.com/LucasFonts/vfbLib/blob/main/FILEFORMAT.md#encoded-value-format)"
format used throughout the VFB binary data.

```bash
$ yuri -e 1 23
8ca2
```

```
yuri -h
usage: yuri [-h] [-e] [-l] [-s] hexstring [hexstring ...]

Decode and encode VFB/Type1 'encoded values'

positional arguments:
  hexstring     Input hex string

options:
  -h, --help    show this help message and exit
  -e, --encode  Encode value instead of decoding
  -l, --long    Output longest notation when encoding
  -s, --signed  Treat value as signed
```

## Python Support Policy

We like to drop unsupported Python versions early. Python 3.11 support remains for now,
because it is the standard version of Python supported out of the box in Glyphs 3. Other
than that, `vfbLib` is tested in Python 3.13 to 3.15.

## History

FontLab’s own `vfb2ufo` converter is from 2015, only outputs UFO v2, and
contains serious bugs that are never going to be fixed. Its support on macOS is
subject to Apple’s mercy (no native support for Apple Silicon).

That’s why in 2022 a single determined programmer, me, Jens Kutílek, armed with nothing
but a hex editor set out to rectify this situation. In late 2025, Yuri Yarmola let me
have a look at the original VFB code from FontLab. I am very grateful for his kindness.
Without Yuri’s help, I would probably never have figured out some parts of the format.

## Copyright

© 2022-2026 by [LucasFonts GmbH](https://www.lucasfonts.com/), Berlin
