6 Copyright (C) 2011-2017 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.
20 - \hyphenation{ttf-auto-hint}
27 **ttfautohint** is a library written in\ C that takes a TrueType font as
28 the input, removes its bytecode instructions (if any), and returns a new
29 font where all glyphs are bytecode hinted using the information given by
30 FreeType's auto-hinting module. The idea is to provide the excellent
31 quality of the auto-hinter on platforms that don't use FreeType.
33 The library has a single API function, `TTF_autohint`, which is described
34 [below](#the-ttfautohint-api).
36 Bundled with the library there are two front-end programs, [`ttfautohint`
37 and `ttfautohintGUI`](#ttfautohint-and-ttfautohintgui), being a command line
38 program and an application with a Graphics User Interface (GUI),
42 What exactly are hints?
43 -----------------------
45 To cite [Wikipedia](http://en.wikipedia.org/wiki/Font_hinting):
47 > **Font hinting** (also known as **instructing**) is the use of
48 > mathematical instructions to adjust the display of an outline font so that
49 > it lines up with a rasterized grid. At low screen resolutions, hinting is
50 > critical for producing a clear, legible text. It can be accompanied by
51 > antialiasing and (on liquid crystal displays) subpixel rendering for
54 and Apple's [TrueType Reference
55 Manual](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM03/Chap3.html#features):
57 > For optimal results, a font instructor should follow these guidelines:
59 > - At small sizes, chance effects should not be allowed to magnify small
60 > differences in the original outline design of a glyph.
62 > - At large sizes, the subtlety of the original design should emerge.
64 In general, there are three possible ways to hint a glyph.
66 1. The font contains hints (in the original sense of this word) to guide
67 the rasterizer, telling it which shapes of the glyphs need special
68 consideration. The hinting logic is partly in the font and partly in
69 the rasterizer. More sophisticated rasterizers are able to produce
70 better rendering results.
72 This is how Type\ 1 and CFF hints work.
74 2. The font contains exact instructions (also called *bytecode*) on how to
75 move the points of its outlines, depending on the resolution of the
76 output device, and which intentionally distort the (outline) shape to
77 produce a well-rasterized result. The hinting logic is in the font;
78 ideally, all rasterizers simply process these instructions to get the
79 same result on all platforms.
81 This is how TrueType hints work.
83 3. The font gets auto-hinted (at run-time). The hinting logic is
84 completely in the rasterizer. No hints in the font are used or needed;
85 instead, the rasterizer scans and analyzes the glyphs to apply
86 corrections by itself.
88 This is how FreeType's auto-hinter works; see
89 [below](#background-and-technical-details) for more.
92 What problems can arise with TrueType hinting?
93 ----------------------------------------------
95 While it is relatively easy to specify PostScript hints (either manually or
96 by an auto-hinter that works at font creation time), creating TrueType
97 hints is far more difficult. There are at least two reasons:
99 - TrueType instructions form a programming language, operating at a very
100 low level. They are comparable to assembler code, thus lacking all
101 high-level concepts to make programming more comfortable.
103 Here an example how such code looks like:
107 PUSHB[ ] /* 3 values pushed */
110 PUSHB[ ] /* 2 values pushed */
113 PUSHB[ ] /* 3 values pushed */
118 Another major obstacle is the fact that font designers usually aren't
121 - It is very time consuming to manually hint glyphs. Given that the
122 number of specialists for TrueType hinting is very limited, hinting a
123 large set of glyphs for a font or font family can become very expensive.
129 The ttfautohint library brings the excellent quality of FreeType rendering
130 to platforms that don't use FreeType, yet require hinting for text to look
131 good -- like Microsoft Windows. Roughly speaking, it converts the glyph
132 analysis done by FreeType's auto-hinting module to TrueType bytecode.
133 Internally, the auto-hinter's algorithm resembles PostScript hinting
134 methods; it thus combines all three hinting methods discussed
135 [previously](#what-exactly-are-hints).
137 The simple interface of the front-ends (both on the command line and with
138 the GUI) allows quick hinting of a whole font with a few mouse clicks or a
139 single command on the prompt. As a result, you get better rendering results
140 with web browsers, for example.
142 Across Windows rendering environments today, fonts processed with
143 ttfautohint look best with ClearType enabled. This is the default for
144 Windows\ 7. Good visual results are also seen in recent MacOS\ X versions
145 and GNU/Linux systems (including Android, ChromeOS, and other mobile
146 operating systems) that use FreeType for rendering glyphs.
148 The goal of the project is to generate a 'first pass' of hinting that font
149 developers can refine further for ultimate quality.
155 Fundamentally, there are two approaches to hinting. The older approach,
156 let's call it 'sharp', popular when text was rendered in pure
157 black-and-white, was to make all stems round to full pixels so that in a
158 text line, all stems would be either one pixel or (at a larger point size)
159 two pixels. When grayscale antialiasing came about, this approach actually
160 started harming the rendering rather than helping it, because the horizontal
161 and vertical stems would render very dark but round or diagonal stems would
164 So a new approach was developed, let's call it 'fuzzy', where all stems and
165 other elements are equalized so that in grayscale (or ClearType) rendering,
166 they all are of roughly equal color. This means that stems are not rounded
167 to full pixels but in fact to fractions of a pixel. However, with
168 black-and-white renderers, this approach yields poor results because in
169 black-and-white you cannot render a fraction of a pixel, so some stems
170 become one pixel and some become two.
172 The TrueType auto-hinters in [FontForge] and [FontLab Studio], to name two
173 well-known font editors, take the 'sharp' approach, while the TrueType
174 auto-hinter in ttfautohint takes the 'fuzzy' approach.
176 In theory, a hybrid approach is possible, using TrueType conditional hints:
177 If the rasterizer is black-and-white, 'sharp' rendering could happen, while
178 if the rasterizer is ClearType, the 'fuzzy' rendering could be used. It is
179 not intended to add black-and-white auto-hinting to ttfautohint. However,
180 it is planned to develop an interface so that ttfautohint can cooperate with
181 font editors, providing this hybrid hinting.
185 `ttfautohint` and `ttfautohintGUI`
186 ==================================
188 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
189 looks quite similar; the used toolkit is [Qt], which in turn uses the
190 platform's native widgets.
192 ![`ttfautohintGUI` on GNU/Linux running KDE](img/ttfautohintGUI.png)
194 Both the GUI and console version share the same features, to be discussed in
197 **Warning: ttfautohint cannot always process a font a second time.**
198 If the font contains composite glyphs, and option [`-c`](#hint-composites)
199 is used, reprocessing with ttfautohint will fail. For this reason it is
200 strongly recommended to *not* delete the original, unhinted font so that you
201 can always rerun ttfautohint.
204 Calling `ttfautohint`
205 ---------------------
208 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
211 The command-line binary, `ttfautohint`, works like a Unix filter, this is,
212 it reads data from standard input if no input file name is given, and it
213 sends its output to standard output if no output file name is specified.
215 A typical call looks like the following.
218 ttfautohint -v -f latn foo.ttf foo-autohinted.ttf
221 For demonstration purposes, here the same using a pipe and redirection.
222 Note that Windows's default command line interpreter, `cmd.exe`, doesn't
223 support piping with binary files, unfortunately.
226 cat foo.ttf | ttfautohint -v -f latn > foo-autohinted.ttf
230 Calling `ttfautohintGUI`
231 ------------------------
234 ttfautohintGUI [OPTION]...
237 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
238 (almost) the same command line options as `ttfautohint`, setting default
241 The following command line options are not available in `ttfautohintGUI`;
242 however, the corresponding functionality can be selected interactively:
243 [`--control-file`](#control-instructions-file),
244 [`--reference`](#blue-zone-reference-font),
245 [`--reference-index`](#reference-face-index).
247 Two options, namely `--ttfa-info` and `--debug`, emit information at
248 standard output and standard error, respectively; they are thus not
249 available in `ttfautohintGUI` at all.
255 Long options can be given with one or two dashes, and with and without an
256 equal sign between option and argument. This means that the following forms
257 are acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and
260 Below, the section title refers to the command's label in the GUI (if
261 applicable), then comes the name of the corresponding long command line
262 option and its short equivalent, followed by a description.
264 Background and technical details on the meaning of the various options are
265 given [afterwards](#background-and-technical-details).
267 ### Control Instructions File
269 `--control-file=`*file*, `-m`\ *file*
270 : Specify the name of a control instructions file to manually tweak the
271 hinting process. This feature can be used to correct glitches in
272 ttfautohint's hinting algorithm. The syntax used in a control
273 instructions file is given [below](#control-instructions).
275 `ttfautohintGUI` doesn't have this command line option.
277 ### Blue Zone Reference Font
279 `--reference=`*file*, `-R`\ *file*
280 : Derive all blue zones from the given font, which can either be a normal
281 TrueType font or a TrueType collection – for the latter you can select
282 the face index with a [separate option](#reference-face-index).
284 Use this to harmonize font families, avoiding ugly height differences at
287 ![Fira Regular and Bold (version 4.106), auto-hinted with ttfautohint
288 and displayed at 16px using Internet Explorer\ 11 under Windows\ 8.1.
289 The bold series shown on the right side uses the regular variant as the
290 reference font.](img/fira-16px-ie11-win81.png)
292 To make this work the reference font must obviously be similar enough to
293 the font to be hinted; in particular, it must have proper blue zone
294 characters so that ttfautohint can derive blue zones at all.
296 `ttfautohintGUI` doesn't have this command line option.
298 ### Hint Set Range Minimum, Hint Set Range Maximum
300 See '[Hint Sets](#hint-sets)' for a definition and explanation.
302 `--hinting-range-min=`*n*, `-l`\ *n*
303 : The minimum PPEM value (in pixels) at which hint sets are created. The
304 default value for *n* is\ 8.
306 `--hinting-range-max=`*n*, `-r`\ *n*
307 : The maximum PPEM value (in pixels) at which hint sets are created. The
308 default value for *n* is 50.
310 Increasing the range given by `-l` and `-r` normally makes the font's
315 `--default-script=`*s*, `-D`\ *s*
316 : Set default script to tag *s*, which is a string consisting of four
317 lowercase characters like `latn` or `dflt`. It is needed to specify the
318 OpenType default script: After applying all features that are handled
319 specially (like small caps or superscript), ttfautohint uses this value
320 for the remaining features. The default value is `latn`. See
321 [below](#opentype-features) for more details.
325 `--fallback-script=`*s*, `-f`\ *s*
326 : Set fallback script to tag *s*, which is a string consisting of four
327 characters like `latn` or `dflt`. It gets used for for all glyphs that
328 can't be assigned to a script automatically. The default value is
329 `none`. See [below](#scripts) for more details.
331 `--fallback-scaling`, `-S`
332 : Use scaling for glyphs covered by the fallback script, not hinting. See
333 [below](#scripts) for more details.
337 `--hinting-limit=`*n*, `-G`\ *n*
338 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
339 switched off (using the `INSTCTRL` bytecode instruction, not the `gasp`
340 table data); it does not influence the file size. The default value for
341 *n* is 200, which means that the font is not hinted for PPEM values
344 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
345 uses the hinting configuration for 'hinting-range-max'.
347 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
348 Hinting Limit' box in the GUI). Since this causes internal math
349 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
350 is strongly recommended to not use this except for testing purposes.
352 ### x Height Increase Limit
354 `--increase-x-height=`*n*, `-x`\ *n*
355 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
356 slight preference for rounding up (to use the terminology of TrueType's
357 'Super Round' bytecode instruction, the threshold is 5/8px). If this
358 flag is set, values in the range 6\ PPEM to *n*\ PPEM are much more
359 often rounded up (setting the threshold to 13/16px). The default value
360 for *n* is 14. Use this flag to increase the legibility of small sizes
361 if necessary; you might get weird rendering results otherwise for glyphs
362 like 'a' or 'e', depending on the font design.
364 To switch off this feature, use `--increase-x-height=0` (or check the
365 'No x\ Height Increase' box in the GUI). To switch off rounding the
366 x\ height to the pixel grid in general, either partially or completely,
367 see '[x Height Snapping Exceptions](#x-height-snapping-exceptions)'.
369 The following FontForge snapshot images use the font '[Mertz
370 Bold](https://github.com/vernnobile/mertzFont/tree/master/FINAL/Mertz-Bold)'
373 ![At 17px, without option `-x` and '`-w ""`', the hole in glyph 'e'
374 looks very grey in the FontForge snapshot, and the GDI ClearType
375 rendering (which is the default on older Windows versions) fills it
376 completely with black because it uses B/W rendering along the y\ axis.
377 FreeType's 'light' autohint mode (which corresponds to ttfautohint's
378 'smooth' stem width algorithm) intentionally aligns horizontal lines
379 to non-integer (but still discrete) values to avoid large glyph shape
380 distortions.](img/e-17px-x14.png)
382 ![The same, this time with option `-x 17` (and
383 '`-w ""`').](img/e-17px-x17.png)
385 ### x Height Snapping Exceptions
387 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
388 : A list of comma separated PPEM values or value ranges at which no
389 x\ height snapping shall be applied. A value range has the form
390 *value*~1~`-`*value*~2~, meaning *value*~1~\ <= PPEM <=\ *value*~2~.
391 *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
392 replaced by the beginning or end of the whole interval of valid PPEM
393 values, respectively (6\ to 32767). Whitespace is not significant;
394 superfluous commas are ignored, and ranges must be specified in
395 increasing order. For example, the string `"7-9, 11, 13-"` means the
396 values 7, 8, 9, 11, 13, 14, 15, etc. Consequently, if the supplied
397 argument is `"-"`, no x\ height snapping takes place at all. The
398 default is the empty string (`""`), meaning no snapping exceptions.
400 Normally, x\ height snapping means a slight increase in the overall
401 vertical glyph size so that the height of lowercase glyphs gets aligned
402 to the pixel grid (this is a global feature, affecting *all* glyphs of a
403 font). However, having larger vertical glyph sizes is not always
404 desired, especially if it is not possible to adjust the `usWinAscent`
405 and `usWinDescent` values from the font's `OS/2` table so that they are
406 not too tight. See '[Windows Compatibility](#windows-compatibility)'
409 ### Fallback Stem Width
411 `--fallback-stem-width=`*n*, `-H`\ *n*
412 : Set the horizontal stem width (hinting) value for all scripts that lack
413 proper standard characters in the font. The value is given in font
414 units and must be a positive integer. If not set, ttfautohint uses a
415 hard-coded default (50\ units at 2048 units per EM, and linearly scaled
416 for other UPEM values, for example 24\ units at 1000 UPEM).
418 For symbol fonts, you need option `--fallback-script` too (to set up a
421 In the GUI, uncheck the 'Default Fallback Stem Width' box to activate
424 ### Windows Compatibility
426 `--windows-compatibility`, `-W`
427 : This option makes ttfautohint add two artificial blue zones, positioned
428 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
429 table). The idea is to help ttfautohint so that the hinted glyphs stay
430 within this horizontal stripe since Windows clips everything falling
433 There is a general problem with tight values for `usWinAscent` and
434 `usWinDescent`; a good description is given in the [Vertical Metrics
435 How-To](http://typophile.com/node/13081). Additionally, there is a
436 special problem with tight values if used in combination with
437 ttfautohint because the auto-hinter tends to slightly increase the
438 vertical glyph dimensions at smaller sizes to improve legibility. This
439 enlargement can make the heights and depths of glyphs exceed the range
440 given by `usWinAscent` and `usWinDescent`.
442 If ttfautohint is part of the font creation tool chain, and the font
443 designer can adjust those two values, a better solution instead of using
444 option `-W` is to reserve some vertical space for 'padding': For the
445 auto-hinter, the difference between a top or bottom outline point before
446 and after hinting is less than 1px, thus a vertical padding of 2px is
447 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
448 gives an increase factor of 8÷6 = 1.33. This is near to the default
449 baseline-to-baseline distance used by TeX and other sophisticated text
450 processing applications, namely 1.2×designsize, which gives satisfying
451 results in most cases. It is also near to the factor 1.25 recommended
452 in the abovementioned how-to. For example, if the vertical extension of
453 the largest glyph is 2000 units (assuming that it approximately
454 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
455 could be 1.25×2000 = 2500.
457 In case ttfautohint is used as an auto-hinting tool for fonts that can
458 be no longer modified to change the metrics, option `-W` in combination
459 with '`-X "-"`' to suppress any vertical enlargement should prevent
464 `--adjust-subglyphs`, `-p`
465 : *Adjusting subglyphs* makes a font's original bytecode be applied to all
466 glyphs before it is replaced with bytecode created by ttfautohint. This
467 makes only sense if your font already has some hints in it that modify
468 the shape even at EM size (normally 2048px); in particular, some CJK
469 fonts need this because the bytecode is used to scale and shift
470 subglyphs (hence the option's long name). For most fonts, however, this
476 : By default, the components of a composite glyph get hinted separately.
477 If this flag is set, the composite glyph itself gets hinted (and the
478 hints of the components are ignored). Using this flag increases the
479 bytecode size a lot, however, it might yield better hinting results.
481 If this option is used (and a font actually contains composite glyphs),
482 ttfautohint currently cannot reprocess its own output for technical
483 reasons, see [below](#the-.ttfautohint-glyph).
488 : Process a font that ttfautohint would refuse otherwise because it can't
489 find a single standard character for any of the supported scripts.
491 For all scripts that lack proper standard characters, ttfautohint uses a
492 default (hinting) value for the standard stem width instead of deriving
493 it from a script's set of standard characters (for the latin script, one
494 of them is character 'o').
496 Use this option (usually in combination with the
497 [`--fallback-script`](#fallback-script) and/or
498 [`--fallback-stem-width`](#fallback-stem-width) option) to hint symbol
499 or dingbat fonts or math glyphs, for example.
504 : Strip off all hints without generating new hints. Consequently, all
505 other hinting options are ignored. This option is intended for testing
511 : Don't add ttfautohint version and command line information to the
512 version string or strings (with name ID\ 5) in the font's `name` table.
513 In the GUI, it corresponds to value 'None' in the 'ttfautohint
516 This option is mutually exclusive with option `-I`.
518 `--detailed-info`, `-I`
519 : Add ttfautohint version and command line information to the version
520 string or strings (with name ID\ 5) in the font's `name` table. In the
521 GUI, it corresponds to value 'Version and Parameters' in the
522 'ttfautohint info' combo box.
524 This option is mutually exclusive with option `-n`.
526 If neither `-n` nor `-I` is set, the string '`ttfautohint (vNNN)`' gets
527 added to the `name` table (with *NNN* the current version); this correponds
528 to value 'Version' in the 'ttfautohint info' combo box.
530 ### Add TTFA Info Table
533 : Add an SFNT table called `TTFA` to the output font that holds a dump of
534 all parameters; the data resembles the format of the `--debug` option's
535 parameter listing. In particular, it lists all ttfautohint control
536 instructions (which are *not* shown in the `name` table info). This
537 option is mainly for archival purposes so that all information used to
538 create a font is stored in the font itself. Note that such a `TTFA`
539 table gets ignored by all TrueType rendering engines.
541 Forthcoming versions of the ttfautohint front-ends will be able to use
542 this data so that a font can be processed another time with exactly the
543 same parameters, thus providing a means for round-tripping fonts.
547 `--family-suffix=`*string*, `-F`\ *string*
548 : A string that gets appended to the family name in entries with IDs 1, 4,
549 6, 16, and\ 21 in the font's `name` table. Allowed input is ASCII in
550 the range 0x20-0x7E except characters `%()/<>[]{}`.
552 Assuming an input family name 'Foo', a full name 'Foo Bold', and a
553 family suffix '\ 1', the output family name will be 'Foo 1' and the
554 full name 'Foo 1 Bold'. For the PostScript name in ID\ 6, ttfautohint
555 uses the suffix with space characters removed (for example 'Foo1Bold').
557 This option is mainly for testing purposes, enabling the operating
558 system to simultaneously display several instances of a font that are
559 processed with different ttfautohint parameters.
561 ### Reference Face Index
563 `--reference-index=`*n*, `-Z`\ *n*
564 : Set the face index for the [blue zone reference
565 font](#blue-zone-reference-font) if the font is a TrueType collection
566 (`.ttc`). For normal TrueType fonts, the value is always zero (which is
569 `ttfautohintGUI` doesn't have this command line option.
571 ### Strong Stem Width and Positioning
573 `--strong-stem-width=`*string*, `-w`\ *string*
574 : ttfautohint offers two different routines to handle (horizontal) stem
575 widths and stem positions: 'smooth' and 'strong'. The former uses
576 discrete values that slightly increase the stem contrast with almost no
577 distortion of the outlines, while the latter snaps both stem widths and
578 stem positions to integer pixel values as much as possible, yielding a
579 crisper appearance at the cost of much more distortion.
581 These two routines are mapped onto three possible rendering targets:
583 - Grayscale rendering, with or without optimization for subpixel
584 positioning (e.g., Android).
586 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
587 GETINFO bytecode instruction, is in the range 36\ <= version <=\ 38
588 and ClearType is enabled (e.g., Windows XP).
590 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
591 by the GETINFO bytecode instruction, is >=\ 39, ClearType is enabled,
592 and subpixel positioning is enabled also (e.g., Internet Explorer\ 9
593 running on Windows\ 7).
595 GDI ClearType uses a mode similar to B/W rendering along the vertical
596 axis, while DW ClearType applies grayscale rendering. Additionally,
597 only DW ClearType provides subpixel positioning along the x\ axis. For
598 what it's worth, the rasterizers version\ 36 and version\ 38 in
599 Microsoft Windows are two completely different rendering engines.
601 [Note that the GDI framework on Windows\ 10 no longer uses B/W rendering
602 along the vertical axis; we consequently treat it as DW ClearType also.
603 We test this by looking at bit\ 11 of the GETINFO instruction, which
604 was introduced in rasterizer version\ 40.]
606 The command line option expects *string* to contain up to three letters
607 with possible values '`g`' for grayscale, '`G`' for GDI ClearType, and
608 '`D`' for DW ClearType. If a letter is found in *string*, the strong
609 stem width routine is used for the corresponding rendering target (and
610 smooth stem width handling otherwise). The default value is '`G`', which
611 means that strong stem width handling is activated for GDI ClearType
612 only. To use smooth stem width handling for all three rendering
613 targets, use the empty string as an argument, usually connoted with
616 In the GUI, simply set the corresponding check box to select the strong
617 width routine for a given rendering target. If you unset the check box,
618 the smooth width routine gets used.
620 The following images again use the font 'Mertz Bold'.
622 ![The left part shows the glyph 'g' unhinted at 26px, the right part
623 with hints, using the 'smooth' stem algorithm.](img/ff-g-26px.png)
625 ![The same, but this time using the 'strong'
626 algorithm. Note how the stems are aligned to the pixel
627 grid.](img/ff-g-26px-wD.png)
631 Watch input files\ \ \ (`ttfautohintGUI` only)
632 : If this checkbox is set, automatically regenerate the output file as
633 soon as an input file (either the font, the control instructions file,
634 or the reference font) gets modified.
636 Pressing the 'Run' button starts watching. If an error occurs, watching
637 stops and must be restarted with the 'Run' button.
639 `--ignore-restrictions`, `-i`
640 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
641 `OS/2` table are rejected. If you have a permission of the font's legal
642 owner to modify the font, specify this command line option.
644 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
645 such fonts if necessary.
648 : On the console, print a brief documentation on standard output and exit.
649 This doesn't work with `ttfautohintGUI` on MS Windows.
652 : On the console, print version information on standard output and exit.
653 This doesn't work with `ttfautohintGUI` on MS Windows.
655 `--ttfa-info`, `-T`\ \ \ (not in `ttfautohintGUI`)
656 : Print [`TTFA` table](#add-ttfa-info-table) of the input font on standard
657 output if present, then exit.
659 `--debug`\ \ \ (not in `ttfautohintGUI`)
660 : Print *a lot* of debugging information on standard error while
661 processing a font (you should redirect stderr to a file).
663 To reduce the amount of debug data it is recommended to restrict the
664 hinting process to a single PPEM value, e.g.,
667 ttfautohint --debug -l 15 -r 15 ... > debug.txt 2>&1
672 Background and Technical Details
673 ================================
675 [Real-Time Grid Fitting of Typographic
676 Outlines](http://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
677 paper that describes FreeType's auto-hinter in some detail. Regarding the
678 described data structures it is slightly out of date, but the algorithm
679 itself hasn't changed in general.
681 The next few subsections are mainly based on this article, introducing some
682 important concepts. Note that ttfautohint only does hinting along the
683 vertical direction (modifying y\ coordinates only).
689 A glyph consists of one or more *contours* (this is, closed curves). For
690 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
692 ![The letter 'O' has two contours, an inner and an outer one, while letter
693 'I' has only an outer contour.](img/o-and-i)
695 A *segment* is a series of consecutive points of a contour (including its
696 Bézier control points) that are approximately aligned along a coordinate
697 axis. A segment has one of three possible directions: left, right, or none
698 (which means neither left nor right), derived from the TrueType outline
699 directions. ttfautohint itself creates segments that contain at least two
700 points. Using control instructions, however, it is possible to create
701 one-point segments, which are useful for fine-tuning the hinting process.
703 ![A serif. Contour and control points are represented by squares and
704 circles, respectively. The bottom 'line' DE is approximately aligned
705 along the horizontal axis, thus it forms a segment of 7\ points. Together
706 with the two other horizontal segments, BC and FG, they form two edges
707 (BC+FG, DE).](img/segment-edge)
709 An *edge* corresponds to a single coordinate value (allowing for a small
710 threshold) on the main dimension that collects one or more segments, all
711 pointing into the same direction (either left or right, all others are
712 ignored). While finding segments is done on the unscaled outline, finding
713 edges is bound to the device resolution. See [below](#hint-sets) for an
716 In general, segments and edges pointing into different directions 'repel'
717 each other, thus preventing alignment on the same vertical coordinate if
718 they are near. Note that this is a simplification, but it should help
719 understand how to manipulate and/or create segments in control instructions
722 The analysis to find segments and edges is specific to a writing
723 system, see [below](#writing-systems).
729 The auto-hinter analyzes a font in two steps. Right now, everything
730 described here happens for the horizontal axis only, providing vertical
735 This affects the hinting of all glyphs, trying to give them a uniform
738 + Compute standard horizontal stem width of the font. The value
739 is normally taken from glyphs that resemble letter 'o'.
741 If, for a given script, there is no glyph for at least one standard
742 character in the input font, a fallback stem width gets used. See
743 also option [`--fallback-stem-width`](#fallback-stem-width).
745 + Compute blue zones, see [below](#blue-zones).
747 If the stem widths of single glyphs differ by a large value, or if
748 ttfautohint fails to find proper blue zones, hinting becomes quite poor,
749 possibly leading even to severe shape distortions.
752 Table: script-specific standard characters of the 'latin' writing system
754 Script Standard characters
755 -------- ---------------------
756 `adlm` '𞤌', U+1E90C, ADLAM CAPITAL LETTER O
757 '𞤮', U+1E92E, ADLAM SMALL LETTER O
758 `arab` 'ـ', U+0640, ARABIC TATWEEL
759 'ل', U+0644, ARABIC LETTER LAM
760 'ح', U+062D, ARABIC LETTER HAH
761 `armn` 'օ', U+0585, ARMENIAN SMALL LETTER OH
762 'Օ', U+0555, ARMENIAN CAPITAL LETTER OH
763 `avst` '𐬚', U+10B1A, AVESTAN LETTER THE
764 `bamu` 'ꛁ', U+A6C1, BAMUM LETTER YUQ
765 'ꛯ', U+A6EF, BAMUM LETTER KOGHOM
766 `beng` '০', U+09E6, BENGALI DIGIT ZERO
767 '৪', U+09EA, BENGALI DIGIT FOUR
768 `buhd` 'ᝋ', U+174B, BUHID LETTER MA
769 'ᝏ', U+174F, BUHID LETTER WA
770 `cakm` '𑄤', U+11124, CHAKMA LETTER WAA
771 '𑄉', U+11109, CHAKMA LETTER GAA
772 '𑄛', U+1111B, CHAKMA LETTER PAA
773 `cans` 'ᑌ', U+144C, CANADIAN SYLLABICS TE
774 'ᓚ', U+14DA, CANADIAN SYLLABICS LA
775 `cari` '𐊫', U+102AB, CARIAN LETTER O
776 '𐋉', U+102C9, CARIAN LETTER RR
777 `cher` 'Ꭴ', U+13A4, CHEROKEE LETTER U
778 'Ꮕ', U+13C5, CHEROKEE LETTER NV
779 'ꮕ', U+AB95, CHEROKEE SMALL LETTER NV
780 `copt` 'Ⲟ', U+2C9E, COPTIC CAPITAL LETTER O
781 'ⲟ', U+2C9F, COPTIC SMALL LETTER O
782 `cprt` '𐠅', U+10805, CYPRIOT SYLLABLE JA
783 '𐠣', U+10823, CYPRIOT SYLLABLE RA
784 `cyrl` '\Cyrillic{}о\cyrillic{}', U+043E, CYRILLIC SMALL LETTER O
785 '\Cyrillic{}О\cyrillic{}', U+041E, CYRILLIC CAPITAL LETTER O
786 `deva` 'ठ', U+0920, DEVANAGARI LETTER TTHA
787 'व', U+0935, DEVANAGARI LETTER VA
788 'ट', U+091F, DEVANAGARI LETTER TTA
789 `dsrt` '𐐄', U+10404, DESERET CAPITAL LETTER LONG O
790 '𐐬', U+1042C, DESERET SMALL LETTER LONG O
791 `ethi` 'ዐ', U+12D0, ETHIOPIC SYLLABLE PHARYNGEAL A
792 `geor` 'ი', U+10D8, GEORGIAN LETTER IN
793 'ე', U+10D4, GEORGIAN LETTER EN
794 'ა', U+10D0, GEORGIAN LETTER AN
795 `geok` 'Ⴖ', U+10B6, GEORGIAN CAPITAL LETTER GHAN
796 'Ⴑ', U+10B1, GEORGIAN CAPITAL LETTER SAN
797 'ⴙ', U+2D19, GEORGIAN SMALL LETTER CHIN
798 `glag` 'Ⱅ', U+2C15, GLAGOLITIC CAPITAL LETTER TVRIDO
799 'ⱅ', U+2C45, GLAGOLITIC SMALL LETTER TVRIDO
800 `goth` '𐌴', U+10334, GOTHIC LETTER AIHVUS
801 '𐌾', U+1033E, GOTHIC LETTER JER
802 '𐍃', U+10343, GOTHIC LETTER SAUIL
803 `grek` '\Greek{}ο\greek{}', U+03BF, GREEK SMALL LETTER OMICRON
804 '\Greek{}Ο\greek{}', U+039F, GREEK CAPITAL LETTER OMICRON
805 `gujr` 'ટ', U+0A9F, GUJARATI LETTER TTA
806 '૦', U+0AE6, GUJARATI DIGIT ZERO
807 `guru` 'ਠ', U+0A20, GURMUKHI LETTER TTHA
808 'ਰ', U+0A30, GURMUKHI LETTER RA
809 '੦', U+0A66, GURMUKHI DIGIT ZERO
810 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
811 `kali` 'ꤍ', U+A90D, KAYAH LI LETTER NGA
812 '꤀', U+A900, KAYAH LI DIGIT ZERO
813 `knda` '೦', U+0CE6, KANNADA DIGIT ZERO
814 'ಬ', U+0CAC, KANNADA LETTER BA
815 `khmr` '០', U+17E0, KHMER DIGIT ZERO
816 `lao` '໐', U+0ED0, LAO DIGIT ZERO
817 `latn` '\Latin{}o\latin{}', U+006F, LATIN SMALL LETTER O
818 '\Latin{}O\latin{}', U+004F, LATIN CAPITAL LETTER O
819 '\Latin{}0\latin{}', U+0030, DIGIT ZERO
820 `lisu` 'ꓳ', U+A4F3, LISU LETTER
821 `mlym` 'ഠ', U+0D20, MALAYALAM LETTER TTHA
822 'റ', U+0D31, MALAYALAM LETTER RRA
823 `mymr` 'ဝ', U+101D, MYANMAR LETTER WA
824 'င', U+1004, MYANMAR LETTER NGA
825 'ဂ', U+1002, MYANMAR LETTER GA
826 `nkoo` 'ߋ', U+07CB, NKO LETTER EE
827 '߀', U+07C0, NKO DIGIT ZERO
828 `olck` 'ᱛ', U+1C5B, OL CHIKI LETTER AT
829 `orkh` '𐰗', U+10C17, OLD TURKIC LETTER YENISEI AY
830 `osge` '𐓂', U+104C2, OSAGE CAPITAL LETTER O
831 '𐓪', U+104EA, OSAGE SMALL LETTER O
832 `osma` '𐒆', U+10486, OSMANYA LETTER DEEL
833 '𐒠', U+104A0, OSMANYA DIGIT ZERO
834 `saur` 'ꢝ', U+A89D, SAURASHTRA LETTER TTHA
835 '꣐', U+A8D0, SAURASHTRA DIGIT ZERO
836 `shaw` '𐑴', U+10474, SHAVIAN LETTER OAK
837 `sinh` 'ට', U+0DA7, SINHALA LETTER ALPAPRAANA TTAYANNA
838 `sund` '᮰', U+1BB0, SUNDANESE DIGIT ZERO
839 `taml` '௦', U+0BE6, TAMIL DIGIT ZERO
840 `tavt` 'ꪒ', U+AA92, TAI VIET LETTER LOW DO
841 'ꪫ', U+AAAB, TAI VIET LETTER HIGH VO
842 `telu` '౦', U+0C66, TELUGU DIGIT ZERO
843 '౧', U+0C67, TELUGU DIGIT ONE
844 `tfng` 'ⵔ', U+2D54, TIFINAGH LETTER YAR
845 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
846 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
847 '๐', U+0E50, THAI DIGIT ZERO
848 `vaii` 'ꘓ', U+A613, VAI SYMBOL FEENG
849 'ꖜ', U+A59C, VAI SYLLABLE BHU
850 'ꖴ', U+A5B4, VAI SYLLABLE KU
853 Table: standard characters of the 'latin' writing system, special scripts
855 Script Standard characters
856 ---------- ---------------------
857 `khms` '᧡', U+19E1, KHMER SYMBOL MUOY KOET
858 '᧪', U+19EA, KHMER SYMBOL DAP KOET
859 `latb` '\Latin{}ₒ\latin{}', U+2092, LATIN SUBSCRIPT SMALL LETTER O
860 '\Latin{}₀\latin{}', U+2080, SUBSCRIPT ZERO
861 `latp` '\Latin{}ᵒ\latin{}', U+1D52, MODIFIER LETTER SMALL O
862 '\Latin{}ᴼ\latin{}', U+1D3C, MODIFIER LETTER CAPITAL O
863 '\Latin{}⁰\latin{}', U+2070, SUPERSCRIPT ZERO
868 This is a per-glyph operation.
870 + Find segments and edges.
872 + Link edges together to find stems and serifs. The abovementioned
873 paper gives more details on what exactly constitutes a stem or a
874 serif and how the algorithm works.
880 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
881 *all* glyphs within these zones are aligned, provided the blue zone is
882 active (this is, its vertical size is smaller than
883 3/4\ pixels).](img/blue-zones)
885 Outlines of certain characters are used to determine *blue zones*. This
886 concept is the same as with Type\ 1 fonts: All glyph points that lie in
887 certain small horizontal zones get aligned vertically.
889 Here a series of tables that show the blue zone characters of the latin
890 writing system's available scripts; the values are hard-coded in the source
891 code. Since the auto-hinter takes mean values it is not necessary that all
892 characters of a zone are present.
894 'Round' characters in blue zones (e.g., the top and bottom of 'O' or the
895 bottom of 'g') are used to control overshoot handling.
897 Blue zones marked with an asterisk are x\ height blue zones, which are
898 adjusted to be on the pixel grid (to improve rendering at small sizes) by
899 scaling the remaining blue zones before they are adjusted to the grid. See
900 also option [`--increase-x-height`](#x-height-increase-limit).
903 Table: `adlm` (Adlam) blue zones
905 ID Blue zone Characters
906 ---- ----------- ------------
907 1 top of capital letters 𞤌 𞤅 𞤈 𞤏 𞤔 𞤚
908 2 bottom of capital letters 𞤂 𞤖
909 3* top of small letters 𞤬 𞤮 𞤻 𞤼 𞤾
910 4 bottom of small letters 𞤤 𞤨 𞤩 𞤭 𞤴 𞤸 𞤺 𞥀
913 Table: `arab` (Arabic) blue zones
915 ID Blue zone Characters
916 ---- ----------- ------------
917 1 top of letters with vertical stroke ا إ ل ك ط ظ
918 2 bottom of letters ت ث ط ظ ك
922 Table: `armn` (Armenian) blue zones
924 ID Blue zone Characters
925 ---- ----------- ------------
926 1 top of capital letters Ա Մ Ւ Փ Բ Գ Դ Օ
927 2 bottom of capital letters Ւ Ո Փ Ճ Շ Ս Տ Օ
928 3 top of ascenders of small letters ե է ի մ վ փ ֆ փ
929 4* top of small letters ա յ ւ ս գ ջ ր օ
930 5 bottom of small letters հ ո ճ ա ե ծ ս օ
931 6 bottom of descenders of small letters բ ը ի լ ղ պ փ ց
934 Table: `avst` (Avestan) blue zones
936 ID Blue zone Characters
937 ---- ----------- ------------
938 1 top of letters 𐬀 𐬁 𐬐 𐬛
939 2 bottom of letters 𐬀 𐬁
942 Table: `bamu` (Bamum) blue zones
944 ID Blue zone Characters
945 ---- ----------- ------------
946 1 top of letters ꚧ ꚨ ꛛ ꛉ ꛁ ꛈ ꛫ ꛯ
947 2 bottom of letters ꚭ ꚳ ꚶ ꛬ ꚢ ꚽ ꛯ ꛲
950 Table: `beng` (Bengali) blue zones
952 ID Blue zone Characters
953 ---- ----------- ------------
954 1 baseline (flat glyphs only) অ ড ত ন ব ভ ল ক
955 2 top of ascenders ই ট ঠ ি ী ৈ ৗ
956 3* top of baseline ও এ ড ত ন ব ল ক
957 4 bottom of base characters অ ড ত ন ব ভ ল ক
959 Contrary to scripts like latin, the baseline in Bengali is on the top, and
960 we hint from top to bottom.
963 Table: `buhd` (Buhid) blue zones
965 ID Blue zone Characters
966 ---- ----------- ------------
968 2 top of large letters ᝅ ᝊ ᝎ
969 3* top of small letters ᝂ ᝃ ᝉ ᝌ
970 4 bottom of letters ᝀ ᝃ ᝆ ᝉ ᝋ ᝏ ᝑ
973 Table: `cakm` (Chakma) blue zones
975 ID Blue zone Characters
976 ---- ----------- ------------
977 1 top of letters 𑄃 𑄅 𑄉 𑄙 𑄗
978 2 bottom of letters 𑄅 𑄛 𑄝 𑄗 𑄓
979 3 bottom of descenders of letters 𑄖𑄳𑄢 𑄘𑄳𑄢 𑄙𑄳𑄢 𑄤𑄳𑄢 𑄥𑄳𑄢
982 Table: `cans` (Canadian Syllabics) blue zones
984 ID Blue zone Characters
985 ---- ----------- ------------
986 1 top of letters ᗜ ᖴ ᐁ ᒣ ᑫ ᑎ ᔑ ᗰ
987 2 bottom of letters ᗶ ᖵ ᒧ ᐃ ᑌ ᒍ ᔑ ᗢ
988 3* top of small letters ᓓ ᓕ ᓀ ᓂ ᓄ ᕄ ᕆ ᘣ
989 4 bottom of small letters ᕃ ᓂ ᓀ ᕂ ᓗ ᓚ ᕆ ᘣ
990 5 top of superscript letters ᐪ ᙆ ᣘ ᐢ ᒾ ᣗ ᔆ
991 6 bottom of superscript letters ᙆ ᗮ ᒻ ᐞ ᔆ ᒡ ᒢ ᓑ
994 Table: `cari` (Carian) blue zones
996 ID Blue zone Characters
997 ---- ----------- ------------
998 1 top of letters 𐊧 𐊫 𐊬 𐊭 𐊱 𐊺 𐊼 𐊿
999 2 bottom of letters 𐊣 𐊧 𐊷 𐋀 𐊫 𐊸 𐋉
1002 Table: `cher` (Cherokee) blue zones
1004 ID Blue zone Characters
1005 ---- ----------- ------------
1006 1 top of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1007 2 bottom of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1008 3 top of ascenders of small letters ꮒ ꮤ ꮶ ꭴ ꭾ ꮗ ꮝ ꮿ
1009 4* top of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1010 5 bottom of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1011 6 bottom of descenders of small letters ᏸ ꮐ ꭹ ꭻ
1014 Table: `copt` (Coptic) blue zones
1016 ID Blue zone Characters
1017 ---- ----------- ------------
1018 1 top of capital letters Ⲍ Ⲏ Ⲡ Ⳟ Ⲟ Ⲑ Ⲥ Ⳋ
1019 2 bottom of capital letters Ⳑ Ⳙ Ⳟ Ⲏ Ⲟ Ⲑ Ⳝ Ⲱ
1020 3* top of small letters ⲍ ⲏ ⲡ ⳟ ⲟ ⲑ ⲥ ⳋ
1021 4 bottom of small letters ⳑ ⳙ ⳟ ⲏ ⲟ ⲑ ⳝ Ⳓ
1024 Table: `cprt` (Cypriot) blue zones
1026 ID Blue zone Characters
1027 ---- ----------- ------------
1028 1 top of letters 𐠍 𐠙 𐠳 𐠱 𐠅 𐠓 𐠣 𐠦
1029 2 bottom of letters 𐠃 𐠊 𐠛 𐠣 𐠳 𐠵 𐠐
1030 3 top of small letters 𐠈 𐠏 𐠖
1031 4 bottom of small letters 𐠈 𐠏 𐠖
1034 Table: `cyrl` (Cyrillic) blue zones
1036 ID Blue zone Characters
1037 ---- ----------- ------------
1038 1 top of capital letters \Cyrillic{}Б В Е П З О С Э\cyrillic{}
1039 2 bottom of capital letters \Cyrillic{}Б В Е Ш З О С Э\cyrillic{}
1040 3* top of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1041 4 bottom of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1042 5 bottom of descenders of small letters \Cyrillic{}р у ф\cyrillic{}
1045 Table: `deva` (Devanagari) blue zones
1047 ID Blue zone Characters
1048 ---- ----------- ------------
1049 1 top of ascenders ई ऐ ओ औ ि ी ो ौ
1050 2 top of baseline क म अ आ थ ध भ श
1051 3* top of baseline (flat glyphs only) क न म उ छ ट ठ ड
1052 4 bottom of base characters क न म उ छ ट ठ ड
1053 5 bottom of descenders ु ृ
1055 Contrary to scripts like latin, the baseline in Devanagari is on the top,
1056 and we hint from top to bottom. Note that some fonts have extreme variation
1057 in the height of the round elements in Zone\ 3; for this reason we also
1058 define Zone\ 1, which must be always present.
1061 Table: `dsrt` (Deseret) blue zones
1063 ID Blue zone Characters
1064 ---- ----------- ------------
1065 1 top of capital letters 𐐂 𐐄 𐐋 𐐗 𐐑
1066 2 bottom of capital letters 𐐀 𐐂 𐐄 𐐗 𐐛
1067 3* top of small letters 𐐪 𐐬 𐐳 𐐿 𐐹
1068 4 bottom of small letters 𐐨 𐐪 𐐬 𐐿 𐑃
1071 Table: `ethi` (Ethiopian) blue zones
1073 ID Blue zone Characters
1074 ---- ----------- ------------
1075 1 top of letters ሀ ሃ ዘ ፐ ማ በ ዋ ዐ
1076 2 bottom of letters ለ ሐ በ ዘ ሀ ሪ ዐ ጨ
1079 Table: `geok` (Georgian Khutsuri) blue zones
1081 ID Blue zone Characters
1082 ---- ----------- ------------
1083 1 top of Asomtavruli letters Ⴑ Ⴇ Ⴙ Ⴜ Ⴄ Ⴅ Ⴓ Ⴚ
1084 2 bottom of Asomtavruli letters Ⴄ Ⴅ Ⴇ Ⴈ Ⴆ Ⴑ Ⴊ Ⴋ
1085 3* top of Nuskhuri letters ⴁ ⴗ ⴂ ⴄ ⴅ ⴇ ⴔ ⴖ
1086 4 bottom of Nuskhuri letters ⴈ ⴌ ⴖ ⴎ ⴃ ⴆ ⴋ ⴢ
1087 5 top of ascender Nuskhuri letters ⴐ ⴑ ⴓ ⴕ ⴙ ⴛ ⴡ ⴣ
1088 6 bottom of Nuskhuri descender letters ⴄ ⴅ ⴔ ⴕ ⴁ ⴂ ⴘ ⴝ
1090 Georgian Asomtavruli and Nuskhuri form the old ecclesiastical script,
1091 Khutsuri. Note that fonts show a great variation in height and depth of
1092 ascender and descender letter forms.
1095 Table: `geor` (Georgian Mkhedruli) blue zones
1097 ID Blue zone Characters
1098 ---- ----------- ------------
1099 1* top of Mkhedruli letters გ დ ე ვ თ ი ო ღ
1100 2 bottom of Mkhedruli letters ა ზ მ ს შ ძ ხ ჰ
1101 3 top of ascender Mkhedruli letters ს ხ ქ ზ მ შ ჩ წ
1102 4 bottom of descender Mkhedruli letters ე ვ ჟ ტ უ ფ ქ ყ
1104 Georgian Mkhedruli support is incomplete; it doesn't yet contain characters
1105 for Mtavruli (which are not yet encoded in Unicode), the uppercase glyph
1106 variants of Mkhedruli.
1109 Table: `glag` (Glagolitic) blue zones
1111 ID Blue zone Characters
1112 ---- ----------- ------------
1113 1 top of capital letters Ⰵ Ⱄ Ⱚ Ⰴ Ⰲ Ⰺ Ⱛ Ⰻ
1114 2 bottom of capital letters Ⰵ Ⰴ Ⰲ Ⱚ Ⱎ Ⱑ Ⰺ Ⱄ
1115 3* top of small letters ⰵ ⱄ ⱚ ⰴ ⰲ ⰺ ⱛ ⰻ
1116 4 bottom of small letters ⰵ ⰴ ⰲ ⱚ ⱎ ⱑ ⰺ ⱄ
1119 Table: `goth` (Gothic) blue zones
1121 ID Blue zone Characters
1122 ---- ----------- ------------
1123 1 top of letters 𐌲 𐌶 𐍀 𐍄 𐌴 𐍃 𐍈 𐌾
1124 2 bottom of letters 𐌶 𐌴 𐍃 𐍈
1127 Table: `grek` (Greek) blue zones
1129 ID Blue zone Characters
1130 ---- ----------- ------------
1131 1 top of capital letters \Greek{}Γ Β Ε Ζ Θ Ο Ω\greek{}
1132 2 bottom of capital letters \Greek{}Β Δ Ζ Ξ Θ Ο\greek{}
1133 3 top of 'small beta' like letters \Greek{}β θ δ ζ λ ξ\greek{}
1134 4* top of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1135 5 bottom of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1136 6 bottom of descenders of small letters \Greek{}β γ η μ ρ φ χ ψ\greek{}
1139 Table: `gujr` (Gujarati) blue zones
1141 ID Blue zone Characters
1142 ---- ----------- ------------
1143 1* top of letters ત ન ઋ ઌ છ ટ ર ૦
1144 2 bottom of letters ખ ગ ઘ ઞ ઇ ઈ ઠ જ
1145 3 top of ascenders ઈ ઊ િ ી લી શ્ચિ જિ સી
1146 4 bottom of descenders ુ ૃ ૄ ખુ છૃ છૄ
1147 5 top of Gujarati digits ૦ ૧ ૨ ૩ ૭
1150 Table: `guru` (Gurmukhi) blue zones
1152 ID Blue zone Characters
1153 ---- ----------- ------------
1154 1 top of ascenders ਇ ਈ ਉ ਏ ਓ ੳ ਿ ੀ
1155 2 top of baseline ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1156 3* top of baseline (flat glyphs only) ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1157 4 bottom of characters ਅ ਏ ਓ ਗ ਜ ਠ ਰ ਸ
1158 5 top of Gurmukhi digits ੦ ੧ ੨ ੩ ੭
1161 Table: `hebr` (Hebrew) blue zones
1163 ID Blue zone Characters
1164 ---- ----------- ------------
1165 1 top of letters ב ד ה ח ך כ ם ס
1166 2 bottom of letters ב ט כ ם ס צ
1167 3 bottom of descenders of letters ק ך ן ף ץ
1170 Table: `kali` (Kayah Li) blue zones
1172 ID Blue zone Characters
1173 ---- ----------- ------------
1174 1* top of letters ꤅ ꤏ ꤁ ꤋ ꤀ ꤍ
1175 2 bottom of letters ꤈ ꤘ ꤀ ꤍ ꤢ
1176 3 top of ascending letters ꤖ ꤡ
1177 4 bottom of descending letters ꤑ ꤜ ꤞ
1178 5 bottom of large descending letters ꤑ꤬ ꤜ꤭ ꤔ꤬
1181 Table: `khmr` (Khmer) blue zones
1183 ID Blue zone Characters
1184 ---- ----------- ------------
1185 1* top of letters ខ ទ ន ឧ ឩ ា
1186 2 top of subscript cluster components ក្ក ក្ខ ក្គ ក្ថ
1187 3 bottom of letters ខ ឃ ច ឋ ប ម យ ឲ
1188 4 bottom of descenders ត្រ រៀ ឲ្យ អឿ
1189 5 bottom of large descenders ន្ត្រៃ ង្ខ្យ ក្បៀ ច្រៀ ន្តឿ ល្បឿ
1192 Table: `khms` (Khmer Symbols) blue zones
1194 ID Blue zone Characters
1195 ---- ----------- ------------
1196 1* top of symbols for waxing ᧠ ᧡
1197 2 bottom of symbols for waning ᧶ ᧹
1199 Khmer symbols are used for lunar dates.
1202 Table: `knda` (Kannada) blue zones
1204 ID Blue zone Characters
1205 ---- ----------- ------------
1206 1 top of letters ಇ ಊ ಐ ಣ ಸಾ ನಾ ದಾ ರಾ
1207 2 bottom of letters ಅ ಉ ಎ ಲ ೦ ೨ ೬ ೭
1210 Table: `lao` (Lao) blue zones
1212 ID Blue zone Characters
1213 ---- ----------- ------------
1214 1* top of letters າ ດ ອ ມ ລ ວ ຣ ງ
1215 2 bottom of letters າ ອ ບ ຍ ຣ ຮ ວ ຢ
1216 3 top of ascenders ປ ຢ ຟ ຝ
1217 4 top of large ascenders ໂ ໄ ໃ
1218 5 bottom of descenders ງ ຊ ຖ ຽ ໆ ຯ
1221 Table: `latb` (Latin Subscripts) blue zones
1223 ID Blue zone Characters
1224 ---- ----------- ------------
1225 1 top of capital characters \Latin{}₀ ₃ ₅ ₇ ₈\latin{}
1226 2 bottom of capital characters \Latin{}₀ ₁ ₂ ₃ ₈\latin{}
1227 3 top of 'small f' like characters \Latin{}ᵢ ⱼ ₕ ₖ ₗ\latin{}
1228 4* top of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1229 5 bottom of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1230 6 bottom of descenders of small characters \Latin{}ᵦ ᵧ ᵨ ᵩ ₚ\latin{}
1232 Subscript latin characters are similar to normal latin characters.
1235 Table: `latn` (Latin) blue zones
1237 ID Blue zone Characters
1238 ---- ----------- ------------
1239 1 top of capital letters \Latin{}T H E Z O C Q S\latin{}
1240 2 bottom of capital letters \Latin{}H E Z L O C U S\latin{}
1241 3 top of 'small f' like letters \Latin{}f i j k d b h\latin{}
1242 4* top of small letters \Latin{}u v x z o e s c\latin{}
1243 5 bottom of small letters \Latin{}n r x z o e s c\latin{}
1244 6 bottom of descenders of small letters \Latin{}p q g j y\latin{}
1247 Table: `latp` (Latin Superscripts) blue zones
1249 ID Blue zone Characters
1250 ---- ----------- ------------
1251 1 top of capital characters \Latin{}⁰ ³ ⁵ ⁷ ᵀ ᴴ ᴱ ᴼ\latin{}
1252 2 bottom of capital characters \Latin{}⁰ ¹ ² ³ ᴱ ᴸ ᴼ ᵁ\latin{}
1253 3 top of 'small f' like characters \Latin{}ᵇ ᵈ ᵏ ʰ ʲ ᶠ ⁱ\latin{}
1254 4* top of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1255 5 bottom of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1256 6 bottom of descenders of small characters \Latin{}ᵖ ʸ ᵍ\latin{}
1258 Superscript latin characters are similar to normal latin characters.
1261 Table: `lisu` (Lisu) blue zones
1263 ID Blue zone Characters
1264 ---- ----------- ------------
1265 1 top of letters ꓡ ꓧ ꓱ ꓶ ꓩ ꓚ ꓵ ꓳ
1266 2 bottom of letters ꓕ ꓜ ꓞ ꓡ ꓛ ꓢ ꓳ ꓴ
1269 Table: `mlym` (Malayalam) blue zones
1271 ID Blue zone Characters
1272 ---- ----------- ------------
1273 1 top of letters ഒ ട ഠ റ ച പ ച്ച പ്പ
1274 2 bottom of letters ട ഠ ധ ശ ഘ ച ഥ ല
1277 Table: `mymr` (Myanmar) blue zones
1279 ID Blue zone Characters
1280 ---- ----------- ------------
1281 1* top of letters ခ ဂ င ဒ ဝ ၥ ၊ ။
1282 2 bottom of letters င ဎ ဒ ပ ဗ ဝ ၊ ။
1283 3 top of ascenders of characters ဩ ြ ၍ ၏ ၆ ါ ိ
1284 3 bottom of descenders of letters ဉ ည ဥ ဩ ဨ ၂ ၅ ၉
1287 Table: `nkoo` (N'Ko) blue zones
1289 ID Blue zone Characters
1290 ---- ----------- ------------
1291 1 top of letters ߐ ߉ ߒ ߟ ߖ ߜ ߠ ߥ
1292 2 bottom of letters ߀ ߘ ߡ ߠ ߥ
1293 3* top of small letters ߏ ߛ ߋ
1294 4 bottom of small letters ߎ ߏ ߛ ߋ
1297 Table: `olck` (Ol Chiki) blue zones
1299 ID Blue zone Characters
1300 ---- ----------- ------------
1301 1 top of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1302 2 bottom of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1305 Table: `orkh` (Old Turkic) blue zones
1307 ID Blue zone Characters
1308 ---- ----------- ------------
1309 1 top of letters 𐰗 𐰘 𐰧
1310 2 bottom of letters 𐰉 𐰗 𐰦 𐰧
1313 Table: `osge` (Osage) blue zones
1315 ID Blue zone Characters
1316 ---- ----------- ------------
1317 1 top of capital letters 𐒾 𐓍 𐓒 𐓓 𐒻 𐓂 𐒵 𐓆
1318 2 bottom of capital letters 𐒰 𐓍 𐓂 𐒿 𐓎 𐒹
1319 3 bottom of descenders of capital letters 𐒼 𐒽 𐒾
1320 4* top of small letters 𐓵 𐓶 𐓺 𐓻 𐓝 𐓣 𐓪 𐓮
1321 5 bottom of small letters 𐓘 𐓚 𐓣 𐓵 𐓡 𐓧 𐓪 𐓶
1322 6 top of ascenders of small letters 𐓤 𐓦 𐓸 𐓹 𐓛
1323 7 bottom of descenders of small letters 𐓤 𐓥 𐓦
1326 Table: `osma` (Osmanya) blue zones
1328 ID Blue zone Characters
1329 ---- ----------- ------------
1330 1 top of letters 𐒆 𐒉 𐒐 𐒒 𐒘 𐒛 𐒠 𐒣
1331 2 bottom of letters 𐒀 𐒂 𐒆 𐒈 𐒊 𐒒 𐒠 𐒩
1334 Table: `saur` (Saurashtra) blue zones
1336 ID Blue zone Characters
1337 ---- ----------- ------------
1338 1 top of letters ꢜ ꢞ ꢳ ꢂ ꢖ ꢒ ꢝ ꢛ
1339 2 bottom of letters ꢂ ꢨ ꢺ ꢤ ꢎ
1342 Table: `shaw` (Shavian) blue zones
1344 ID Blue zone Characters
1345 ---- ----------- ------------
1346 1 top of letters 𐑕 𐑙
1347 2 bottom of letters 𐑔 𐑖 𐑗 𐑹 𐑻
1348 3 bottom of descenders of letters 𐑟 𐑣
1349 4* top of small letters 𐑱 𐑲 𐑳 𐑴 𐑸 𐑺 𐑼
1350 5 bottom of small letters 𐑴 𐑻 𐑹
1353 Table: `sinh` (Sinhala) blue zones
1355 ID Blue zone Characters
1356 ---- ----------- ------------
1357 1 top of letters ඉ ක ඝ ඳ ප ය ල ෆ
1358 2 bottom of letters එ ඔ ඝ ජ ට ථ ධ ර
1359 3 bottom of descenders of letters ද ඳ උ ල තූ තු බු දු
1362 Table: `sund` (Sundanese) blue zones
1364 ID Blue zone Characters
1365 ---- ----------- ------------
1366 1 top of letters ᮋ ᮞ ᮮ ᮽ ᮰ ᮈ
1367 2 bottom of letters ᮄ ᮔ ᮕ ᮗ ᮰ ᮆ ᮈ ᮉ
1368 3 bottom of descenders of letters ᮼ ᳄
1371 Table: `taml` (Tamil) blue zones
1373 ID Blue zone Characters
1374 ---- ----------- ------------
1375 1 top of letters உ ஒ ஓ ற ஈ க ங ச
1376 2 bottom of letters க ச ல ஶ உ ங ட ப
1379 Table: `tavt` (Tai Viet) blue zones
1381 ID Blue zone Characters
1382 ---- ----------- ------------
1383 1 top of letters ꪆ ꪔ ꪒ ꪖ ꪫ
1384 2 bottom of letters ꪉ ꪫ ꪮ
1387 Table: `telu` (Telugu) blue zones
1389 ID Blue zone Characters
1390 ---- ----------- ------------
1391 1 top of letters ఇ ఌ ఙ ఞ ణ ఱ ౯
1392 2 bottom of letters అ క చ ర ఽ ౨ ౬
1395 Table: `tfng` (Tifinagh) blue zones
1397 ID Blue zone Characters
1398 ---- ----------- ------------
1399 1 top of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1400 2 bottom of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1403 Table: `thai` (Thai) blue zones
1405 ID Blue zone Characters
1406 ---- ----------- ------------
1407 1* top of letters บ เ แ อ ก า
1408 2 bottom of letters บ ป ษ ฯ อ ย ฮ
1409 3 top of ascenders of letters ป ฝ ฟ
1410 4 top of large ascenders of letters โ ใ ไ
1411 5 bottom of descenders of letters ฎ ฏ ฤ ฦ
1412 6 bottom of large descenders of letters ญ ฐ
1413 7 top of Thai digits ๐ ๑ ๓
1416 Table: `vaii` (Vai) blue zones
1418 ID Blue zone Characters
1419 ---- ----------- ------------
1420 1 top of vai letters ꗍ ꘖ ꘙ ꘜ ꖜ ꖝ ꔅ ꕢ
1421 2 bottom of vai letters ꗍ ꘖ ꘙ ꗞ ꔅ ꕢ ꖜ ꔆ
1424 ![This image shows the relevant glyph terms for vertical blue zone
1425 positions.](img/glyph-terms)
1431 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
1432 necessarily mean that the outlines are positioned *exactly* on the grid,
1433 however, especially if you want a smooth appearance at different sizes.
1434 This is the central routine of the auto-hinter; its actions are highly
1435 dependent on the used writing system. Currently, only one writing system is
1436 available (latin), providing support for scripts like Latin or Greek.
1438 * Align edges linked to blue zones.
1440 * Fit edges to the pixel grid.
1442 * Align serif edges.
1444 * Handle remaining 'strong' points. Such points are not part of an edge
1445 but are still important for defining the shape. This roughly
1446 corresponds to the `IP` TrueType instruction.
1448 * Everything else (the 'weak' points) is handled with an 'IUP'
1451 The following images illustrate the hinting process, using glyph 'a' from
1452 the freely available font '[Ubuntu Book](http://font.ubuntu.com)'. The
1453 manual hints were added by [Dalton Maag Ltd], the used application to create
1454 the hinting debug snapshots was [FontForge].
1456 ![Before hinting.](img/a-before-hinting.png)
1458 ![After hinting, using manual hints.](img/a-after-hinting.png)
1460 ![After hinting, using ttfautohint. Note that the hinting process
1461 doesn't change horizontal positions.](img/a-after-autohinting.png)
1467 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
1468 a given PPEM (pixel per EM) value.
1470 In the range given by the `--hinting-range-min` and `--hinting-range-max`
1471 options, ttfautohint creates hint sets for every PPEM value. For each
1472 glyph, ttfautohint automatically determines whether a new set should be
1473 emitted for a PPEM value if it finds that it differs from a previous one.
1474 For some glyphs it is possible that one set covers, say, the range
1475 8px-1000px, while other glyphs need 10 or more such sets.
1477 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1478 one set, in the PPEM range between `--hinting-range-max` and
1479 `--hinting-limit`, it also uses just one set.
1481 One of the hinting configuration parameters is the decision which segments
1482 form an edge. For example, let us assume that two segments get aligned on a
1483 single horizontal edge at 11px, while two edges are used at 12px. This
1484 change makes ttfautohint emit a new hint set to accomodate this situation.
1485 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1486 from the 'Ubuntu book' font, processed with ttfautohint.
1488 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
1490 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
1491 single edge, as are segments 26-0-1 and
1492 20-21.](img/afii10108-11px-after-hinting.png)
1494 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
1496 ![After hinting, size 12px. The segments are not aligned. While
1497 segments 43-27-28 and 20-21 now have almost the same horizontal position,
1498 they don't form an edge because the outlines passing through the segments
1499 point into different directions.](img/afii10108-12px-after-hinting.png)
1501 Obviously, the more hint sets get emitted, the larger the bytecode
1502 ttfautohint adds to the output font. To find a good value\ *n* for
1503 `--hinting-range-max`, some experimentation is necessary since *n* depends
1504 on the glyph shapes in the input font. If the value is too low, the hint
1505 set created for the PPEM value\ *n* (this hint set gets used for all larger
1506 PPEM values) might distort the outlines too much in the PPEM range given
1507 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1508 switched off). If the value is too high, the font size increases due to
1509 more hint sets without any noticeable hinting effects.
1511 Similar arguments hold for `--hinting-range-min` except that there is no
1512 lower limit at which hinting is switched off.
1514 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1515 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1516 out that four hint sets must be computed to exactly cover this hinting
1517 range: 10-15, 16-40, 41-80, and 81-100. For ppem values below 10ppem, the
1518 hint set covering 10-15ppem is used, for ppem values larger than 100 the
1519 hint set covering 81-100ppem is used. For ppem values larger than 250, no
1520 hinting gets applied.
1526 The ttfautohint library (and programs) supports two solutions for handling
1527 composite glyphs, to be controlled with option
1528 [`--composites`](#hint-composites). This section contains some general
1529 information, then covers the case where the option is off, while the next
1530 section describes how ttfautohint behaves if this option is activated.
1532 Regardless of the `--composites` option, ttfautohint performs a scan over
1533 all composite glyphs to assure that components of a composite glyph inherit
1534 its style, as described [later](#opentype-features). However, components
1535 that are shifted vertically will be skipped. For example, if the glyph
1536 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1537 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1538 vertically unshifted, 'grave' does inherit the style.
1540 If `--composites` is off, components are hinted separately, then put
1541 together. Separate hinting implies that the current style's blue zones are
1542 applied to all subglyphs in its original, unshifted positions. In case you
1543 want to shift components vertically, it is *mandatory* to set bit\ 2
1544 (value\ 4), `ROUND_XY_TO_GRID`, in the flag variable of the composite glyph
1545 description to get visually pleasing results, as the images below
1548 ![Here, the subscript glyphs are composites each having a single element
1549 that is shifted down. If option `--composites` is not used, subglyphs are
1550 hinted before they are glued together (possibly applying scaling and
1551 shifting). Because the `ROUND_XY_TO_GRID` flag isn't set, the vertical
1552 translation doesn't align the subglyph to the pixel grid, causing severe
1553 distortions.](img/composite-no-round-xy-to-grid.png)
1555 ![The same as before, but with `ROUND_XY_TO_GRID` set. Now the subscript
1556 glyphs look identical to the
1557 superscripts.](img/composite-round-xy-to-grid.png)
1559 ![For comparison purposes, here the result *with* option `--composites` (and
1560 no `ROUND_XY_TO_GRID`). The composite glyphs as a whole get hinted;
1561 consequently, the subscript glyphs get separate blue zones. At the
1562 displayed size of 16ppem the vertical positions of the subscript blue
1563 zones are rounded differently if compared to the superscript zones, thus
1564 the smaller glyph height.](img/composite-no-round-xy-to-grid-option-c.png)
1567 The '\.ttfautohint' Glyph
1568 -------------------------
1570 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1571 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1572 glyph, this is, composites get recursively expanded internally so that they
1573 form simple glyphs, then hints are applied -- this is the normal working
1574 mode of FreeType's auto-hinter.
1576 One problem, however, must be solved: Hinting for subglyphs (which usually
1577 are used as normal glyphs also) must be deactivated so that nothing but the
1578 final bytecode of the composite gets executed.
1580 The trick used by ttfautohint is to prepend a composite element called
1581 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1582 job: Its bytecode increases a variable (to be more precise, it is a CVT
1583 register called `cvtl_is_subglyph` in the source code), indicating that we
1584 are within a composite glyph. The final bytecode of the composite glyph
1585 eventually decrements this variable again.
1587 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1588 subglyph 'A' as the base and 'grave' as its accent. After processing with
1589 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1590 'grave' (in this order).
1593 ------------- --------
1594 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1595 A do nothing because `cvtl_is_subglyph` > 0
1596 grave do nothing because `cvtl_is_subglyph` > 0
1597 Agrave decrease `cvtl_is_subglyph` (now: 0)
1598 apply hints because `cvtl_is_subglyph` == 0
1600 Some technical details (which you might skip): All glyph point indices get
1601 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1602 one. This must be done for both the bytecode and one subformat of
1603 OpenType's `GPOS` anchor tables.
1605 While this approach works fine on all tested platforms, there is one single
1606 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1607 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1608 the font! Under normal circumstances this never happens because
1609 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1610 some test and demo programs like FreeType's `ftview` application or other
1611 glyph viewers that are able to bypass the `cmap` table might be affected.)
1617 In FreeType terminology, a writing system is a set of functions that
1618 provides auto-hinting for certain scripts. Right now, only two writing
1619 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1620 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1621 follow in the next section.
1627 ttfautohint needs to know which script should be used to hint a specific
1628 glyph. To do so, it checks a glyph's Unicode character code whether it
1629 belongs to a given script.
1631 See '[Character Ranges](#character-ranges)' for a complete list of all
1632 handled scripts and its ranges. This list is auto-generated from a source
1633 code file, covering the 'latin' writing system. It also covers some
1634 non-latin scripts (in the Unicode sense) that have similar typographical
1637 In ttfautohint, scripts are identified by four-character tags (if there are
1638 less characters, spaces are appended). The value `none` indicates 'no
1641 Each script is represented by two tables to handle 'base' and 'non-base'
1642 characters. For ttfautohint, a non-base character is something that should
1643 not be affected by blue zones, regardless of whether this is a spacing or
1644 no-spacing glyph. In other words, non-base characters are hinted using a
1645 script's default stem width without applying blue zones.
1647 Right now, there are two pseudo-scripts that are used as fallbacks: `latb`
1648 and `latp`, used for latin subscript and superscript characters,
1649 respectively. Its main usage is support of phonetic alphabets like the IPA,
1650 which intermix those characters with normal characters sitting on the
1651 baseline, and which are not specially handled in corresponding OpenType
1652 features like `sups`.
1654 If a glyph's character code is not covered by a script range, it is handled
1655 by a *fallback script*. By default, the fallback script is `none`, which
1656 indicates handling by the 'latin' writing system without applying
1657 script-specific blue zones (but aligning stems to the grid if possible).
1658 The fallback script can be changed; see option
1659 [`--fallback-script`](#fallback-script).
1661 The user can also select whether uncovered glyphs are either hinted (which
1662 is the default) or scaled only with the fallback script's scaling
1663 parameters. This can be controlled with option
1664 [`--fallback-scaling`](#fallback-script). Note that fallback scaling only
1665 makes sense if the fallback script has x\ height blue zones, e.g., `cyrl` or
1668 As a special case, specifying `none` as a fallback script and switching on
1669 fallback scaling ('`-f none -S`'), no hinting is applied at all to uncovered
1670 glyphs – using `none` always implies a scaling factor of\ 1.
1676 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1677 and `GPOS` tables, and how they relate to scripts.)
1679 For modern OpenType fonts, character ranges are not sufficient to handle
1682 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1683 table), which handles ligatures and similar typographic features, there
1684 is no longer a one-to-one mapping from an input Unicode character to a
1685 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1686 for historical reasons, but most of them don't. While it is possible to
1687 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1688 from this area are arbitrary by definition and thus unusable for
1691 * Some features like `sups` (for handling superscript) completely change
1692 the appearance and even vertical position of the affected glyphs.
1693 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1694 auto-hinter puts them into a separate group (called *style* in FreeType
1695 speak), having its own set of blue zones.
1698 Table: OpenType features handled specially by ttfautohint
1700 Feature tag Description
1701 --------------- -------------
1702 `c2cp` petite capitals from capitals
1703 `c2sc` small capitals from capitals
1705 `pcap` petite capitals
1706 `sinf` scientific inferiors
1707 `smcp` small capitals
1713 There are two conditions to get a valid style for a feature in a given
1716 1. One of the script's standard characters must be available in the
1719 2. The feature must provide characters to form at least one blue zone; see
1720 [above](#blue-zones).
1722 An additional complication is that features from the above table might use
1723 data not only from the `GSUB` but also from the `GPOS` table, containing
1724 information for glyph positioning. For example, the `sups` feature for
1725 superscripts might use the same glyphs as the `subs` feature for subscripts,
1726 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1727 for accessing standard characters) because glyph positioning happens after
1728 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1729 contrary to `subs`, which holds the unshifted glyphs.
1731 The remaining OpenType features of a script are not handled specially; the
1732 affected glyphs are simply hinted together with the 'normal' glyphs of the
1735 Note that a font might still contain some features not covered yet: OpenType
1736 has the concept of a *default script*; its data gets used for all scripts
1737 that aren't explicitly handled in a font. By default, ttfautohint unifies
1738 all affected glyphs from default script features with the `latn` script.
1739 This can be changed with option [`--default-script`](#default-script), if
1743 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1749 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1750 font. Note that only OpenType fonts with TrueType outlines are supported.
1751 OpenType fonts with a `CFF` table (this is, with PostScript outlines) won't
1754 * `glyf`: All hints in the table are replaced with new ones. If option
1755 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1756 the '\.ttfautohint' glyph) and all composites get an additional
1759 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1760 necessary for the new hinting bytecode.
1762 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1763 grid-fitting for standard hinting, and symmetric grid-fitting and
1764 symmetric smoothing for horizontal subpixel hinting (ClearType).
1766 * `DSIG`: If it exists, it gets replaced with a dummy version.
1767 ttfautohint can't digitally sign a font; you have to do that afterwards.
1769 * `name`: The 'version' entries are modified to add information about the
1770 parameters that have been used for calling ttfautohint. This can be
1771 controlled with the [`--no-info`](#ttfautohint-info) option.
1773 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1774 additional '\.ttfautohint' glyph, the additional subglyphs in
1775 composites, and the new hinting bytecode.
1777 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1778 those tables are superfluous and thus removed.
1780 * `VDMX`: Removed, since it depends on the original bytecode, which
1781 ttfautohint removes. A font editor might recompute the necessary data
1788 ### Interaction With FreeType
1790 Recent versions of FreeType have an experimental extension for handling
1791 subpixel hinting; it is off by default and can be activated by defining the
1792 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` at compile time. This code has
1793 been contributed mainly by [Infinality], being a subset of his original
1794 patch. Many GNU/Linux distributions activate this code, or provide packages
1797 This extension changes the behaviour of many bytecode instructions to get
1798 better rendering results. However, not all changes are global; some of them
1799 are specific to certain fonts. For example, it contains font-specific
1800 improvements for the '[DejaVu] Sans' font family. The list of affected
1801 fonts is hard-coded; it can be found in FreeType's source code file
1804 If you are going to process such specially-handled fonts with ttfautohint,
1805 serious rendering problems might show up. Since ttfautohint (intentionally)
1806 doesn't change the font name in the `name` table, the Infinality extension
1807 has no chance to recognize that the hints are different. All such problems
1808 vanish if the font gets renamed in its `name` table (the name of the font
1809 file itself doesn't matter).
1811 ### Incorrect Unicode Character Map
1813 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1814 ttfautohint. Especially older fonts do cheat; for example, there exist
1815 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1816 them work with non-localized versions of Windows\ 98, say.
1818 Since ttfautohint needs to find both standard and blue zone characters, it
1819 relies on correct Unicode values. If you want to handle such fonts, please
1820 fix their `cmap` tables accordingly.
1822 ### Irregular Glyph Heights
1824 The central concept of ttfautohint's hinting algorithm, as discussed
1825 [above](#segments-and-edges), is to identify horizontal segments at extremum
1826 positions, especially for blue zones. If such a segment is missing, it
1827 cannot be associated with a blue zone, possibly leading to irregular heights
1828 for the particular glyph.
1830 Normally, a segment has a horizontal length of at least 20\ font units
1831 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1832 length of a segment must be at least 20 font units, and the height multiplied
1833 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1834 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1835 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1836 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1837 however, it is possible to define additional segments at arbitrary points
1838 that help overcome this restriction, making it possible to fix (most of)
1843 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1844 this might lead to strokes that look too thick at smaller sizes. A font
1845 designer might compensate this to a certain amount by slightly reducing the
1846 stroke width of diagonal lines. However, in many cases the sub-optimal
1847 appearance of a stroke with borders that don't exactly fit the pixel grid is
1848 not the outline itself but an incorrect gamma value of the monitor: People
1849 tend to not properly adjust it, and the default values of most operating
1850 systems are too low, causing too much darkening of such strokes. It is thus
1851 of vital importance to compare ttfautohint's results with similar fonts to
1852 exclude any systematic effect not related to the outlines themselves.
1855 Extending ttfautohint with new scripts
1856 --------------------------------------
1858 Right now, adding new scripts to ttfautohint only works on the source code
1859 level, this is, you have to patch the C\ source code.
1861 The process itself isn't very complicated; it is demonstrated best by
1862 example. The following commits in ttfautohint add Ethiopian and Armenian,
1865 | [http://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07](http://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07)
1866 | [http://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9](http://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9)
1868 It shows that you have to do the following steps.
1870 * Add blue zone character data to the file `lib/tablue.dat`.
1872 * Add the proper Unicode ranges to `lib/taranges.c`, following the
1873 structure of similar entries.
1875 * Similarly, the files `lib/tastyles.h` and `lib/ttfautohint-script.h`
1876 must be updated. The latter holds the information on the used default
1877 character or characters; it also references the corresponding script tag
1878 `HB_SCRIPT_XXX` as used by the HarfBuzz library.
1880 If there are any questions, please contact the [FreeType mailing
1881 list](https://lists.nongnu.org/mailman/listinfo/freetype) for help. Note
1882 that the script data in ttfautohint are hold in sync with FreeType's
1886 Control Instructions
1887 ====================
1889 An entry in a control instructions file has various syntax forms, which are
1890 discussed here. Brackets indicate optional elements.
1893 Common Syntax Elements
1894 ----------------------
1896 *font‑idx* gives the index of the font in a TrueType Collection, starting
1897 with value\ 0. If missing, it is set to zero. For normal TrueType fonts,
1898 only value zero is valid. A font index can be specified in decimal, octal,
1899 or hexadecimal format, the latter two indicated by the prefixes `0` and
1902 *glyph‑id* is either a glyph's name as listed in the `post` SFNT table or a
1903 glyph index. A glyph name consists of characters from the set
1904 '`A-Za-z0-9._`' only and does not start with a digit or period, with the
1905 exceptions of the names '`.notdef`' and '`.null`'. A glyph index starts
1906 with value\ 0 can be specified in decimal, octal, or hexadecimal format, the
1907 latter two indicated by the prefixes `0` and `0x`, respectively. Glyph
1908 names are internally converted to glyph indices.
1910 *points* are number ranges, see '[x Height Snapping
1911 Exceptions](#x-height-snapping-exceptions)' for the syntax.
1913 Similar to the Bourne shell (`sh` or `bash`), a comment starts with
1914 character '`#`'; the rest of the line is ignored. An empty line is ignored
1915 also. Both the newline character and '`;`' can be used as a separator
1916 between exception entries. A trailing '`\`' at the end of a line continues
1917 the current line on the next one.
1919 A control instructions file is parsed line by line; later entries override
1920 earlier entries (in case there is something to override).
1926 This syntax form makes it possible to override the style assignment
1927 algorithm of ttfautohint; see '[Scripts](#scripts)' and '[OpenType
1928 Features](#opentype-features)' for more details.
1930 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`@`*\ \ glyph-ids
1932 *script* is a four-letter name^[The notable exception is the tag 'lao',
1933 which originally has a trailing space as the fourth character. However,
1934 ttfautohint ignores the space.] of one of the scripts supported by
1935 ttfautohint. *feature* is one of the four-letter names of features
1936 supported by ttfautohint.
1938 The elements of *glyph-ids* are a list of comma separated *glyph-id* values
1939 or value ranges. Note that is not necessary that elements are specified in
1942 Assuming that a font contains superscript digits 'zero.sups' to 'nine.sups'
1943 together with the glyphs 'a.sups' and 'o.sups', use a line
1946 cyrl sups @ zero.sups-nine.sups, a.sups, o.sups
1949 to add those glyphs to the style handling Cyrillic superscript glyphs.
1950 However, it is still necessary that the selected script contains proper
1951 [Blue Zone characters](#blue-zones), otherwise those glyphs aren't handled
1954 Use the `--debug` command line option to see how ttfautohint assigns glyph
1955 indices of a font to styles.
1958 Stem Width Adjustments
1959 ----------------------
1961 Use the following syntax form to adjust stem width values for a given style,
1962 overriding ttfautohint's algorithm; see '[Scripts](#scripts)' and '[OpenType
1963 Features](#opentype-features)' for more details. This adjustment doesn't
1964 change the glyph shapes; it only influences the hinting process.
1966 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`w[idth]`*\ \ stem-widths
1968 *script* and *feature* are the same as with style adjustments; see above.
1969 However, *script* can additionally be the wildcard character '`*`', which
1970 indicates 'any script'.
1972 The elements of *stem-widths* are an unsorted list of comma separated
1973 integer *stem-width* values (in font units); the first value gives the
1974 style's default stem width.
1976 The effect of this adjustment depends [on the selected stem width
1977 algorithm](#strong-stem-width-and-positioning). For smooth stem width
1978 positioning, only the first (i.e., the default) value is used; it gets a
1979 higher preference than other discrete stem width choices. For strong stem
1980 width positioning, the stem widths are snapped to the provided values (if
1981 not differing too much) before rounding to an integer pixel value.
1983 A typical example is to reduce the default stem width of an extra-bold font,
1984 which gets better hinted if a stem width of, say, 100 is used instead of the
1985 default value 150. Let's also assume that the font further contains latin
1986 subscript and superscript characters that are hinted best with a stem width
1987 set to 80 font units. We can achieve this with the following lines in a
1988 control instructions file.
1997 Without the adjustment chances are very high that the 'eyes' in glyphs 'e'
1998 or 'a' of extra-bold fonts are filled at smaller ppem values.
2000 Use the `--debug` command line option to see how ttfautohint assigns stem
2001 widths to styles by default.
2007 The following syntax forms allows adjustments of a glyph's hinting process.
2009 ### Change Direction of Points, Artificial Segments
2011 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ \ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
2013 The mutually exclusive parameters `left` and `right` (which can be
2014 abbreviated as '`l`' and '`r`', respectively) indicate that the following
2015 points have left or right 'out' direction, respectively, overriding
2016 ttfautohint's algorithm for setting point directions. The 'out direction'
2017 of a point is the direction of the outline *leaving* the point (or passing
2018 the control point). If the specified direction is identical to what
2019 ttfautohint computes, nothing special happens. Otherwise, a one-point
2020 segment with the specified direction gets created, see
2021 [above](#segments-and-edges). By default, its length is zero. Setting
2022 *left‑offset* and *right‑offset*, you can change the segment's horizontal
2023 start and end position relative to the point position. *left‑offset* and
2024 *right‑offset* are integers measured in font units.
2026 The following five images, displaying glyphs 'O' and 'Q' from the font
2027 [Halant-Regular](http://www.google.com/fonts/specimen/Halant), demonstrate
2028 how to use direction changes.
2030 ![The outlines of glyphs 'O' and 'Q', as displayed in FontForge. They are
2031 sufficiently similar to expect that ttfautohint hints them equally.
2032 However, this is not the case.](img/Halant-Regular-O-Q.png)
2034 ![The same glyphs, shown at 12px before hinting. [Please ignore the outline
2035 distortion in the upper right of glyph 'O'; this is a bug in FontForge
2036 while running the TrueType
2037 debugger.]](img/Halant-Regular-O-Q-unhinted-12px.png)
2039 ![Using only ttfautohint's '`-w gGD`' parameter to force strong stem width
2040 and positioning, the hinting of glyph 'Q' is really bad, making the glyph
2041 vertically two pixels larger! Reason is that this glyph doesn't contain a
2042 horizontal segment at the baseline blue zone (*y*\ =\ 1; this corresponds
2043 to the segment 13-14 in the 'O' glyph). Normally, segment 1-2 would form
2044 a 'stem' with the baseline segment (as segment 7-8 does in glyph 'O').
2045 Instead, it forms a stem with segment 19-20, which gets moved down
2046 (*y*\ =\ −1) because the whole glyph appears to be
2047 stretched.](img/Halant-Regular-O-good-Q-badly-hinted-12px.png)
2049 ![To fix the problem, we change the direction of point\ 38 to 'left' by
2050 writing a line '`Q left 38`' (without the quotes) to a control description
2051 file `Halant-Regular.txt`. Adding option '`-m Halant-Regular.txt`' to
2052 ttfautohint, we get the shown image as a result, which is much better:
2053 Segment 1-2 now properly forms a stem with our artificial one-point
2054 segment\ 38, and the 'O'-like shape is properly positioned. However,
2055 there is still room for improvement: Segment 19-20 is also positioned at
2056 the baseline, making the connection between the 'O' shape and the tail too
2057 thin.](img/Halant-Regular-O-good-Q-better-hinted-12px.png)
2059 ![By giving the one-point segment\ 38 a horizontal width, we can prevent
2060 that segment 19-20 gets positioned at the baseline: Replace the line in
2061 the previous image description with '`Q left 38 (−70,20)`', making the
2062 segment extend 70 font units to the left and 20 to the right of point\ 38.
2063 The exact offset values don't matter; it's only important to start left of
2064 point\ 19. Another solution to the problem is to artificially change the
2065 direction of segment 19-20 by adding a second line '`Q right 19-20`' to
2066 the control instructions file; for our 'Q' glyph, this produces almost
2067 exactly the same hinting results. Note that such direction changes only
2068 influence the hinting process; an outline's direction won't be changed at
2069 all.](img/Halant-Regular-O-good-Q-well-hinted-12px.png)
2071 ### Unset Direction of Points
2073 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ \ points\
2075 Parameter `nodir` (or '`n`') sets the 'out' direction of the following
2076 points to 'no direction', this is, neither left nor right. If the specified
2077 direction is identical to what ttfautohint computes, nothing special
2078 happens. Otherwise, ttfautohint no longer considers those points as part of
2079 horizontal segments, thus treating them as ['weak'](#grid-fitting) points.
2081 Modifying or adding segments doesn't directly modify the outlines; it only
2082 influences the hinting process.
2084 ### Delta Exceptions
2086 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ \ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ \ ppems\
2088 The mutually exclusive parameters `touch` and `point` (which can be
2089 abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply delta
2090 exceptions for the given points, shifting them by the given values. Delta
2091 exceptions entered with `touch` are applied before the final 'IUP'
2092 (*interpolate untouched points*) instructions in a glyph's bytecode,
2093 exceptions entered with `point` after 'IUP' (please consult Greg Hitchcock's
2094 [ClearType Whitepaper] for more on pre-IUP and post-IUP delta hints).
2095 Additionally, the `touch` parameter makes the bytecode *touch* the affected
2096 points; such points are no longer affected by 'IUP' at all. Note that in
2097 ClearType mode all deltas along the x\ axis are discarded, and deltas along
2098 the y\ axis are only executed for touched points. As a consequence,
2099 vertical delta exceptions entered with `point` should not be used in
2100 ClearType mode.^[Unfortunately, there is a bug in FreeType prior to version
2101 2.5.4 (released in December 2014) that completely disables vertical delta
2102 exceptions if subpixel hinting is activated. For this reason you should
2103 expect that the `touch` parameter fails on older GNU/Linux distributions.]
2105 *ppems*, similar to *points*, are number ranges, see '[x Height Snapping
2106 Exceptions](#x-height-snapping-exceptions)' for the syntax.
2108 *x‑shift* and *y‑shift* represent real numbers that get rounded to multiples
2109 of 1/8 pixels. The entries for `xshift` ('`x`') and `yshift` ('`y`') are
2110 optional; if missing, the corresponding value is set to zero. If both
2111 values are zero, the delta exception entry is ignored as a whole.
2113 Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0]. Values
2114 for *ppems* must be in the range [6;53]. Values for *points* are limited by
2115 the number of points in the glyph.
2117 Note that only character '`.`' is recognized as a decimal point, and a
2118 thousands separator is not accepted.
2120 As an example for delta instructions, let's assume that you want to shift
2121 points 2, 3, and\ 4 in glyph 'Aacute' at ppem sizes 12 and\ 13 by a vertical
2122 amount of 0.25 pixels. This corresponds to the line
2125 Aacute touch 2-4 yshift 0.25 @ 12, 13
2128 in a control instructions file. Since we use `touch` and not `point`,
2129 points 2, 3, and\ 4 are no longer subject to the final 'IUP' instruction,
2130 which interpolates weak, untouched point positions between strong, touched
2131 ones, cf. the description
2132 [here](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM05/Chap5.html#IUP).