TypeFacet Autokern Manual

Warning: Typefacet Autokern is finicky. You will not receive usable results if you do not read this manual.

Terminology

For the purposes of kerning, a glyph has the following elements:

Contour, a path defined by a series of on-points and Bezier control points.
LSB, the Left Side Bearing. This is the distance from the origin (0) to the left x-extrema. This may be negative.
RSB, the Right Side Bearing. This is the distance from the x-advance to the right x-extrema. This may be negative.
x-extrema, the minimum and maximum x values. May not correspond to any on-point or bezier control point of a contour.
x-advance, the default (unkerned) width of the glyph.

When kerning a given pair of glyphs, we have the following elements:

Kerning value, the adjustment to the spacing defined by the side-bearings. May be positive or negative. In the example above, a large negative kerning value draws the two glyphs closer together.
x-extrema overlap, the overlap of the glyph's x-extrema. Does not imply the overlap of contours.

Installation

Download TypeFacet and its dependencies. See the Installation Guide.

Overview

TypeFacet Autokern reads a .UFO file and outputs a modified .UFO file. Autokern only modifies the kerning values and (by default) the glyph side bearings.
There is no "correct" default behavior. Different font styles are kerned in different ways. Kerning is also dependent on the proclivities of the type designer. You will need to tune Autokern's arguments to arrive at a satisfactory result.
Autokern's performance is very dependent on its arguments. For example, the --precision-ems argument also has a significant effect on performance. Values smaller than the default (0.005) are more accurate but slower.
Also, certain logging configurations (for example, the --write-kerning-pair-logsand --log-basic-pairs arguments) are slow and should probably not be used when kerning an entire font. Instead, when tuning Autokern's arguments use one of the --kern-samples-only, --glyph-pairs-to-kern or --glyphs-to-kern arguments to kern just a subset of glyphs or glyph pairs. This is far faster than processing the entire font.

Invoking TypeFacet Autokern

TypeFacet Autokern can only be used from the command line.

As described in the Installation Guide, TypeFacet Autokern's dependencies must be append to the Python path. Here's an example of how to invoke TypeFacet Autokern with the -h argument.

# Mac:
env PYTHONPATH=dependencies/RoboFab/lib:dependencies/pystache:dependencies/svgwrite:dependencies/PyYaml/lib:dependencies/FontTools/Lib:python/src-main python python/src-main/autokern/Autokern.py -h

# Windows:
set PYTHONPATH=%PYTHONPATH%;dependencies/RoboFab/lib;dependencies/pystache;dependencies/svgwrite;dependencies/PyYaml/lib;dependencies/FontTools/Lib
python python/src-main/autokern/Autokern.py -h

The -h help argument will print the usage message which describes all of Autokern's arguments.

The examples below will only describe the arguments to use. Replace -h in the example above with new arguments.

Using Autokern's Logs

There are two ways to review Autokern's results. You can open the output .ufo file in a font editor. A more convenient alternative is to look at Autokern's HTML logs.

To activate Autokern's logs, set the --log-path argument.

How to Tune Autokern Arguments

Autokerning an entire font is slow. When tuning Autokern's configuration, you will usually only want to kern a limited set of glyphs or glyph pairs.

To tune an argument:

Run Autokern
Refresh the browser window that contains the HTML log.
Repeat as necessary, tuning Autokern's arguments one by one, as described below.

The key to tuning is to use the most appropriate logs.

The "sample texts" log (example) is particularly useful when tuning arguments. Use the --kern-samples-only argument to kern just the pairs that are used in the sample texts. Use the --sample-texts argument to set the sample texts.

The --write-kerning-pair-logs argument will activate the "kerning pair" logs which document the kerning process in detail in a separate log file for each kerning pair. Example. Combine this with the --glyph-pairs-to-kern or --write-kerning-pair-logs arguments to kern just a specific set of glyphs or glyph pairs.

Step 0: Getting started

Let's begin without an empty configuration.

# See "Invoking TypeFacet Autokern" above for example of how to append dependencies to the Python path.
# All arguments should be one line.
Autokern.py \
	--ufo-src-path "theleagueof-league-gothic-4f9ff8d/source/League Gothic.ufo" \
	--ufo-dst-path "out/League Gothic-kerned.ufo" \
	--min-distance-ems 0.00 \
	--max-distance-ems 0.00 \
	--max-x-extrema-overlap-ems 0.0 \
	--intrusion-tolerance-ems 0.0 \
	--precision-ems 0.005 \
	--log-path logs \
	--kern-samples-only

Consult the "sample texts" log. All glyphs should be kerned with zero space, ie. just barely touching each other.

Step 1: the --min-distance-ems argument

