Developer Guide
The TrueType standard and the .ttx
file format
Briefly, the TrueType font standard encodes all of the information discussed in the user guide.
The .ttx
file format is simply an XML file that encodes a font, specified by
fonttools
. In a .ttx
file, each glyph is contained within a <ttGlyph>
tag.
This tag has several <contour>
definitions.
Within each contour we have successive <pt>
tags which define control points.
Each control point specifies its location (i.e., x and y coordinates) and
whether the point is "on curve" or "off curve".
There are some important rules on how to understand these points.
- If two successive points are "on" this means that they form a line.
- If three points are "on", "off", "on" then this defines a quadratic Bezier curve.
- If there are several "off" points with no "on" point in between them, there is a virtual "on" point in the middle of the two "off" points. This is a form of data compression.
- If the first point in a contour is an "off" point go to the last point and start from there. If the last point is also "off" start with a virtual "on" in between the first and the last one.
For more information, refer to:
- The
fonttools
documentation. - Glyph Hell by David Turner
- The FreeType Glyph Conventions documentation
- This StackOverflow thread on parsing
.ttf
files
Protocol buffers (protobufs)
In the words of the Google documentation, protocol buffers are
a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more.
For more information on protobufs, please refer to the protobuf developer
guide, and the
protobuf tutorial for
Python.
Here, we describe how knead
uses protobufs.
The
glyph_batch.proto
file specifies the protobuf for a batch of glyphs, and the
glyph_batch_pb2.py
is the corresponding output of the protobuf
compiler.
To compile a glyph_batch.proto
file to a Python file, you will need to install
the protobuf compiler (protoc
). See the protobuf compiler installtion
instructions.
Then, run the following command from the project root directory:
protoc --proto_path=knead/utils/ --python_out=knead/utils/ knead/utils/glyph_batch.proto
Miscellaneous notes
- Since
knead
relies heavily onfonttools
(specifically, thettx
command line tool) to convert.ttf
files to.ttx
, correct and reproducible behavior is contingent on having the correct version offonttools
. Therefore, thefonttools
version number is pinned inknead
'srequirements.txt
.