6 Copyright (C) 2011-2016 by Werner Lemberg.
8 This file is part of the ttfautohint library, and may only be used,
9 modified, and distributed under the terms given in `COPYING'. By
10 continuing to use, modify, or distribute this file you indicate that you
11 have read `COPYING' and understand and accept it fully.
13 The file `COPYING' mentioned in the previous paragraph is distributed
14 with the ttfautohint library.
22 **ttfautohint** is a library written in\ C that takes a TrueType font as
23 the input, removes its bytecode instructions (if any), and returns a new
24 font where all glyphs are bytecode hinted using the information given by
25 FreeType's auto-hinting module. The idea is to provide the excellent
26 quality of the auto-hinter on platforms that don't use FreeType.
28 The library has a single API function, `TTF_autohint`, which is described
29 [below](#the-ttfautohint-api).
31 Bundled with the library there are two front-end programs, [`ttfautohint`
32 and `ttfautohintGUI`](#ttfautohint-and-ttfautohintgui), being a command line
33 program and an application with a Graphics User Interface (GUI),
37 What exactly are hints?
38 -----------------------
40 To cite [Wikipedia](http://en.wikipedia.org/wiki/Font_hinting):
42 > **Font hinting** (also known as **instructing**) is the use of
43 > mathematical instructions to adjust the display of an outline font so that
44 > it lines up with a rasterized grid. At low screen resolutions, hinting is
45 > critical for producing a clear, legible text. It can be accompanied by
46 > antialiasing and (on liquid crystal displays) subpixel rendering for
49 and Apple's [TrueType Reference
50 Manual](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM03/Chap3.html#features):
52 > For optimal results, a font instructor should follow these guidelines:
54 > - At small sizes, chance effects should not be allowed to magnify small
55 > differences in the original outline design of a glyph.
57 > - At large sizes, the subtlety of the original design should emerge.
59 In general, there are three possible ways to hint a glyph.
61 1. The font contains hints (in the original sense of this word) to guide
62 the rasterizer, telling it which shapes of the glyphs need special
63 consideration. The hinting logic is partly in the font and partly in
64 the rasterizer. More sophisticated rasterizers are able to produce
65 better rendering results.
67 This is how Type\ 1 and CFF hints work.
69 2. The font contains exact instructions (also called *bytecode*) on how to
70 move the points of its outlines, depending on the resolution of the
71 output device, and which intentionally distort the (outline) shape to
72 produce a well-rasterized result. The hinting logic is in the font;
73 ideally, all rasterizers simply process these instructions to get the
74 same result on all platforms.
76 This is how TrueType hints work.
78 3. The font gets auto-hinted (at run-time). The hinting logic is
79 completely in the rasterizer. No hints in the font are used or needed;
80 instead, the rasterizer scans and analyzes the glyphs to apply
81 corrections by itself.
83 This is how FreeType's auto-hinter works; see
84 [below](#background-and-technical-details) for more.
87 What problems can arise with TrueType hinting?
88 ----------------------------------------------
90 While it is relatively easy to specify PostScript hints (either manually or
91 by an auto-hinter that works at font creation time), creating TrueType
92 hints is far more difficult. There are at least two reasons:
94 - TrueType instructions form a programming language, operating at a very
95 low level. They are comparable to assembler code, thus lacking all
96 high-level concepts to make programming more comfortable.
98 Here an example how such code looks like:
102 PUSHB[ ] /* 3 values pushed */
105 PUSHB[ ] /* 2 values pushed */
108 PUSHB[ ] /* 3 values pushed */
113 Another major obstacle is the fact that font designers usually aren't
116 - It is very time consuming to manually hint glyphs. Given that the
117 number of specialists for TrueType hinting is very limited, hinting a
118 large set of glyphs for a font or font family can become very expensive.
124 The ttfautohint library brings the excellent quality of FreeType rendering
125 to platforms that don't use FreeType, yet require hinting for text to look
126 good -- like Microsoft Windows. Roughly speaking, it converts the glyph
127 analysis done by FreeType's auto-hinting module to TrueType bytecode.
128 Internally, the auto-hinter's algorithm resembles PostScript hinting
129 methods; it thus combines all three hinting methods discussed
130 [previously](#what-exactly-are-hints).
132 The simple interface of the front-ends (both on the command line and with
133 the GUI) allows quick hinting of a whole font with a few mouse clicks or a
134 single command on the prompt. As a result, you get better rendering results
135 with web browsers, for example.
137 Across Windows rendering environments today, fonts processed with
138 ttfautohint look best with ClearType enabled. This is the default for
139 Windows\ 7. Good visual results are also seen in recent MacOS\ X versions
140 and GNU/Linux systems (including Android, ChromeOS, and other mobile
141 operating systems) that use FreeType for rendering glyphs.
143 The goal of the project is to generate a 'first pass' of hinting that font
144 developers can refine further for ultimate quality.
150 Fundamentally, there are two approaches to hinting. The older approach,
151 let's call it 'sharp', popular when text was rendered in pure
152 black-and-white, was to make all stems round to full pixels so that in a
153 text line, all stems would be either one pixel or (at a larger point size)
154 two pixels. When grayscale antialiasing came about, this approach actually
155 started harming the rendering rather than helping it, because the horizontal
156 and vertical stems would render very dark but round or diagonal stems would
159 So a new approach was developed, let's call it 'fuzzy', where all stems and
160 other elements are equalized so that in grayscale (or ClearType) rendering,
161 they all are of roughly equal color. This means that stems are not rounded
162 to full pixels but in fact to fractions of a pixel. However, with
163 black-and-white renderers, this approach yields poor results because in
164 black-and-white you cannot render a fraction of a pixel, so some stems
165 become one pixel and some become two.
167 The TrueType autohinters in [FontForge] and [FontLab Studio], to name two
168 well-known font editors, take the 'sharp' approach, while the TrueType
169 autohinter in ttfautohint takes the 'fuzzy' approach.
171 In theory, a hybrid approach is possible, using TrueType conditional hints:
172 If the rasterizer is black-and-white, 'sharp' rendering could happen, while
173 if the rasterizer is ClearType, the 'fuzzy' rendering could be used. It is
174 not intended to add black-and-white auto-hinting to ttfautohint. However,
175 it is planned to develop an interface so that ttfautohint can cooperate with
176 font editors, providing this hybrid hinting.
180 `ttfautohint` and `ttfautohintGUI`
181 ==================================
183 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
184 looks quite similar; the used toolkit is [Qt], which in turn uses the
185 platform's native widgets.
187 ![`ttfautohintGUI` on GNU/Linux running KDE](img/ttfautohintGUI.png)
189 Both the GUI and console version share the same features, to be discussed in
192 **Warning: ttfautohint cannot always process a font a second time.**
193 If the font contains composite glyphs, and option [`-c`](#hint-composites)
194 is used, reprocessing with ttfautohint will fail. For this reason it is
195 strongly recommended to *not* delete the original, unhinted font so that you
196 can always rerun ttfautohint.
199 Calling `ttfautohint`
200 ---------------------
203 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
206 The command-line binary, `ttfautohint`, works like a Unix filter, this is,
207 it reads data from standard input if no input file name is given, and it
208 sends its output to standard output if no output file name is specified.
210 A typical call looks like the following.
213 ttfautohint -v -f latn foo.ttf foo-autohinted.ttf
216 For demonstration purposes, here the same using a pipe and redirection.
217 Note that Windows's default command line interpreter, `cmd.exe`, doesn't
218 support piping with binary files, unfortunately.
221 cat foo.ttf | ttfautohint -v -f latn > foo-autohinted.ttf
225 Calling `ttfautohintGUI`
226 ------------------------
229 ttfautohintGUI [OPTION]...
232 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
233 the same command line options as `ttfautohint`, setting default values for
240 Long options can be given with one or two dashes, and with and without an
241 equal sign between option and argument. This means that the following forms
242 are acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and
245 Below, the section title refers to the command's label in the GUI (if
246 applicable), then comes the name of the corresponding long command line
247 option and its short equivalent, followed by a description.
249 Background and technical details on the meaning of the various options are
250 given [afterwards](#background-and-technical-details).
252 ### Hint Set Range Minimum, Hint Set Range Maximum
254 See '[Hint Sets](#hint-sets)' for a definition and explanation.
256 `--hinting-range-min=`*n*, `-l`\ *n*
257 : The minimum PPEM value (in pixels) at which hint sets are created. The
258 default value for *n* is\ 8.
260 `--hinting-range-max=`*n*, `-r`\ *n*
261 : The maximum PPEM value (in pixels) at which hint sets are created. The
262 default value for *n* is 50.
264 Increasing the range given by `-l` and `-r` normally makes the font's
269 `--default-script=`*s*, `-D`\ *s*
270 : Set default script to tag *s*, which is a string consisting of four
271 lowercase characters like `latn` or `dflt`. It is needed to specify the
272 OpenType default script: After applying all features that are handled
273 specially (like small caps or superscript), ttfautohint uses this value
274 for the remaining features. The default value is `latn`. See
275 [below](#opentype-features) for more details.
279 `--fallback-script=`*s*, `-f`\ *s*
280 : Set fallback script to tag *s*, which is a string consisting of four
281 characters like `latn` or `dflt`. It gets used for for all glyphs that
282 can't be assigned to a script automatically. The default value is
283 `none`. See [below](#scripts) for more details.
285 `--fallback-scaling`, `-S`
286 : Use scaling for glyphs covered by the fallback script, not hinting. See
287 [below](#scripts) for more details.
291 `--hinting-limit=`*n*, `-G`\ *n*
292 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
293 switched off (using the `INSTCTRL` bytecode instruction, not the `gasp`
294 table data); it does not influence the file size. The default value for
295 *n* is 200, which means that the font is not hinted for PPEM values
298 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
299 uses the hinting configuration for 'hinting-range-max'.
301 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
302 Hinting Limit' box in the GUI). Since this causes internal math
303 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
304 is strongly recommended to not use this except for testing purposes.
306 ### x Height Increase Limit
308 `--increase-x-height=`*n*, `-x`\ *n*
309 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
310 slight preference for rounding up (to use the terminology of TrueType's
311 'Super Round' bytecode instruction, the threshold is 5/8px). If this
312 flag is set, values in the range 6\ PPEM to *n*\ PPEM are much more
313 often rounded up (setting the threshold to 13/16px). The default value
314 for *n* is 14. Use this flag to increase the legibility of small sizes
315 if necessary; you might get weird rendering results otherwise for glyphs
316 like 'a' or 'e', depending on the font design.
318 To switch off this feature, use `--increase-x-height=0` (or check the
319 'No x\ Height Increase' box in the GUI). To switch off rounding the
320 x\ height to the pixel grid in general, either partially or completely,
321 see '[x Height Snapping Exceptions](#x-height-snapping-exceptions)'.
323 The following FontForge snapshot images use the font '[Mertz
324 Bold](https://github.com/vernnobile/mertzFont/tree/master/FINAL/Mertz-Bold)'
327 ![At 17px, without option `-x` and '`-w ""`', the hole in glyph 'e'
328 looks very grey in the FontForge snapshot, and the GDI ClearType
329 rendering (which is the default on older Windows versions) fills it
330 completely with black because it uses B/W rendering along the y\ axis.
331 FreeType's 'light' autohint mode (which corresponds to ttfautohint's
332 'smooth' stem width algorithm) intentionally aligns horizontal lines
333 to non-integer (but still discrete) values to avoid large glyph shape
334 distortions.](img/e-17px-x14.png)
336 ![The same, this time with option `-x 17` (and
337 '`-w ""`').](img/e-17px-x17.png)
339 ### x Height Snapping Exceptions
341 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
342 : A list of comma separated PPEM values or value ranges at which no
343 x\ height snapping shall be applied. A value range has the form
344 *value*~1~`-`*value*~2~, meaning *value*~1~\ <= PPEM <=\ *value*~2~.
345 *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
346 replaced by the beginning or end of the whole interval of valid PPEM
347 values, respectively (6\ to 32767). Whitespace is not significant;
348 superfluous commas are ignored, and ranges must be specified in
349 increasing order. For example, the string `"7-9, 11, 13-"` means the
350 values 7, 8, 9, 11, 13, 14, 15, etc. Consequently, if the supplied
351 argument is `"-"`, no x\ height snapping takes place at all. The
352 default is the empty string (`""`), meaning no snapping exceptions.
354 Normally, x\ height snapping means a slight increase in the overall
355 vertical glyph size so that the height of lowercase glyphs gets aligned
356 to the pixel grid (this is a global feature, affecting *all* glyphs of a
357 font). However, having larger vertical glyph sizes is not always
358 desired, especially if it is not possible to adjust the `usWinAscent`
359 and `usWinDescent` values from the font's `OS/2` table so that they are
360 not too tight. See '[Windows Compatibility](#windows-compatibility)'
363 ### Fallback Stem Width
365 `--fallback-stem-width=`*n*, `-H`\ *n*
366 : Set the horizontal stem width (hinting) value for all scripts that lack
367 proper standard characters in the font. The value is given in font
368 units and must be a positive integer. If not set, ttfautohint uses a
369 hard-coded default (50\ units at 2048 units per EM, and linearly scaled
370 for other UPEM values, for example 24\ units at 1000 UPEM).
372 For symbol fonts, you need option `--fallback-script` too (to set up a
375 In the GUI, uncheck the 'Default Fallback Stem Width' box to activate
378 ### Windows Compatibility
380 `--windows-compatibility`, `-W`
381 : This option makes ttfautohint add two artificial blue zones, positioned
382 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
383 table). The idea is to help ttfautohint so that the hinted glyphs stay
384 within this horizontal stripe since Windows clips everything falling
387 There is a general problem with tight values for `usWinAscent` and
388 `usWinDescent`; a good description is given in the [Vertical Metrics
389 How-To](http://typophile.com/node/13081). Additionally, there is a
390 special problem with tight values if used in combination with
391 ttfautohint because the auto-hinter tends to slightly increase the
392 vertical glyph dimensions at smaller sizes to improve legibility. This
393 enlargement can make the heights and depths of glyphs exceed the range
394 given by `usWinAscent` and `usWinDescent`.
396 If ttfautohint is part of the font creation tool chain, and the font
397 designer can adjust those two values, a better solution instead of using
398 option `-W` is to reserve some vertical space for 'padding': For the
399 auto-hinter, the difference between a top or bottom outline point before
400 and after hinting is less than 1px, thus a vertical padding of 2px is
401 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
402 gives an increase factor of 8÷6 = 1.33. This is near to the default
403 baseline-to-baseline distance used by TeX and other sophisticated text
404 processing applications, namely 1.2×designsize, which gives satisfying
405 results in most cases. It is also near to the factor 1.25 recommended
406 in the abovementioned how-to. For example, if the vertical extension of
407 the largest glyph is 2000 units (assuming that it approximately
408 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
409 could be 1.25×2000 = 2500.
411 In case ttfautohint is used as an auto-hinting tool for fonts that can
412 be no longer modified to change the metrics, option `-W` in combination
413 with '`-X "-"`' to suppress any vertical enlargement should prevent
418 `--adjust-subglyphs`, `-p`
419 : *Adjusting subglyphs* makes a font's original bytecode be applied to all
420 glyphs before it is replaced with bytecode created by ttfautohint. This
421 makes only sense if your font already has some hints in it that modify
422 the shape even at EM size (normally 2048px); in particular, some CJK
423 fonts need this because the bytecode is used to scale and shift
424 subglyphs (hence the option's long name). For most fonts, however, this
430 : By default, the components of a composite glyph get hinted separately.
431 If this flag is set, the composite glyph itself gets hinted (and the
432 hints of the components are ignored). Using this flag increases the
433 bytecode size a lot, however, it might yield better hinting results.
435 If this option is used (and a font actually contains composite glyphs),
436 ttfautohint currently cannot reprocess its own output for technical
437 reasons, see [below](#the-.ttfautohint-glyph).
442 : Process a font that ttfautohint would refuse otherwise because it can't
443 find a single standard character for any of the supported scripts.
445 For all scripts that lack proper standard characters, ttfautohint uses a
446 default (hinting) value for the standard stem width instead of deriving
447 it from a script's set of standard characters (for the latin script, one
448 of them is character 'o').
450 Use this option (usually in combination with the
451 [`--fallback-script`](#fallback-script) and/or
452 [`--fallback-stem-width`](#fallback-stem-width) option) to hint symbol
453 or dingbat fonts or math glyphs, for example.
458 : Strip off all hints without generating new hints. Consequently, all
459 other hinting options are ignored. This option is intended for testing
465 : Don't add ttfautohint version and command line information to the
466 version string or strings (with name ID\ 5) in the font's `name` table.
467 In the GUI, it corresponds to value 'None' in the 'ttfautohint
470 This option is mutually exclusive with option `-I`.
472 `--detailed-info`, `-I`
473 : Add ttfautohint version and command line information to the version
474 string or strings (with name ID\ 5) in the font's `name` table. In the
475 GUI, it corresponds to value 'Version and Parameters' in the
476 'ttfautohint info' combo box.
478 This option is mutually exclusive with option `-n`.
480 If neither `-n` nor `-I` is set, the string '`ttfautohint (vNNN)`' gets
481 added to the `name` table (with *NNN* the current version); this correponds
482 to value 'Version' in the 'ttfautohint info' combo box.
484 ### Add TTFA Info Table
487 : Add an SFNT table called `TTFA` to the output font that holds a dump of
488 all parameters; the data resembles the format of the `--debug` option's
489 parameter listing. In particular, it lists all ttfautohint control
490 instructions (which are *not* shown in the `name` table info). This
491 option is mainly for archival purposes so that all information used to
492 create a font is stored in the font itself. Note that such a `TTFA`
493 table gets ignored by all TrueType rendering engines.
495 Forthcoming versions of the ttfautohint front-ends will be able to use
496 this data so that a font can be processed another time with exactly the
497 same parameters, thus providing a means for round-tripping fonts.
501 `--family-suffix=`*string*, `-F`\ *string*
502 : A string that gets appended to the family name in entries with IDs 1, 4,
503 6, 16, and\ 21 in the font's `name` table. Allowed input is ASCII in
504 the range 0x20-0x7E except characters `%()/<>[]{}`.
506 Assuming an input family name 'Foo', a full name 'Foo Bold', and a
507 family suffix '\ 1', the output family name will be 'Foo 1' and the
508 full name 'Foo 1 Bold'. For the PostScript name in ID\ 6, ttfautohint
509 uses the suffix with space characters removed (for example 'Foo1Bold').
511 This option is mainly for testing purposes, enabling the operating
512 system to simultaneously display several instances of a font that are
513 processed with different ttfautohint parameters.
515 ### Strong Stem Width and Positioning
517 `--strong-stem-width=`*string*, `-w`\ *string*
518 : ttfautohint offers two different routines to handle (horizontal) stem
519 widths and stem positions: 'smooth' and 'strong'. The former uses
520 discrete values that slightly increase the stem contrast with almost no
521 distortion of the outlines, while the latter snaps both stem widths and
522 stem positions to integer pixel values as much as possible, yielding a
523 crisper appearance at the cost of much more distortion.
525 These two routines are mapped onto three possible rendering targets:
527 - grayscale rendering, with or without optimization for subpixel
528 positioning (e.g. Android)
530 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
531 GETINFO bytecode instruction, is in the range 36\ <= version <\ 38 and
532 ClearType is enabled (e.g. Windows XP)
534 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
535 by the GETINFO bytecode instruction, is >=\ 38, ClearType is enabled,
536 and subpixel positioning is enabled also (e.g. Internet Explorer\ 9
537 running on Windows\ 7)
539 GDI ClearType uses a mode similar to B/W rendering along the vertical
540 axis, while DW ClearType applies grayscale rendering. Additionally,
541 only DW ClearType provides subpixel positioning along the x\ axis. For
542 what it's worth, the rasterizers version\ 36 and version\ 38 in
543 Microsoft Windows are two completely different rendering engines.
545 The command line option expects *string* to contain up to three letters
546 with possible values '`g`' for grayscale, '`G`' for GDI ClearType, and
547 '`D`' for DW ClearType. If a letter is found in *string*, the strong
548 stem width routine is used for the corresponding rendering target (and
549 smooth stem width handling otherwise). The default value is '`G`', which
550 means that strong stem width handling is activated for GDI ClearType
551 only. To use smooth stem width handling for all three rendering
552 targets, use the empty string as an argument, usually connoted with
555 In the GUI, simply set the corresponding check box to select the strong
556 width routine for a given rendering target. If you unset the check box,
557 the smooth width routine gets used.
559 The following images again use the font 'Mertz Bold'.
561 ![The left part shows the glyph 'g' unhinted at 26px, the right part
562 with hints, using the 'smooth' stem algorithm.](img/ff-g-26px.png)
564 ![The same, but this time using the 'strong'
565 algorithm. Note how the stems are aligned to the pixel
566 grid.](img/ff-g-26px-wD.png)
568 ### Control Instructions File
569 `--control-file=`*file*, `-m`\ *file* (not in `ttfautohintGUI`)
570 : Specify the name of a control instructions file to manually tweak the
571 hinting process. This feature can be used to correct glitches in
572 ttfautohint's hinting algorithm. The syntax used in a control
573 instructions file is given [below](#control-instructions).
577 Watch input files (`ttfautohintGUI` only)
578 : If this checkbox is set, automatically regenerate the output file as
579 soon as an input file (either the font or the control instructions file)
582 Pressing the 'Run' button starts watching. If an error occurs, watching
583 stops and must be restarted with the 'Run' button.
585 `--ignore-restrictions`, `-i`
586 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
587 `OS/2` table are rejected. If you have a permission of the font's legal
588 owner to modify the font, specify this command line option.
590 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
591 such fonts if necessary.
594 : On the console, print a brief documentation on standard output and exit.
595 This doesn't work with `ttfautohintGUI` on MS Windows.
598 : On the console, print version information on standard output and exit.
599 This doesn't work with `ttfautohintGUI` on MS Windows.
601 `--ttfa-info`, `-T` (not in `ttfautohintGUI`)
602 : Print [`TTFA` table](#add-ttfa-info-table) of the input font on standard
603 output if present, then exit.
606 : Print *a lot* of debugging information on standard error while
607 processing a font (you should redirect stderr to a file). This
608 doesn't work with `ttfautohintGUI` on MS Windows.
610 To reduce the amount of debug data it is recommended to restrict the
611 hinting process to a single PPEM value, e.g.,
614 ttfautohint --debug -l 15 -r 15 ... > debug.txt 2>&1
619 Background and Technical Details
620 ================================
622 [Real-Time Grid Fitting of Typographic
623 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
624 paper that describes FreeType's auto-hinter in some detail. Regarding the
625 described data structures it is slightly out of date, but the algorithm
626 itself hasn't changed in general.
628 The next few subsections are mainly based on this article, introducing some
629 important concepts. Note that ttfautohint only does hinting along the
630 vertical direction (modifying y\ coordinates only).
636 A glyph consists of one or more *contours* (this is, closed curves). For
637 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
639 ![The letter 'O' has two contours, an inner and an outer one, while letter
640 'I' has only an outer contour.](img/o-and-i)
642 A *segment* is a series of consecutive points of a contour (including its
643 Bézier control points) that are approximately aligned along a coordinate
644 axis. A segment has one of three possible directions: left, right, or none
645 (which means neither left nor right), derived from the TrueType outline
646 directions. ttfautohint itself creates segments that contain at least two
647 points. Using control instructions, however, it is possible to create
648 one-point segments, which are useful for fine-tuning the hinting process.
650 ![A serif. Contour and control points are represented by squares and
651 circles, respectively. The bottom 'line' DE is approximately aligned
652 along the horizontal axis, thus it forms a segment of 7\ points. Together
653 with the two other horizontal segments, BC and FG, they form two edges
654 (BC+FG, DE).](img/segment-edge)
656 An *edge* corresponds to a single coordinate value (allowing for a small
657 threshold) on the main dimension that collects one or more segments, all
658 pointing into the same direction (either left or right, all others are
659 ignored). While finding segments is done on the unscaled outline, finding
660 edges is bound to the device resolution. See [below](#hint-sets) for an
663 In general, segments and edges pointing into different directions 'repel'
664 each other, thus preventing alignment on the same vertical coordinate if
665 they are near. Note that this is a simplification, but it should help
666 understand how to manipulate and/or create segments in control instructions
669 The analysis to find segments and edges is specific to a writing
670 system, see [below](#writing-systems).
676 The auto-hinter analyzes a font in two steps. Right now, everything
677 described here happens for the horizontal axis only, providing vertical
682 This affects the hinting of all glyphs, trying to give them a uniform
685 + Compute standard horizontal stem width of the font. The value
686 is normally taken from glyphs that resemble letter 'o'.
688 + Compute blue zones, see [below](#blue-zones).
690 If the stem widths of single glyphs differ by a large value, or if
691 ttfautohint fails to find proper blue zones, hinting becomes quite poor,
692 possibly leading even to severe shape distortions.
695 Table: script-specific standard characters of the 'latin' writing system
697 Script Standard characters
698 ---------- ---------------------
699 `arab` 'ـ', U+0640, ARABIC TATWEEL
700 'ل', U+0644, ARABIC LETTER LAM
701 'ح', U+062D, ARABIC LETTER HAH
702 `armn` 'օ', U+0585, ARMENIAN SMALL LETTER OH
703 'Օ', U+0555, ARMENIAN CAPITAL LETTER OH
704 `beng` '০', U+09E6, BENGALI DIGIT ZERO
705 '৪', U+09EA, BENGALI DIGIT FOUR
706 `cyrl` 'о', U+043E, CYRILLIC SMALL LETTER O
707 'О', U+041E, CYRILLIC CAPITAL LETTER O
708 `cher` 'Ꭴ', U+13A4, CHEROKEE LETTER U
709 'Ꮕ', U+13C5, CHEROKEE LETTER NV
710 'ꮕ', U+AB95, CHEROKEE SMALL LETTER NV
711 `deva` 'ठ', U+0920, DEVANAGARI LETTER TTHA
712 'व', U+0935, DEVANAGARI LETTER VA
713 'ट', U+091F, DEVANAGARI LETTER TTA
714 `ethi` 'ዐ', U+12D0, ETHIOPIC SYLLABLE PHARYNGEAL A
715 `geor` 'ი', U+10D8, GEORGIAN LETTER IN
716 'ე', U+10D4, GEORGIAN LETTER EN
717 'ა', U+10D0, GEORGIAN LETTER AN
718 `geok` 'Ⴖ', U+10B6, GEORGIAN CAPITAL LETTER GHAN
719 'Ⴑ', U+10B1, GEORGIAN CAPITAL LETTER SAN
720 'ⴙ', U+2D19, GEORGIAN SMALL LETTER CHIN
721 `grek` 'ο', U+03BF, GREEK SMALL LETTER OMICRON
722 'Ο', U+039F, GREEK CAPITAL LETTER OMICRON
723 `gujr` 'ટ', U+0A9F, GUJARATI LETTER TTA
724 '૦', U+0AE6, GUJARATI DIGIT ZERO
725 `guru` 'ਠ', U+0A20, GURMUKHI LETTER TTHA
726 'ਰ', U+0A30, GURMUKHI LETTER RA
727 '੦', U+0A66, GURMUKHI DIGIT ZERO
728 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
729 `knda` '೦', U+0CE6, KANNADA DIGIT ZERO
730 'ಬ', U+0CAC, KANNADA LETTER BA
731 `khmr` '០', U+17E0, KHMER DIGIT ZERO
732 `lao` '໐', U+0ED0, LAO DIGIT ZERO
733 `latn` 'o', U+006F, LATIN SMALL LETTER O
734 'O', U+004F, LATIN CAPITAL LETTER O
735 '0', U+0030, DIGIT ZERO
736 `mlym` 'ഠ', U+0D20, MALAYALAM LETTER TTHA
737 'റ', U+0D31, MALAYALAM LETTER RRA
738 `mymr` 'ဝ', U+101D, MYANMAR LETTER WA
739 'င', U+1004, MYANMAR LETTER NGA
740 'ဂ', U+1002, MYANMAR LETTER GA
741 `sinh` 'ට', U+0DA7, SINHALA LETTER ALPAPRAANA TTAYANNA
742 `taml` '௦', U+0BE6, TAMIL DIGIT ZERO
743 `telu` '౦', U+0C66, TELUGU DIGIT ZERO
744 '౧', U+0C67, TELUGU DIGIT ONE
745 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
746 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
747 '๐', U+0E50, THAI DIGIT ZERO
750 Table: standard characters of the 'latin' writing system, special scripts
752 Script Standard characters
753 ---------- ---------------------
754 `khms` '᧡', U+19E1, KHMER SYMBOL MUOY KOET
755 '᧪', U+19EA, KHMER SYMBOL DAP KOET
756 `latb` 'ₒ', U+2092, LATIN SUBSCRIPT SMALL LETTER O
757 '₀', U+2080, SUBSCRIPT ZERO
758 `latp` 'ᵒ', U+1D52, MODIFIER LETTER SMALL O
759 'ᴼ', U+1D3C, MODIFIER LETTER CAPITAL O
760 '⁰', U+2070, SUPERSCRIPT ZERO
765 This is a per-glyph operation.
767 + Find segments and edges.
769 + Link edges together to find stems and serifs. The abovementioned
770 paper gives more details on what exactly constitutes a stem or a
771 serif and how the algorithm works.
777 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
778 *all* glyphs within these zones are aligned, provided the blue zone is
779 active (this is, its vertical size is smaller than
780 3/4\ pixels).](img/blue-zones)
782 Outlines of certain characters are used to determine *blue zones*. This
783 concept is the same as with Type\ 1 fonts: All glyph points that lie in
784 certain small horizontal zones get aligned vertically.
786 Here a series of tables that show the blue zone characters of the latin
787 writing system's available scripts; the values are hard-coded in the source
788 code. Since the auto-hinter takes mean values it is not necessary that all
789 characters of a zone are present.
791 'Round' characters in blue zones (e.g., the top and bottom of 'O' or the
792 bottom of 'g') are used to control overshoot handling.
794 Blue zones marked with an asterisk are x\ height blue zones, which are
795 adjusted to be on the pixel grid (to improve rendering at small sizes) by
796 scaling the remaining blue zones before they are adjusted to the grid. See
797 also option [`--increase-x-height`](#x-height-increase-limit).
800 Table: `arab` blue zones
802 ID Blue zone Characters
803 ---- ----------- ------------
804 1 top of letters with vertical stroke ا إ ل ك ط ظ
805 2 bottom of letters ت ث ط ظ ك
809 Table: `armn` blue zones
811 ID Blue zone Characters
812 ---- ----------- ------------
813 1 top of capital letters Ա Մ Ւ Փ Բ Գ Դ Օ
814 2 bottom of capital letters Ւ Ո Փ Ճ Շ Ս Տ Օ
815 3 top of ascenders of small letters ե է ի մ վ փ ֆ փ
816 4* top of small letters ա յ ւ ս գ ջ ր օ
817 5 bottom of small letters հ ո ճ ա ե ծ ս օ
818 6 bottom of descenders of small letters բ ը ի լ ղ պ փ ց
821 Table: `beng` blue zones
823 ID Blue zone Characters
824 ---- ----------- ------------
825 1 baseline (flat glyphs only) অ ড ত ন ব ভ ল ক
826 2 top of ascenders ই ট ঠ ি ী ৈ ৗ
827 3* top of baseline ও এ ড ত ন ব ল ক
828 4 bottom of base characters অ ড ত ন ব ভ ল ক
830 Contrary to scripts like latin, the baseline in Bengali is on the top, and
831 we hint from top to bottom.
834 Table: `cher` blue zones
836 ID Blue zone Characters
837 ---- ----------- ------------
838 1 top of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
839 2 bottom of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
840 3 top of ascenders of small letters ꮒ ꮤ ꮶ ꭴ ꭾ ꮗ ꮝ ꮿ
841 4* top of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
842 5 bottom of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
843 6 bottom of descenders of small letters ᏸ ꮐ ꭹ ꭻ
846 Table: `cyrl` blue zones
848 ID Blue zone Characters
849 ---- ----------- ------------
850 1 top of capital letters Б В Е П З О С Э
851 2 bottom of capital letters Б В Е Ш З О С Э
852 3* top of small letters х п н ш е з о с
853 4 bottom of small letters х п н ш е з о с
854 5 bottom of descenders of small letters р у ф
857 Table: `deva` blue zones
859 ID Blue zone Characters
860 ---- ----------- ------------
861 1 top of ascenders ई ऐ ओ औ ि ी ो ौ
862 2 top of baseline क म अ आ थ ध भ श
863 3* top of baseline (flat glyphs only) क न म उ छ ट ठ ड
864 4 bottom of base characters क न म उ छ ट ठ ड
865 5 bottom of descenders ु ृ
867 Contrary to scripts like latin, the baseline in Devanagari is on the top,
868 and we hint from top to bottom. Note that some fonts have extreme variation
869 in the height of the round elements in Zone\ 3; for this reason we also
870 define Zone\ 1, which must be always present.
873 Table: `ethi` blue zones
875 ID Blue zone Characters
876 ---- ----------- ------------
877 1 top of letters ሀ ሃ ዘ ፐ ማ በ ዋ ዐ
878 2 bottom of letters ለ ሐ በ ዘ ሀ ሪ ዐ ጨ
881 Table: `geok` blue zones
883 ID Blue zone Characters
884 ---- ----------- ------------
885 1 top of Asomtavruli letters Ⴑ Ⴇ Ⴙ Ⴜ Ⴄ Ⴅ Ⴓ Ⴚ
886 2 bottom of Asomtavruli letters Ⴄ Ⴅ Ⴇ Ⴈ Ⴆ Ⴑ Ⴊ Ⴋ
887 3* top of Nuskhuri letters ⴁ ⴗ ⴂ ⴄ ⴅ ⴇ ⴔ ⴖ
888 4 bottom of Nuskhuri letters ⴈ ⴌ ⴖ ⴎ ⴃ ⴆ ⴋ ⴢ
889 5 top of ascender Nuskhuri letters ⴐ ⴑ ⴓ ⴕ ⴙ ⴛ ⴡ ⴣ
890 6 bottom of Nuskhuri descender letters ⴄ ⴅ ⴔ ⴕ ⴁ ⴂ ⴘ ⴝ
892 Georgian Asomtavruli and Nuskhuri form the old ecclesiastical script,
893 Khutsuri. Note that fonts show a great variation in height and depth of
894 ascender and descender letter forms.
897 Table: `geor` blue zones
899 ID Blue zone Characters
900 ---- ----------- ------------
901 1* top of Mkhedruli letters გ დ ე ვ თ ი ო ღ
902 2 bottom of Mkhedruli letters ა ზ მ ს შ ძ ხ ჰ
903 3 top of ascender Mkhedruli letters ს ხ ქ ზ მ შ ჩ წ
904 4 bottom of descender Mkhedruli letters ე ვ ჟ ტ უ ფ ქ ყ
906 Georgian Mkhedruli support is incomplete; it doesn't yet contain characters
907 for Mtavruli (which are not yet encoded in Unicode), the uppercase glyph
908 variants of Mkhedruli.
911 Table: `grek` blue zones
913 ID Blue zone Characters
914 ---- ----------- ------------
915 1 top of capital letters Γ Β Ε Ζ Θ Ο Ω
916 2 bottom of capital letters Β Δ Ζ Ξ Θ Ο
917 3 top of 'small beta' like letters β θ δ ζ λ ξ
918 4* top of small letters α ε ι ο π σ τ ω
919 5 bottom of small letters α ε ι ο π σ τ ω
920 6 bottom of descenders of small letters β γ η μ ρ φ χ ψ
923 Table: `gujr` blue zones
925 ID Blue zone Characters
926 ---- ----------- ------------
927 1* top of letters ત ન ઋ ઌ છ ટ ર ૦
928 2 bottom of letters ખ ગ ઘ ઞ ઇ ઈ ઠ જ
929 3 top of ascenders ઈ ઊ િ ી લી શ્ચિ જિ સી
930 4 bottom of descenders ુ ૃ ૄ ખુ છૃ છૄ
931 5 top of Gujarati digits ૦ ૧ ૨ ૩ ૭
934 Table: `guru` blue zones
936 ID Blue zone Characters
937 ---- ----------- ------------
938 1 top of ascenders ਇ ਈ ਉ ਏ ਓ ੳ ਿ ੀ
939 2 top of baseline ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
940 3* top of baseline (flat glyphs only) ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
941 4 bottom of characters ਅ ਏ ਓ ਗ ਜ ਠ ਰ ਸ
942 5 top of Gurmukhi digits ੦ ੧ ੨ ੩ ੭
945 Table: `hebr` blue zones
947 ID Blue zone Characters
948 ---- ----------- ------------
949 1 top of letters ב ד ה ח ך כ ם ס
950 2 bottom of letters ב ט כ ם ס צ
951 3 bottom of descenders of letters ק ך ן ף ץ
954 Table: `knda` blue zones
956 ID Blue zone Characters
957 ---- ----------- ------------
958 1 top of letters ಇ ಊ ಐ ಣ ಸಾ ನಾ ದಾ ರಾ
959 2 bottom of letters ಅ ಉ ಎ ಲ ೦ ೨ ೬ ೭
962 Table: `khmr` blue zones
964 ID Blue zone Characters
965 ---- ----------- ------------
966 1* top of letters ខ ទ ន ឧ ឩ ា
967 2 top of subscript cluster components ក្ក ក្ខ ក្គ ក្ថ
968 3 bottom of letters ខ ឃ ច ឋ ប ម យ ឲ
969 4 bottom of descenders ត្រ រៀ ឲ្យ អឿ
970 5 bottom of large descenders ន្ត្រៃ ង្ខ្យ ក្បៀ ច្រៀ ន្តឿ ល្បឿ
973 Table: `khms` blue zones
975 ID Blue zone Characters
976 ---- ----------- ------------
977 1* top of symbols for waxing ᧠ ᧡
978 2 bottom of symbols for waning ᧶ ᧹
980 Khmer symbols are used for lunar dates.
983 Table: `lao` blue zones
985 ID Blue zone Characters
986 ---- ----------- ------------
987 1* top of letters າ ດ ອ ມ ລ ວ ຣ ງ
988 2 bottom of letters າ ອ ບ ຍ ຣ ຮ ວ ຢ
989 3 top of ascenders ປ ຢ ຟ ຝ
990 4 top of large ascenders ໂ ໄ ໃ
991 5 bottom of descenders ງ ຊ ຖ ຽ ໆ ຯ
994 Table: `latb` blue zones
996 ID Blue zone Characters
997 ---- ----------- ------------
998 1 top of capital characters ₀ ₃ ₅ ₇ ₈
999 2 bottom of capital characters ₀ ₁ ₂ ₃ ₈
1000 3 top of 'small f' like characters ᵢ ⱼ ₕ ₖ ₗ
1001 4* top of small characters ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ
1002 5 bottom of small characters ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ
1003 6 bottom of descenders of small characters ᵦ ᵧ ᵨ ᵩ ₚ
1005 Subscript latin characters are similar to normal latin characters.
1008 Table: `latn` blue zones
1010 ID Blue zone Characters
1011 ---- ----------- ------------
1012 1 top of capital letters T H E Z O C Q S
1013 2 bottom of capital letters H E Z L O C U S
1014 3 top of 'small f' like letters f i j k d b h
1015 4* top of small letters x z r o e s c
1016 5 bottom of small letters x z r o e s c
1017 6 bottom of descenders of small letters p q g j y
1020 Table: `latp` blue zones
1022 ID Blue zone Characters
1023 ---- ----------- ------------
1024 1 top of capital characters ⁰ ³ ⁵ ⁷ ᵀ ᴴ ᴱ ᴼ
1025 2 bottom of capital characters ⁰ ¹ ² ³ ᴱ ᴸ ᴼ ᵁ
1026 3 top of 'small f' like characters ᵇ ᵈ ᵏ ʰ ʲ ᶠ ⁱ
1027 4* top of small characters ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ
1028 5 bottom of small characters ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ
1029 6 bottom of descenders of small characters ᵖ ʸ ᵍ
1031 Superscript latin characters are similar to normal latin characters.
1034 Table: `mlym` blue zones
1036 ID Blue zone Characters
1037 ---- ----------- ------------
1038 1 top of letters ഒ ട ഠ റ ച പ ച്ച പ്പ
1039 2 bottom of letters ട ഠ ധ ശ ഘ ച ഥ ല
1042 Table: `mymr` blue zones
1044 ID Blue zone Characters
1045 ---- ----------- ------------
1046 1* top of letters ခ ဂ င ဒ ဝ ၥ ၊ ။
1047 2 bottom of letters င ဎ ဒ ပ ဗ ဝ ၊ ။
1048 3 top of ascenders of characters ဩ ြ ၍ ၏ ၆ ါ ိ
1049 3 bottom of descenders of letters ဉ ည ဥ ဩ ဨ ၂ ၅ ၉
1052 Table: `sinh` blue zones
1054 ID Blue zone Characters
1055 ---- ----------- ------------
1056 1 top of letters ඉ ක ඝ ඳ ප ය ල ෆ
1057 2 bottom of letters එ ඔ ඝ ජ ට ථ ධ ර
1058 3 bottom of descenders of letters ද ඳ උ ල තූ තු බු දු
1061 Table: `taml` blue zones
1063 ID Blue zone Characters
1064 ---- ----------- ------------
1065 1 top of letters உ ஒ ஓ ற ஈ க ங ச
1066 2 bottom of letters க ச ல ஶ உ ங ட ப
1069 Table: `telu` blue zones
1071 ID Blue zone Characters
1072 ---- ----------- ------------
1074 2 bottom అ క చ ర ఽ ౨ ౬
1077 Table: `thai` blue zones
1079 ID Blue zone Characters
1080 ---- ----------- ------------
1082 2 bottom บ ป ษ ฯ อ ย ฮ
1084 4 large ascender โ ใ ไ
1086 6 large descender ญ ฐ
1087 7 top of Thai digits ๐ ๑ ๓
1090 ![This image shows the relevant glyph terms for vertical blue zone
1091 positions.](img/glyph-terms)
1097 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
1098 necessarily mean that the outlines are positioned *exactly* on the grid,
1099 however, especially if you want a smooth appearance at different sizes.
1100 This is the central routine of the auto-hinter; its actions are highly
1101 dependent on the used writing system. Currently, only one writing system is
1102 available (latin), providing support for scripts like Latin or Greek.
1104 * Align edges linked to blue zones.
1106 * Fit edges to the pixel grid.
1108 * Align serif edges.
1110 * Handle remaining 'strong' points. Such points are not part of an edge
1111 but are still important for defining the shape. This roughly
1112 corresponds to the `IP` TrueType instruction.
1114 * Everything else (the 'weak' points) is handled with an 'IUP'
1117 The following images illustrate the hinting process, using glyph 'a' from
1118 the freely available font '[Ubuntu Book](http://font.ubuntu.com)'. The
1119 manual hints were added by [Dalton Maag Ltd], the used application to create
1120 the hinting debug snapshots was [FontForge].
1122 ![Before hinting.](img/a-before-hinting.png)
1124 ![After hinting, using manual hints.](img/a-after-hinting.png)
1126 ![After hinting, using ttfautohint. Note that the hinting process
1127 doesn't change horizontal positions.](img/a-after-autohinting.png)
1133 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
1134 a given PPEM (pixel per EM) value.
1136 In the range given by the `--hinting-range-min` and `--hinting-range-max`
1137 options, ttfautohint creates hint sets for every PPEM value. For each
1138 glyph, ttfautohint automatically determines whether a new set should be
1139 emitted for a PPEM value if it finds that it differs from a previous one.
1140 For some glyphs it is possible that one set covers, say, the range
1141 8px-1000px, while other glyphs need 10 or more such sets.
1143 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1144 one set, in the PPEM range between `--hinting-range-max` and
1145 `--hinting-limit`, it also uses just one set.
1147 One of the hinting configuration parameters is the decision which segments
1148 form an edge. For example, let us assume that two segments get aligned on a
1149 single horizontal edge at 11px, while two edges are used at 12px. This
1150 change makes ttfautohint emit a new hint set to accomodate this situation.
1151 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1152 from the 'Ubuntu book' font, processed with ttfautohint.
1154 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
1156 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
1157 single edge, as are segments 26-0-1 and
1158 20-21.](img/afii10108-11px-after-hinting.png)
1160 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
1162 ![After hinting, size 12px. The segments are not aligned. While
1163 segments 43-27-28 and 20-21 now have almost the same horizontal position,
1164 they don't form an edge because the outlines passing through the segments
1165 point into different directions.](img/afii10108-12px-after-hinting.png)
1167 Obviously, the more hint sets get emitted, the larger the bytecode
1168 ttfautohint adds to the output font. To find a good value\ *n* for
1169 `--hinting-range-max`, some experimentation is necessary since *n* depends
1170 on the glyph shapes in the input font. If the value is too low, the hint
1171 set created for the PPEM value\ *n* (this hint set gets used for all larger
1172 PPEM values) might distort the outlines too much in the PPEM range given
1173 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1174 switched off). If the value is too high, the font size increases due to
1175 more hint sets without any noticeable hinting effects.
1177 Similar arguments hold for `--hinting-range-min` except that there is no
1178 lower limit at which hinting is switched off.
1180 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1181 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1182 out that four hint sets must be computed to exactly cover this hinting
1183 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
1184 hint set covering 10-15ppem is used, for ppem values larger than 100 the
1185 hint set covering 81-100ppem is used. For ppem values larger than 250, no
1186 hinting gets applied.
1192 The ttfautohint library (and programs) supports two solutions for handling
1193 composite glyphs, to be controlled with option
1194 [`--composites`](#hint-composites). This section contains some general
1195 information, then covers the case where the option is off, while the next
1196 section describes how ttfautohint behaves if this option is activated.
1198 Regardless of the `--composites` option, ttfautohint performs a scan over
1199 all composite glyphs to assure that components of a composite glyph inherit
1200 its style, as described [later](#opentype-features). However, components
1201 that are shifted vertically will be skipped. For example, if the glyph
1202 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1203 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1204 vertically unshifted, 'grave' does inherit the style.
1206 If `--composites` is off, components are hinted separately, then put
1207 together. Separate hinting implies that the current style's blue zones are
1208 applied to all subglyphs in its original, unshifted positions. In case you
1209 want to shift components vertically, it is *mandatory* to set bit\ 2
1210 (value\ 4), `ROUND_XY_TO_GRID`, in the flag variable of the composite glyph
1211 description to get visually pleasing results, as the images below
1214 ![Here, the subscript glyphs are composites each having a single element
1215 that is shifted down. If option `--composites` is not used, subglyphs are
1216 hinted before they are glued together (possibly applying scaling and
1217 shifting). Because the `ROUND_XY_TO_GRID` flag isn't set, the vertical
1218 translation doesn't align the subglyph to the pixel grid, causing severe
1219 distortions.](img/composite-no-round-xy-to-grid.png)
1221 ![The same as before, but with `ROUND_XY_TO_GRID` set. Now the subscript
1222 glyphs look identical to the
1223 superscripts.](img/composite-round-xy-to-grid.png)
1225 ![For comparison purposes, here the result *with* option `--composites` (and
1226 no `ROUND_XY_TO_GRID`). The composite glyphs as a whole get hinted;
1227 consequently, the subscript glyphs get separate blue zones. At the
1228 displayed size of 16ppem the vertical positions of the subscript blue
1229 zones are rounded differently if compared to the superscript zones, thus
1230 the smaller glyph height.](img/composite-no-round-xy-to-grid-option-c.png)
1233 The '\.ttfautohint' Glyph
1234 -------------------------
1236 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1237 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1238 glyph, this is, composites get recursively expanded internally so that they
1239 form simple glyphs, then hints are applied -- this is the normal working
1240 mode of FreeType's auto-hinter.
1242 One problem, however, must be solved: Hinting for subglyphs (which usually
1243 are used as normal glyphs also) must be deactivated so that nothing but the
1244 final bytecode of the composite gets executed.
1246 The trick used by ttfautohint is to prepend a composite element called
1247 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1248 job: Its bytecode increases a variable (to be more precise, it is a CVT
1249 register called `cvtl_is_subglyph` in the source code), indicating that we
1250 are within a composite glyph. The final bytecode of the composite glyph
1251 eventually decrements this variable again.
1253 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1254 subglyph 'A' as the base and 'grave' as its accent. After processing with
1255 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1256 'grave' (in this order).
1259 ------------- --------
1260 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1261 A do nothing because `cvtl_is_subglyph` > 0
1262 grave do nothing because `cvtl_is_subglyph` > 0
1263 Agrave decrease `cvtl_is_subglyph` (now: 0)\
1264 apply hints because `cvtl_is_subglyph` == 0
1266 Some technical details (which you might skip): All glyph point indices get
1267 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1268 one. This must be done for both the bytecode and one subformat of
1269 OpenType's `GPOS` anchor tables.
1271 While this approach works fine on all tested platforms, there is one single
1272 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1273 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1274 the font! Under normal circumstances this never happens because
1275 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1276 some test and demo programs like FreeType's `ftview` application or other
1277 glyph viewers that are able to bypass the `cmap` table might be affected.)
1283 In FreeType terminology, a writing system is a set of functions that
1284 provides auto-hinting for certain scripts. Right now, only two writing
1285 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1286 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1287 follow in the next section.
1293 ttfautohint needs to know which script should be used to hint a specific
1294 glyph. To do so, it checks a glyph's Unicode character code whether it
1295 belongs to a given script.
1297 See '[Character Ranges](#character-ranges)' for a complete list of all
1298 handled scripts and its ranges. This list is auto-generated from a source
1299 code file, covering the 'latin' writing system. It also covers some
1300 non-latin scripts (in the Unicode sense) that have similar typographical
1303 In ttfautohint, scripts are identified by four-character tags (if there are
1304 less characters, spaces are appended). The value `none` indicates 'no
1307 Each script is represented by two tables to handle 'base' and 'non-base'
1308 characters. For ttfautohint, a non-base character is something that should
1309 not be affected by blue zones, regardless of whether this is a spacing or
1310 no-spacing glyph. In other words, non-base characters are hinted using a
1311 script's default stem width without applying blue zones.
1313 Right now, there are two pseudo-scripts that are used as fallbacks: `latb`
1314 and `latp`, used for latin subscript and superscript characters,
1315 respectively. Its main usage is support of phonetic alphabets like the IPA,
1316 which intermix those characters with normal characters sitting on the
1317 baseline, and which are not specially handled in corresponding OpenType
1318 features like `sups`.
1320 If a glyph's character code is not covered by a script range, it is handled
1321 by a *fallback script*. By default, the fallback script is `none`, which
1322 indicates handling by the 'latin' writing system without applying
1323 script-specific blue zones (but aligning stems to the grid if possible).
1324 The fallback script can be changed; see option
1325 [`--fallback-script`](#fallback-script).
1327 The user can also select whether uncovered glyphs are either hinted (which
1328 is the default) or scaled only with the fallback script's scaling
1329 parameters. This can be controlled with option
1330 [`--fallback-scaling`](#fallback-script). Note that fallback scaling only
1331 makes sense if the fallback script has x\ height blue zones, e.g., `cyrl` or
1334 As a special case, specifying `none` as a fallback script and switching on
1335 fallback scaling ('`-f none -S`'), no hinting is applied at all to uncovered
1336 glyphs – using `none` always implies a scaling factor of\ 1.
1342 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1343 and `GPOS` tables, and how they relate to scripts.)
1345 For modern OpenType fonts, character ranges are not sufficient to handle
1348 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1349 table), which handles ligatures and similar typographic features, there
1350 is no longer a one-to-one mapping from an input Unicode character to a
1351 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1352 for historical reasons, but most of them don't. While it is possible to
1353 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1354 from this area are arbitrary by definition and thus unusable for
1357 * Some features like `sups` (for handling superscript) completely change
1358 the appearance and even vertical position of the affected glyphs.
1359 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1360 auto-hinter puts them into a separate group (called *style* in FreeType
1361 speak), having its own set of blue zones.
1364 Table: OpenType features handled specially by ttfautohint
1366 Feature tag Description
1367 --------------- -------------
1368 `c2cp` petite capitals from capitals
1369 `c2sc` small capitals from capitals
1371 `pcap` petite capitals
1372 `sinf` scientific inferiors
1373 `smcp` small capitals
1379 There are two conditions to get a valid style for a feature in a given
1382 1. One of the script's standard characters must be available in the
1385 2. The feature must provide characters to form at least one blue zone; see
1386 [above](#blue-zones).
1388 An additional complication is that features from the above table might use
1389 data not only from the `GSUB` but also from the `GPOS` table, containing
1390 information for glyph positioning. For example, the `sups` feature for
1391 superscripts might use the same glyphs as the `subs` feature for subscripts,
1392 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1393 for accessing standard characters) because glyph positioning happens after
1394 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1395 contrary to `subs`, which holds the unshifted glyphs.
1397 The remaining OpenType features of a script are not handled specially; the
1398 affected glyphs are simply hinted together with the 'normal' glyphs of the
1401 Note that a font might still contain some features not covered yet: OpenType
1402 has the concept of a *default script*; its data gets used for all scripts
1403 that aren't explicitly handled in a font. By default, ttfautohint unifies
1404 all affected glyphs from default script features with the `latn` script.
1405 This can be changed with option [`--default-script`](#default-script), if
1409 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1415 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1416 font. Note that only OpenType fonts with TrueType outlines are supported.
1417 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
1420 * `glyf`: All hints in the table are replaced with new ones. If option
1421 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1422 the '\.ttfautohint' glyph) and all composites get an additional
1425 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1426 necessary for the new hinting bytecode.
1428 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1429 grid-fitting for standard hinting, and symmetric grid-fitting and
1430 symmetric smoothing for horizontal subpixel hinting (ClearType).
1432 * `DSIG`: If it exists, it gets replaced with a dummy version.
1433 ttfautohint can't digitally sign a font; you have to do that afterwards.
1435 * `name`: The 'version' entries are modified to add information about the
1436 parameters that have been used for calling ttfautohint. This can be
1437 controlled with the [`--no-info`](#ttfautohint-info) option.
1439 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1440 additional '\.ttfautohint' glyph, the additional subglyphs in
1441 composites, and the new hinting bytecode.
1443 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1444 those tables are superfluous and thus removed.
1446 * `VDMX`: Removed, since it depends on the original bytecode, which
1447 ttfautohint removes. A font editor might recompute the necessary data
1454 ### Interaction With FreeType
1456 Recent versions of FreeType have an experimental extension for handling
1457 subpixel hinting; it is off by default and can be activated by defining the
1458 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` at compile time. This code has
1459 been contributed mainly by [Infinality], being a subset of his original
1460 patch. Many GNU/Linux distributions activate this code, or provide packages
1463 This extension changes the behaviour of many bytecode instructions to get
1464 better rendering results. However, not all changes are global; some of them
1465 are specific to certain fonts. For example, it contains font-specific
1466 improvements for the '[DejaVu] Sans' font family. The list of affected
1467 fonts is hard-coded; it can be found in FreeType's source code file
1470 If you are going to process such specially-handled fonts with ttfautohint,
1471 serious rendering problems might show up. Since ttfautohint (intentionally)
1472 doesn't change the font name in the `name` table, the Infinality extension
1473 has no chance to recognize that the hints are different. All such problems
1474 vanish if the font gets renamed in its `name` table (the name of the font
1475 file itself doesn't matter).
1477 ### Incorrect Unicode Character Map
1479 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1480 ttfautohint. Especially older fonts do cheat; for example, there exist
1481 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1482 them work with non-localized versions of Windows\ 98, say.
1484 Since ttfautohint needs to find both standard and blue zone characters, it
1485 relies on correct Unicode values. If you want to handle such fonts, please
1486 fix their `cmap` tables accordingly.
1488 ### Irregular Glyph Heights
1490 The central concept of ttfautohint's hinting algorithm, as discussed
1491 [above](#segments-and-edges), is to identify horizontal segments at extremum
1492 positions, especially for blue zones. If such a segment is missing, it
1493 cannot be associated with a blue zone, possibly leading to irregular heights
1494 for the particular glyph.
1496 Normally, a segment has a horizontal length of at least 20\ font units
1497 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1498 length of a segment must be at least 20 font units, and the height multiplied
1499 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1500 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1501 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1502 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1503 however, it is possible to define additional segments at arbitrary points
1504 that help overcome this restriction, making it possible to fix (most of)
1509 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1510 this might lead to strokes that look too thick at smaller sizes. A font
1511 designer might compensate this to a certain amount by slightly reducing the
1512 stroke width of diagonal lines. However, in many cases the sub-optimal
1513 appearance of a stroke with borders that don't exactly fit the pixel grid is
1514 not the outline itself but an incorrect gamma value of the monitor: People
1515 tend to not properly adjust it, and the default values of most operating
1516 systems are too low, causing too much darkening of such strokes. It is thus
1517 of vital importance to compare ttfautohint's results with similar fonts to
1518 exclude any systematic effect not related to the outlines themselves.
1522 Control Instructions
1523 ====================
1525 An entry in a control instructions file has various syntax forms, which are
1526 discussed here. Brackets indicate optional elements.
1529 Common Syntax Elements
1530 ----------------------
1532 *font‑idx* gives the index of the font in a TrueType Collection, starting
1533 with value\ 0. If missing, it is set to zero. For normal TrueType fonts,
1534 only value zero is valid. A font index can be specified in decimal, octal,
1535 or hexadecimal format, the latter two indicated by the prefixes `0` and
1538 *glyph‑id* is either a glyph's name as listed in the `post` SFNT table or a
1539 glyph index. A glyph name consists of characters from the set
1540 '`A-Za-z0-9._`' only and does not start with a digit or period, with the
1541 exceptions of the names '`.notdef`' and '`.null`'. A glyph index starts
1542 with value\ 0 can be specified in decimal, octal, or hexadecimal format, the
1543 latter two indicated by the prefixes `0` and `0x`, respectively. Glyph
1544 names are internally converted to glyph indices.
1546 *points* are number ranges, see '[x Height Snapping
1547 Exceptions](#x-height-snapping-exceptions)' for the syntax.
1549 Similar to the Bourne shell (`sh` or `bash`), a comment starts with
1550 character '`#`'; the rest of the line is ignored. An empty line is ignored
1551 also. Both the newline character and '`;`' can be used as a separator
1552 between exception entries. A trailing '`\`' at the end of a line continues
1553 the current line on the next one.
1555 A control instructions file is parsed line by line; later entries override
1556 earlier entries (in case there is something to override).
1562 This syntax form makes it possible to override the style assignment
1563 algorithm of ttfautohint; see '[Scripts](#scripts)' and '[OpenType
1564 Features](#opentype-features)' for more details.
1566 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`@`*\ \ glyph-ids
1568 *script* is a four-letter name of one of the scripts supported by
1569 ttfautohint. *feature* is one of the four-letter names of features
1570 supported by ttfautohint.
1572 The elements of *glyph-ids* are a list of comma separated *glyph-id* values
1573 or value ranges. Note that is not necessary that elements are specified in
1576 Assuming that a font contains superscript digits 'zero.sups' to 'nine.sups'
1577 together with the glyphs 'a.sups' and 'o.sups', use a line
1580 cyrl sups @ zero.sups-nine.sups, a.sups, o.sups
1583 to add those glyphs to the style handling Cyrillic superscript glyphs.
1584 However, it is still necessary that the selected script contains proper
1585 [Blue Zone characters](#blue-zones), otherwise those glyphs aren't handled
1588 Use the `--debug` command line option to see how ttfautohint assigns glyph
1589 indices of a font to styles.
1595 The following syntax forms allows adjustments of a glyph's hinting process.
1597 ### Change Direction of Points, Artificial Segments
1599 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ \ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
1601 The mutually exclusive parameters `left` and `right` (which can be
1602 abbreviated as '`l`' and '`r`', respectively) indicate that the following
1603 points have left or right 'out' direction, respectively, overriding
1604 ttfautohint's algorithm for setting point directions. The 'out direction'
1605 of a point is the direction of the outline *leaving* the point (or passing
1606 the control point). If the specified direction is identical to what
1607 ttfautohint computes, nothing special happens. Otherwise, a one-point
1608 segment with the specified direction gets created, see
1609 [above](#segments-and-edges). By default, its length is zero. Setting
1610 *left‑offset* and *right‑offset*, you can change the segment's horizontal
1611 start and end position relative to the point position. *left‑offset* and
1612 *right‑offset* are integers measured in font units.
1614 The following five images, displaying glyphs 'O' and 'Q' from the font
1615 [Halant-Regular](http://www.google.com/fonts/specimen/Halant), demonstrate
1616 how to use direction changes.
1618 ![The outlines of glyphs 'O' and 'Q', as displayed in FontForge. They are
1619 sufficiently similar to expect that ttfautohint hints them equally.
1620 However, this is not the case.](img/Halant-Regular-O-Q.png)
1622 ![The same glyphs, shown at 12px before hinting. [Please ignore the outline
1623 distortion in the upper right of glyph 'O'; this is a bug in FontForge
1624 while running the TrueType
1625 debugger.]](img/Halant-Regular-O-Q-unhinted-12px.png)
1627 ![Using only ttfautohint's '`-w gGD`' parameter to force strong stem width
1628 and positioning, the hinting of glyph 'Q' is really bad, making the glyph
1629 vertically two pixels larger! Reason is that this glyph doesn't contain a
1630 horizontal segment at the baseline blue zone (*y*\ =\ 1; this corresponds
1631 to the segment 13-14 in the 'O' glyph). Normally, segment 1-2 would form
1632 a 'stem' with the baseline segment (as segment 7-8 does in glyph 'O').
1633 Instead, it forms a stem with segment 19-20, which gets moved down
1634 (*y*\ =\ −1) because the whole glyph appears to be
1635 stretched.](img/Halant-Regular-O-good-Q-badly-hinted-12px.png)
1637 ![To fix the problem, we change the direction of point\ 38 to 'left' by
1638 writing a line '`Q left 38`' (without the quotes) to a control description
1639 file `Halant-Regular.txt`. Adding option '`-m Halant-Regular.txt`' to
1640 ttfautohint, we get the shown image as a result, which is much better:
1641 Segment 1-2 now properly forms a stem with our artificial one-point
1642 segment\ 38, and the 'O'-like shape is properly positioned. However,
1643 there is still room for improvement: Segment 19-20 is also positioned at
1644 the baseline, making the connection between the 'O' shape and the tail too
1645 thin.](img/Halant-Regular-O-good-Q-better-hinted-12px.png)
1647 ![By giving the one-point segment\ 38 a horizontal width, we can prevent
1648 that segment 19-20 gets positioned at the baseline: Replace the line in
1649 the previous image description with '`Q left 38 (−70,20)`', making the
1650 segment extend 70 font units to the left and 20 to the right of point\ 38.
1651 The exact offset values don't matter; it's only important to start left of
1652 point\ 19. Another solution to the problem is to artificially change the
1653 direction of segment 19-20 by adding a second line '`Q right 19-20`' to
1654 the control instructions file; for our 'Q' glyph, this produces almost
1655 exactly the same hinting results. Note that such direction changes only
1656 influence the hinting process; an outline's direction won't be changed at
1657 all.](img/Halant-Regular-O-good-Q-well-hinted-12px.png)
1659 ### Unset Direction of Points
1661 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ \ points\
1663 Parameter `nodir` (or '`n`') sets the 'out' direction of the following
1664 points to 'no direction', this is, neither left nor right. If the specified
1665 direction is identical to what ttfautohint computes, nothing special
1666 happens. Otherwise, ttfautohint no longer considers those points as part of
1667 horizontal segments, thus treating them as ['weak'](#grid-fitting) points.
1669 Modifying or adding segments doesn't directly modify the outlines; it only
1670 influences the hinting process.
1672 ### Delta Exceptions
1674 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ \ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ \ ppems\
1676 The mutually exclusive parameters `touch` and `point` (which can be
1677 abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply delta
1678 exceptions for the given points, shifting them by the given values. Delta
1679 exceptions entered with `touch` are applied before the final 'IUP'
1680 (*interpolate untouched points*) instructions in a glyph's bytecode,
1681 exceptions entered with `point` after 'IUP' (please consult Greg Hitchcock's
1682 [ClearType Whitepaper] for more on pre-IUP and post-IUP delta hints).
1683 Additionally, the `touch` parameter makes the bytecode *touch* the affected
1684 points; such points are no longer affected by 'IUP' at all. Note that in
1685 ClearType mode all deltas along the x\ axis are discarded, and deltas along
1686 the y\ axis are only executed for touched points. As a consequence,
1687 vertical delta exceptions entered with `point` should not be used in
1688 ClearType mode.^[Unfortunately, there is a bug in FreeType prior to version
1689 2.5.4 (released in December 2014) that completely disables vertical delta
1690 exceptions if subpixel hinting is activated. For this reason you should
1691 expect that the `touch` parameter fails on older GNU/Linux distributions.]
1693 *ppems*, similar to *points*, are number ranges, see '[x Height Snapping
1694 Exceptions](#x-height-snapping-exceptions)' for the syntax.
1696 *x‑shift* and *y‑shift* represent real numbers that get rounded to multiples
1697 of 1/8 pixels. The entries for `xshift` ('`x`') and `yshift` ('`y`') are
1698 optional; if missing, the corresponding value is set to zero. If both
1699 values are zero, the delta exception entry is ignored as a whole.
1701 Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0]. Values
1702 for *ppems* must be in the range [6;53]. Values for *points* are limited by
1703 the number of points in the glyph.
1705 Note that only character '`.`' is recognized as a decimal point, and a
1706 thousands separator is not accepted.
1708 As an example for delta instructions, let's assume that you want to shift
1709 points 2, 3, and\ 4 in glyph 'Aacute' at ppem sizes 12 and\ 13 by a vertical
1710 amount of 0.25 pixels. This corresponds to the line
1713 Aacute touch 2-4 yshift 0.25 @ 12, 13
1716 in a control instructions file. Since we use `touch` and not `point`,
1717 points 2, 3, and\ 4 are no longer subject to the final 'IUP' instruction,
1718 which interpolates weak, untouched point positions between strong, touched
1719 ones, cf. the description
1720 [here](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM05/Chap5.html#IUP).