The --min-distance-ems argument sets a lower bound on how close the contours of the two glyphs can be.

Tune the --min-distance-ems value by kerning a pair of glyphs such as T vs. T, t vs. t, f vs. T or r vs. f whose profiles usually meet at the endpoints of two strokes.

Note: Set the --min-distance-ems and --max-distance-ems arguments to the same value for now.

To kern just T vs. T, use the following arguments:

# See "Invoking TypeFacet Autokern" above for example of how to append dependencies to the Python path.
# All arguments should be one line.
Autokern.py \
	--ufo-src-path "theleagueof-league-gothic-4f9ff8d/source/League Gothic.ufo" \
	--ufo-dst-path "out/League Gothic-kerned.ufo" \
	--min-distance-ems 0.04 \ <-- Tune these arguments together using the same value
	--max-distance-ems 0.04 \ <-- Tune these arguments together using the same value
	--max-x-extrema-overlap-ems 0.0 \
	--intrusion-tolerance-ems 0.0 \
	--precision-ems 0.005 \
	--log-path logs \
	--glyph-pairs-to-kern T T \
	--write-kerning-pair-logs

To kern a T vs. T, t vs. t, f vs. T and r vs. f , use the following arguments:

# See "Invoking TypeFacet Autokern" above for example of how to append dependencies to the Python path.
# All arguments should be one line.
Autokern.py \
	--ufo-src-path "theleagueof-league-gothic-4f9ff8d/source/League Gothic.ufo" \
	--ufo-dst-path "out/League Gothic-kerned.ufo" \
	--min-distance-ems 0.04 \ <-- Tune these arguments together using the same value
	--max-distance-ems 0.04 \ <-- Tune these arguments together using the same value
	--max-x-extrema-overlap-ems 0.0 \
	--intrusion-tolerance-ems 0.0 \
	--precision-ems 0.005 \
	--log-path logs \
	--kern-samples-only \
	--sample-texts "ttrfTT"

Step 2: the --max-distance-ems argument

The --max-distance-ems defines the normal spacing between two glyphs. It sets an upper bound on how far apart the two glyphs can be.

Tune the --max-distance-ems value by kerning a pair of glyphs such as N vs. N, which have straight, uninterrupted profiles.

If you aren't kerning a sans-serif font, your N may not have straight sides. You may have to use the "vertical line" glyph ("bar", unicode 0x7c) instead.

To kern just N vs. N, use the following arguments:

# See "Invoking TypeFacet Autokern" above for example of how to append dependencies to the Python path.
# All arguments should be one line.
Autokern.py \
	--ufo-src-path "theleagueof-league-gothic-4f9ff8d/source/League Gothic.ufo" \
	--ufo-dst-path "out/League Gothic-kerned.ufo" \
	--min-distance-ems 0.04 \
	--max-distance-ems 0.1 \ <-- Tune this value
	--max-x-extrema-overlap-ems 0.0 \
	--intrusion-tolerance-ems 0.0 \
	--precision-ems 0.005 \
	--log-path logs \
	--kern-samples-only \
	--sample-texts "||NNnnOOoo"

Step 3: the --intrusion-tolerance-ems argument

The --intrusion-tolerance-ems argument defines the maximum amount to which the glyphs can "intrude" into the spacing between them.

For example, if you are kerning a serif font, your results for the N vs. N kerning (see above) ought to look something like this:

This is wrong. The --max-distance-ems argument should be used to specify the distance between glyph's bodies, not small details like serifs. The serifs should intrude into the spacing between the glyphs.

The --intrusion-tolerance-ems argument is crucial and should be tuned with care. As a rule, it should be as large as necessary and no larger.

A good point of departure are pairs such as A vs. A or O vs. O which should pull towards each other. You should also review the entirety of the "sample texts" log.

# See "Invoking TypeFacet Autokern" above for example of how to append dependencies to the Python path.
# All arguments should be one line.
Autokern.py \
	--ufo-src-path theleagueof-linden-hill-a3f7ae6/source/Linden Hill.ufo \
	--ufo-dst-path out/Linden Hill-kerned.ufo \
	--min-distance-ems 0.04 \
	--max-distance-ems 0.1 \
	--max-x-extrema-overlap-ems 0.0 \
	--intrusion-tolerance-ems 0.1 \ <-- Tune this value
	--precision-ems 0.005 \
	--log-path logs \
	--kern-samples-only \
	--sample-texts "NNOOAA"

Note: intrusion is limited by the --min-distance-ems argument, so intrusion will never cause contours to overlap.

Step 4: the --max-x-extrema-overlap-ems argument

The --max-x-extrema-overlap-ems argument limits the extent to which the x-extrema of glyphs can overlap. Do not confuse x-extrema overlap with contour overlap.

Tune the --max-x-extrema-overlap-ems value by kerning a pair of glyphs such as V vs. A, T vs. a, L vs. T, etc. whose x-extrema do not collide.

# See "Invoking TypeFacet Autokern" above for example of how to append dependencies to the Python path.
# All arguments should be one line.
Autokern.py \
	--ufo-src-path theleagueof-linden-hill-a3f7ae6/source/Linden Hill.ufo \
	--ufo-dst-path out/Linden Hill-kerned.ufo \
	--min-distance-ems 0.04 \
	--max-distance-ems 0.1 \
	--max-x-extrema-overlap-ems 0.1 \ <-- Tune this value
	--intrusion-tolerance-ems 0.1 \ 
	--precision-ems 0.005 \
	--log-path logs \
	--kern-samples-only \
	--sample-texts "WAVTaLTLY"

If the --max-x-extrema-overlap-ems argument is negative, Autokern will maintain a minimum spacing between the glyphs' x-extrema.

Further Tuning

When kerning an entire font, do not use the --write-kerning-pair-logs argument as writing a log file for each kerning pair combination will be very slow.
Use the --disparity-log-count argument to write "disparity" logs which document the largest differences between the original kerning and Autokern's kerning. Example.
If the --do-not-modify-side-bearings argument is present, Autokern will preserve the original side bearings.
By default, Autokern will not allow negative side bearings, ie. within the x-extrema of a glyph. The --allow-negative-side-bearings argument enables such side bearings.
If the --kerning-threshold-ems argument is present, Autokern will discard kerning values less than this value.
If the --max-kerning-pairs argument is present, Autokern will only output the N largest kerning values and discard the rest.
If the --log-basic-pairs argument is present, Autokern will write the "basic pairs" logs which can be used for proofing. NOTE: these logs are very time-consuming to generate.
In addition to the --max-x-extrema-overlap-ems argument, you can use the --x-extrema-overlap-scaling argument to tune x-extrema overlap. To scale down x-extrema overlaps to 1/3 of their normal size, use a --x-extrema-overlap-scaling value of 0.333. --x-extrema-overlap-scaling does not effect kerning pairs that do not have x-extrema overlap.
The --tracking argument can be used to add a constant value to all kerning values.
The --ignore-x-extrema-overlap-outside-ascender argument can be used to ignore x-extrema overlap below the baseline or above the ascender.

Controlling Scope

By default, Autokern will kern nearly all of the glyphs in the font.

We've already discussed how to limit Autokern's scope using the --kern-samples-only, --glyph-pairs-to-kern or --glyphs-to-kern arguments. To kern an entire font, make sure none of these arguments are present.

The --glyphs-to-ignore and --glyph-categories-to-ignore arguments can be used to specify a set of glyphs that should not be kerned. Use the -h usage argument for more information.

Per-Category Tuning

The --max-x-extrema-overlap-ems-per-category, --max-distance-ems-per-category, --min-distance-ems-per-category, --intrusion-tolerance-ems-per-category and --tracking-ems-per-category, arguments allow the user to use different values for different unicode categories, for example: punctuation (P*) or currency symbols (Sc).

The user sets these values using a set of (category, value) rules.

# Example:
# Require a minimum x-extrema offset of -0.025 em 
# for all punctuation, marks and symbols:
--max-x-extrema-overlap-ems-per-category P* -0.025 M* -0.025 S* -0.025

# Example:
# Apply a --max-distance-ems value of 0.050 em 
# to all currency symbols.
--max-distance-ems-per-category Sc 0.050

These categories are defined by the unicode standard. See the Unicodedata documentation for a list of glyph categories.

Unicode glyph categories (ie. Lu = Letter, Uppercase) have a major (ie. Letter) and minor (ie. Uppercase) components. You may use an asterisk in the minor component as a wildcard (ie. L* = all Letters).

When the user has defined more than one rule that applies to a kerning pair, the last rule in the rule set has precedence.

# Rule precedence example:
--min-distance-ems 0.030
--min-distance-ems-per-category P* 0.015 M* 0.025 S* 0.025 Sc 0.050 

# No per-category rule applies, so the default --min-distance-ems 0.030 applies.
A vs. T 

# The punctuation wildcard rule (P*) matches period, so it applies: 0.015.
A vs. period

# The symbol wildcard rule (S*) and the currency symbol rule (Sc) both match dollar,
# so the currency symbol rule applies since it is defined later in the rule set: 0.050.
A vs. dollar

# The punctuation wildcard rule (S*) matches period 
# the and the currency symbol rule (Sc) matches dollar,
# so the currency symbol rule applies since it is defined later in the rule set: 0.050.
period vs. dollar

TypeFacet Autokern Home