6 Copyright (C) 2011-2019 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 central 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](https://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 PostScript 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 and higher. Good visual results are also seen in recent MacOS\ X
145 versions and GNU/Linux systems (including Android, ChromeOS, and other
146 mobile operating systems) that use FreeType for rendering glyphs.
152 Fundamentally, there are two approaches to hinting. The older approach,
153 let's call it 'sharp', popular when text was rendered in pure
154 black-and-white, was to make all stems round to full pixels so that in a
155 text line, all stems would be either one pixel or (at a larger point size)
156 two pixels. When grayscale antialiasing came about, this approach actually
157 started harming the rendering rather than helping it, because the horizontal
158 and vertical stems would render very dark but round or diagonal stems would
161 So a new approach was developed, let's call it 'fuzzy', where all stems and
162 other elements are equalized so that in grayscale (or ClearType) rendering,
163 they all are of roughly equal color. This means that stems are not rounded
164 to full pixels but in fact to fractions of a pixel. However, with
165 black-and-white renderers, this approach yields poor results because in
166 black-and-white you cannot render a fraction of a pixel, so some stems
167 become one pixel and some become two.
169 The TrueType auto-hinters in [FontForge] and [FontLab Studio], to name two
170 well-known font editors, take the 'sharp' approach, while the TrueType
171 auto-hinter in ttfautohint takes the 'fuzzy' approach.
173 In theory, a hybrid approach is possible, using TrueType conditional hints:
174 If the rasterizer is black-and-white, 'sharp' rendering could happen, while
175 if the rasterizer is ClearType, the 'fuzzy' rendering could be used. It is
176 not intended to add black-and-white auto-hinting to ttfautohint. However,
177 it is planned to develop an interface so that ttfautohint can cooperate with
178 font editors, providing this hybrid hinting.
182 `ttfautohint` and `ttfautohintGUI`
183 ==================================
185 On all supported platforms (GNU/Linux, Windows, and Mac OS\ X), the GUI
186 looks quite similar; the used toolkit is [Qt], which in turn uses the
187 platform's native widgets.
189 ![`ttfautohintGUI` on GNU/Linux running KDE](img/ttfautohintGUI.png)
191 Both the GUI and console version share the same features, to be discussed in
194 **Warning: ttfautohint cannot always process a font a second time.**
195 If the font contains composite glyphs, and option [`-c`](#hint-composites)
196 is used, reprocessing with ttfautohint will fail. For this reason it is
197 strongly recommended to *not* delete the original, unhinted font so that you
198 can always rerun ttfautohint.
201 Calling `ttfautohint`
202 ---------------------
205 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
208 The command-line binary, `ttfautohint`, works like a Unix filter, this is,
209 it reads data from standard input if no input file name is given, and it
210 sends its output to standard output if no output file name is specified.
212 A typical call looks like the following.
215 ttfautohint -v -t -m foo-control.txt foo.ttf foo-autohinted.ttf
218 For demonstration purposes, here the same using a pipe and redirection.
219 Note that Windows's default command line interpreter, `cmd.exe`, doesn't
220 support piping with binary files, unfortunately.
223 cat foo.ttf | ttfautohint -v -t -m foo-control.txt > foo-autohinted.ttf
227 Calling `ttfautohintGUI`
228 ------------------------
231 ttfautohintGUI [OPTION]...
234 `ttfautohintGUI` doesn't send any output to a console; however, it accepts
235 (almost) the same command line options as `ttfautohint` to provide
236 customized default values of the GUI.
238 The following command line options are not available in `ttfautohintGUI`:
239 [`--control-file`](#control-instructions-file),
240 [`--reference`](#blue-zone-reference-font),
241 [`--reference-index`](#reference-face-index). Note, however, that the
242 corresponding functionality can be selected interactively.
244 Two options, namely `--ttfa-info` and `--debug`, emit information at
245 standard output and standard error, respectively; they are thus not
246 available in `ttfautohintGUI`, too, and there is no corresponding GUI
247 functionality either.
253 Long options can be given with one or two dashes, and with and without an
254 equal sign between option and argument. This means that the following forms
255 are acceptable: `-foo=`*bar*, `--foo=`*bar*, `-foo`\ *bar*, and
258 Below, the section title refers to the command's label in the GUI (if
259 applicable), then comes the name of the corresponding long command line
260 option and its short equivalent, followed by a description.
262 Background and technical details on the meaning of the various options are
263 given [afterwards](#background-and-technical-details).
265 ### Control Instructions File
267 `--control-file=`*file*, `-m`\ *file*
268 : Specify the name of a control instructions file to manually tweak the
269 hinting process. This feature can be used to correct glitches in
270 ttfautohint's hinting algorithm. The syntax used in a control
271 instructions file is given [below](#control-instructions).
273 `ttfautohintGUI` doesn't have this command line option.
275 ### Blue Zone Reference Font
277 `--reference=`*file*, `-R`\ *file*
278 : Derive all blue zones from the given font, which can either be a normal
279 TrueType font or a TrueType collection – for the latter you can select
280 the face index with a [separate option](#reference-face-index).
282 Use this to harmonize font families, avoiding ugly height differences at
285 ![Fira Regular and Bold (version 4.106), auto-hinted with ttfautohint
286 and displayed at 16px using Internet Explorer\ 11 under Windows\ 8.1.
287 The bold series shown on the right side uses the regular variant as
288 the reference font.](img/fira-16px-ie11-win81.png)
290 To make this work the reference font must obviously be similar enough to
291 the font to be hinted; in particular, it must have proper blue zone
292 characters so that ttfautohint can derive blue zones at all.
294 `ttfautohintGUI` doesn't have this command line option.
296 ### Hint Set Range Minimum, Hint Set Range Maximum
298 See '[Hint Sets](#hint-sets)' for a definition and explanation.
300 `--hinting-range-min=`*n*, `-l`\ *n*
301 : The minimum PPEM value (in pixels) at which hint sets are created. The
302 default value for *n* is\ 8.
304 `--hinting-range-max=`*n*, `-r`\ *n*
305 : The maximum PPEM value (in pixels) at which hint sets are created. The
306 default value for *n* is 50.
308 Increasing the range given by `-l` and `-r` normally makes the font's
313 `--default-script=`*s*, `-D`\ *s*
314 : Set default script to tag *s*, which is a string consisting of four
315 lowercase characters like `latn` or `dflt`. It is needed to specify the
316 OpenType default script: After applying all features that are handled
317 specially (like small caps or superscript), ttfautohint uses this value
318 for the remaining features. The default value is `latn`. See
319 [below](#opentype-features) for more details.
323 `--fallback-script=`*s*, `-f`\ *s*
324 : Set fallback script to tag *s*, which is a string consisting of four
325 characters like `latn` or `dflt`. It gets used for all glyphs that
326 can't be assigned to a script automatically. The default value is
327 `none`. See [below](#scripts) for more details.
329 `--fallback-scaling`, `-S`
330 : Use scaling for glyphs covered by the fallback script, not hinting. See
331 [below](#scripts) for more details.
335 `--hinting-limit=`*n*, `-G`\ *n*
336 : The *hinting limit* is the PPEM value (in pixels) where hinting gets
337 switched off (using the `INSTCTRL` bytecode instruction, not the `gasp`
338 table data); it does not influence the file size. The default value for
339 *n* is 200, which means that the font is not hinted for PPEM values
342 Note that hinting in the range 'hinting-range-max' up to 'hinting-limit'
343 uses the hinting configuration for 'hinting-range-max'.
345 To omit a hinting limit, use `--hinting-limit=0` (or check the 'No
346 Hinting Limit' box in the GUI). Since this causes internal math
347 overflow in the rasterizer for large pixel values (>\ 1500px approx.) it
348 is strongly recommended to not use this except for testing purposes.
350 ### x Height Increase Limit
352 `--increase-x-height=`*n*, `-x`\ *n*
353 : Normally, ttfautohint rounds the x\ height to the pixel grid, with a
354 slight preference for rounding up (to use the terminology of TrueType's
355 'Super Round' bytecode instruction, the threshold is 5/8px). If this
356 flag is set, values in the PPEM range 6 to\ *n* are much more often
357 rounded up (setting the threshold to 13/16px). The default value for
358 *n* is 14. Use this flag to increase the legibility of small sizes if
359 necessary; you might get weird rendering results otherwise for glyphs
360 like 'a' or 'e', depending on the font design.
362 To switch off this feature, use `--increase-x-height=0` (or check the
363 'No x\ Height Increase' box in the GUI). To switch off rounding the
364 x\ height to the pixel grid in general, either partially or completely,
365 see '[x Height Snapping Exceptions](#x-height-snapping-exceptions)'.
367 The following FontForge snapshot images use the font '[Mertz
368 Bold](https://github.com/vernnobile/mertzFont/tree/master/FINAL/Mertz-Bold)'
371 ![At 17px, without option `-x` and `-a qqq`, the hole in glyph 'e' looks
372 very grey in the FontForge snapshot, and the GDI ClearType rendering
373 (which is the default on older Windows versions) fills it completely
374 with black because it uses B/W rendering along the y\ axis.
375 ttfautohint's 'smooth' stem width algorithm intentionally aligns
376 horizontal lines to non-integer (but still discrete) values to avoid
377 large glyph shape distortions.](img/e-17px-x14.png)
379 ![The same, this time with option `-x 17` (and
380 `-a qqq`).](img/e-17px-x17.png)
382 ### x Height Snapping Exceptions
384 `--x-height-snapping-exceptions=`*string*, `-X`\ *string*
385 : A list of comma separated PPEM values or value ranges at which no
386 x\ height snapping shall be applied. A value range has the form
387 *value*~1~`-`*value*~2~, meaning *value*~1~\ <= PPEM <=\ *value*~2~.
388 *value*~1~ or *value*~2~ (or both) can be missing; a missing value is
389 replaced by the beginning or end of the whole interval of valid PPEM
390 values, respectively (6\ to 32767). Whitespace is not significant;
391 superfluous commas are ignored, and ranges must be specified in
392 increasing order. For example, the string `"7-9, 11, 13-"` means the
393 values 7, 8, 9, 11, 13, 14, 15, etc. Consequently, if the supplied
394 argument is `"-"`, no x\ height snapping takes place at all. The
395 default is the empty string (`""`), meaning no snapping exceptions.
397 Normally, x\ height snapping means a slight increase in the overall
398 vertical glyph size so that the height of lowercase glyphs gets aligned
399 to the pixel grid (this is a global feature, affecting *all* glyphs of a
400 font). However, having larger vertical glyph sizes is not always
401 desired, especially if it is not possible to adjust the `usWinAscent`
402 and `usWinDescent` values from the font's `OS/2` table so that they are
403 not too tight. See '[Windows Compatibility](#windows-compatibility)'
406 ### Fallback Stem Width
408 `--fallback-stem-width=`*n*, `-H`\ *n*
409 : Set the horizontal stem width (hinting) value for all scripts that lack
410 proper standard characters in the font. The value is given in font
411 units and must be a positive integer. If not set, ttfautohint uses a
412 hard-coded default (50\ units at 2048 units per EM, and linearly scaled
413 for other UPEM values, for example 24\ units at 1000 UPEM).
415 For symbol fonts, you need option `--fallback-script` too (to set up a
418 In the GUI, uncheck the 'Default Fallback Stem Width' box to activate
421 ### Windows Compatibility
423 `--windows-compatibility`, `-W`
424 : This option makes ttfautohint add two artificial blue zones, positioned
425 at the `usWinAscent` and `usWinDescent` values (from the font's `OS/2`
426 table). The idea is to help ttfautohint so that the hinted glyphs stay
427 within this horizontal stripe since older versions of Windows clip
428 everything that lies outside.
430 There is a general problem with tight values for `usWinAscent` and
431 `usWinDescent`; a good description is given in the [Vertical Metrics
432 How-To](http://typophile.com/node/13081). Additionally, there is a
433 special problem with tight values if used in combination with
434 ttfautohint because the auto-hinter tends to slightly increase the
435 vertical glyph dimensions at smaller sizes to improve legibility. This
436 enlargement can make the heights and depths of glyphs exceed the range
437 given by `usWinAscent` and `usWinDescent`.
439 If ttfautohint is part of the font creation tool chain, and the font
440 designer can adjust those two values, a better solution instead of using
441 option `-W` is to reserve some vertical space for 'padding': For the
442 auto-hinter, the difference between a top or bottom outline point before
443 and after hinting is less than 1px, thus a vertical padding of 2px is
444 sufficient. Assuming a minimum hinting size of 6ppem, adding two pixels
445 gives an increase factor of 8÷6 = 1.33. This is near to the default
446 baseline-to-baseline distance used by TeX and other sophisticated text
447 processing applications, namely 1.2×designsize, which gives satisfying
448 results in most cases. It is also near to the factor 1.25 recommended
449 in the abovementioned how-to. For example, if the vertical extension of
450 the largest glyph is 2000 units (assuming that it approximately
451 represents the designsize), the sum of `usWinAscent` and `usWinDescent`
452 could be 1.25×2000 = 2500.
454 In case ttfautohint is used as an auto-hinting tool for fonts that can
455 be no longer modified to change the metrics, option `-W` in combination
456 with '`-X "-"`' to suppress any vertical enlargement should prevent
461 `--adjust-subglyphs`, `-p`
462 : *Adjusting subglyphs* makes a font's original bytecode be applied to all
463 glyphs before it is replaced with bytecode created by ttfautohint. This
464 makes only sense if your font already has some hints in it that modify
465 the shape even at EM size (normally 2048px); in particular, some CJK
466 fonts need this because the bytecode is used to scale and shift
467 subglyphs (hence the option's long name). For most fonts, however, this
473 : By default, the components of a composite glyph get hinted separately.
474 If this flag is set, the composite glyph itself gets hinted (and the
475 hints of the components are ignored). Using this flag increases the
476 bytecode size a lot, however, it *might* yield better hinting results –
479 If this option is used (and a font actually contains composite glyphs),
480 ttfautohint currently cannot reprocess its own output for technical
481 reasons, see [below](#the-.ttfautohint-glyph).
486 : Process a font that ttfautohint would refuse otherwise because it can't
487 find a single standard character for any of the supported scripts.
489 For all scripts that lack proper standard characters, ttfautohint uses a
490 default (hinting) value for the standard stem width instead of deriving
491 it from a script's set of standard characters (for the latin script, one
492 of them is character 'o').
494 Use this option – usually in combination with the
495 [`--fallback-script`](#fallback-script) and/or
496 [`--fallback-stem-width`](#fallback-stem-width) option – to hint symbol
497 or dingbat fonts or math glyphs, for example.
502 : Strip off all hints without generating new hints. Consequently, all
503 other hinting options are ignored. This option is intended for testing
509 : Don't add ttfautohint version and command line information to the
510 version string or strings (with name ID\ 5) in the font's `name` table.
511 In the GUI, it corresponds to value 'None' in the 'ttfautohint
514 This option is mutually exclusive with option `-I`.
516 `--detailed-info`, `-I`
517 : Add ttfautohint version and command line information to the version
518 string or strings (with name ID\ 5) in the font's `name` table. In the
519 GUI, it corresponds to value 'Version and Parameters' in the
520 'ttfautohint info' combo box.
522 This option is mutually exclusive with option `-n`.
524 If neither `-n` nor `-I` is set, the string '`ttfautohint (vNNN)`' gets
525 added to the `name` table (with *NNN* the current version); this correponds
526 to value 'Version' in the 'ttfautohint info' combo box.
528 ### Add TTFA Info Table
531 : Add an SFNT table called `TTFA` to the output font that holds a dump of
532 all parameters; the data resembles the format of the `--debug` option's
533 parameter listing. In particular, it lists all ttfautohint control
534 instructions (which are *not* shown in the `name` table info). This
535 option is mainly for archival purposes so that all information used to
536 create a font is stored in the font itself. Note that such a `TTFA`
537 table gets ignored by all TrueType rendering engines.
539 Forthcoming versions of the ttfautohint front-ends will be able to use
540 this data so that a font can be processed another time with exactly the
541 same parameters, thus providing a means for round-tripping fonts.
545 `--family-suffix=`*string*, `-F`\ *string*
546 : A string that gets appended to the family name in entries with IDs 1, 4,
547 6, 16, and\ 21 in the font's `name` table. Allowed input is ASCII in
548 the range 0x20-0x7E except characters `%()/<>[]{}`.
550 Assuming an input family name 'Foo', a full name 'Foo Bold', and a
551 family suffix '\ 1', the output family name will be 'Foo 1' and the
552 full name 'Foo 1 Bold'. For the PostScript name in ID\ 6, ttfautohint
553 uses the suffix with space characters removed (for example 'Foo1Bold').
555 This option is mainly for testing purposes, enabling the operating
556 system to simultaneously display several instances of a font that are
557 processed with different ttfautohint parameters.
559 ### Reference Face Index
561 `--reference-index=`*n*, `-Z`\ *n*
562 : Set the face index for the [blue zone reference
563 font](#blue-zone-reference-font) if the font is a TrueType collection
564 (`.ttc`). For normal TrueType fonts, the value is always zero (which is
567 `ttfautohintGUI` doesn't have this command line option.
569 ### Stem Width and Positioning Mode
571 `--stem-width-mode=`*string*, `-a`\ *string*
572 : ttfautohint provides three different algorithms for computing horizontal
573 stem widths and the positioning of blue zones.
575 - 'natural': No adjustments to stem widths, discrete blue zone
576 positioning. This is what FreeType uses for its 'light'
577 (auto-)hinting mode. Essentially no glyph shape distortion, low
580 - 'quantized': Both stem widths and blue zone positions are slightly
581 quantized to take discrete values. For example, stem values 50, 51,
582 72, 76, and 100 would become 50, 74, and 100 (or something similar).
583 More glyph shape distortion but increased contrast.
585 - 'strong: If active, stem widths and blue zones are snapped and
586 positioned to integer pixel values as much as possible. This gives
587 high contrast, but glyph shape distortion can be significant.
589 These three algorithms are mapped onto three possible rendering targets.
591 - Grayscale rendering, with or without optimization for subpixel
592 positioning (e.g., Android).
594 - 'GDI ClearType' rendering: the rasterizer version, as returned by the
595 GETINFO bytecode instruction, is in the range 36\ <= version <=\ 38
596 and ClearType is enabled (e.g., Windows XP).
598 - 'DirectWrite ClearType' rendering: the rasterizer version, as returned
599 by the GETINFO bytecode instruction, is >=\ 39, ClearType is enabled,
600 and subpixel positioning is enabled also (e.g., Internet Explorer\ 9
601 running on Windows\ 7).
603 GDI ClearType uses a mode similar to B/W rendering along the vertical
604 axis, while DW ClearType applies grayscale rendering. Additionally,
605 only DW ClearType provides subpixel positioning along the x\ axis. For
606 what it's worth, the rasterizers version\ 36 and version\ 38 in
607 Microsoft Windows are two completely different rendering engines.
609 [Note that the GDI framework on Windows\ 10 no longer uses B/W rendering
610 along the vertical axis; we consequently treat it as DW ClearType also.
611 We test this by looking at bit\ 11 of the GETINFO instruction, which
612 was introduced in rasterizer version\ 40.]
614 The command line option expects *string* to contain exactly three
615 letters with possible values '`n`' for natural, '`q`' for quantized, and
616 '`s`' for strong stem width and positioning mode. The first, second,
617 and third letter correspond to grayscale, GDI ClearType, and DW
618 ClearType rendering, respectively. The default value is `qsq`, which
619 means that the 'quantized' algorithm gets used for grayscale and DW
620 ClearType, and the 'strong' algorithm for GDI ClearType. For example,
621 to use the 'natural' algorithm for all three rendering targets, use
624 In the GUI, simply select the desired stem width algorithm in the three
627 ![This image shows different versions of glyph 'g' of the font
628 [Merriweather-Black](https://fonts.google.com/specimen/Merriweather)
629 as displayed with the 'ftgrid' demo program of FreeType. Top left is
630 unhinted, top right is hinted using ttfautohint natural stem width
631 mode. Bottom left and right uses the quantized and strong stem width
632 modes, respectively.](img/Merriweather-Black-g-21px-comparison.png)
634 `--strong-stem-width=`*string*, `-w`\ *string*
636 : This option is deprecated and has been replaced with the more versatile
637 option [`--stem-width-mode`](#stem-width-and-positioning-mode). The
638 table below shows the corresponding arguments.
653 Watch input files\ \ \ (`ttfautohintGUI` only)
654 : If this checkbox is set, automatically regenerate the output file as
655 soon as an input file (either the font, the control instructions file,
656 or the reference font) gets modified.
658 Pressing the 'Run' button starts watching. If an error occurs, watching
659 stops and must be restarted with the 'Run' button.
661 `--ignore-restrictions`, `-i`
662 : By default, fonts that have bit\ 1 set in the 'fsType' field of the
663 `OS/2` table are rejected. If you have a permission of the font's legal
664 owner to modify the font, specify this command line option.
666 If this option is not set, `ttfautohintGUI` shows a dialogue to handle
667 such fonts if necessary.
670 : On the console, print a brief documentation on standard output and exit.
671 This doesn't work with `ttfautohintGUI` on MS Windows.
674 : On the console, print version information on standard output and exit.
675 This doesn't work with `ttfautohintGUI` on MS Windows.
677 `--ttfa-info`, `-T`\ \ \ (not in `ttfautohintGUI`)
678 : Print [`TTFA` table](#add-ttfa-info-table) of the input font on standard
679 output if present, then exit.
681 `--debug`\ \ \ (not in `ttfautohintGUI`)
682 : Print *a lot* of debugging information on standard error while
683 processing a font (you should redirect stderr to a file).
685 To reduce the amount of debug data it is recommended to restrict the
686 hinting process to a single PPEM value, e.g.,
689 ttfautohint --debug -l 15 -r 15 ... > debug.txt 2>&1
694 Background and Technical Details
695 ================================
697 [Real-Time Grid Fitting of Typographic
698 Outlines](https://www.tug.org/TUGboat/tb24-3/lemberg.pdf) is a scholarly
699 paper that describes FreeType's auto-hinter in some detail. Regarding the
700 described data structures it is slightly out of date, but the algorithm
701 itself hasn't changed in general.
703 The next few subsections are mainly based on this article, introducing some
704 important concepts. Note that ttfautohint only does hinting along the
705 vertical direction (modifying y\ coordinates only).
711 A glyph consists of one or more *contours* (this is, closed curves). For
712 example, glyph 'O' consists of two contours, while glyph 'I' has only one.
714 ![The letter 'O' has two contours, an inner and an outer one, while letter
715 'I' has only an outer contour.](img/o-and-i)
717 A *segment* is a series of consecutive points of a contour (including its
718 Bézier control points) that are approximately aligned along a coordinate
719 axis. A segment has one of three possible directions: left, right, or none
720 (which means neither left nor right), derived from the TrueType outline
721 directions. ttfautohint itself creates segments that contain at least two
722 points. Using control instructions, however, it is possible to create
723 one-point segments, which are useful for fine-tuning the hinting process.
725 ![A serif. Contour and control points are represented by squares and
726 circles, respectively. The bottom 'line' DE is approximately aligned
727 along the horizontal axis, thus it forms a segment of 7\ points. Together
728 with the two other horizontal segments, BC and FG, they form two edges
729 (BC+FG, DE).](img/segment-edge)
731 An *edge* corresponds to a single coordinate value (allowing for a small
732 threshold) on the main dimension that collects one or more segments, all
733 pointing into the same direction (either left or right, all others are
734 ignored). While finding segments is done on the unscaled outline, finding
735 edges is bound to the device resolution. See [below](#hint-sets) for an
738 In general, segments and edges pointing into different directions 'repel'
739 each other, thus preventing alignment on the same vertical coordinate if
740 they are near. Note that this is a simplification, but it should help
741 understand how to manipulate and/or create segments in control instructions
744 The analysis to find segments and edges is specific to a writing
745 system, see [below](#writing-systems).
751 The auto-hinter analyzes a font in two steps. Right now, everything
752 described here happens for the horizontal axis only, providing vertical
757 This affects the hinting of all glyphs, trying to give them a uniform
760 + Compute standard horizontal stem width of the font. The value
761 is normally taken from glyphs that resemble letter 'o'.
763 If, for a given script, there is no glyph for at least one standard
764 character in the input font, a fallback stem width gets used. See
765 also option [`--fallback-stem-width`](#fallback-stem-width).
767 The stem width(s) found by the algorithm can be overridden with the
768 [`width`](#stem-width-adjustments) control instruction.
770 + Compute blue zones, see [below](#blue-zones).
772 If the stem widths of single glyphs differ by a large value, or if
773 ttfautohint fails to find proper blue zones, hinting becomes quite poor,
774 possibly leading even to severe shape distortions.
777 Table: script-specific standard characters of the 'latin' writing system
779 Script Standard characters
780 -------- ---------------------
781 `adlm` '𞤌', U+1E90C, ADLAM CAPITAL LETTER O
782 '𞤮', U+1E92E, ADLAM SMALL LETTER O
783 `arab` 'ـ', U+0640, ARABIC TATWEEL
784 'ل', U+0644, ARABIC LETTER LAM
785 'ح', U+062D, ARABIC LETTER HAH
786 `armn` 'օ', U+0585, ARMENIAN SMALL LETTER OH
787 'Օ', U+0555, ARMENIAN CAPITAL LETTER OH
788 `avst` '𐬚', U+10B1A, AVESTAN LETTER THE
789 `bamu` 'ꛁ', U+A6C1, BAMUM LETTER YUQ
790 'ꛯ', U+A6EF, BAMUM LETTER KOGHOM
791 `beng` '০', U+09E6, BENGALI DIGIT ZERO
792 '৪', U+09EA, BENGALI DIGIT FOUR
793 `buhd` 'ᝋ', U+174B, BUHID LETTER MA
794 'ᝏ', U+174F, BUHID LETTER WA
795 `cakm` '𑄤', U+11124, CHAKMA LETTER WAA
796 '𑄉', U+11109, CHAKMA LETTER GAA
797 '𑄛', U+1111B, CHAKMA LETTER PAA
798 `cans` 'ᑌ', U+144C, CANADIAN SYLLABICS TE
799 'ᓚ', U+14DA, CANADIAN SYLLABICS LA
800 `cari` '𐊫', U+102AB, CARIAN LETTER O
801 '𐋉', U+102C9, CARIAN LETTER RR
802 `cher` 'Ꭴ', U+13A4, CHEROKEE LETTER U
803 'Ꮕ', U+13C5, CHEROKEE LETTER NV
804 'ꮕ', U+AB95, CHEROKEE SMALL LETTER NV
805 `copt` 'Ⲟ', U+2C9E, COPTIC CAPITAL LETTER O
806 'ⲟ', U+2C9F, COPTIC SMALL LETTER O
807 `cprt` '𐠅', U+10805, CYPRIOT SYLLABLE JA
808 '𐠣', U+10823, CYPRIOT SYLLABLE RA
809 `cyrl` '\Cyrillic{}о\cyrillic{}', U+043E, CYRILLIC SMALL LETTER O
810 '\Cyrillic{}О\cyrillic{}', U+041E, CYRILLIC CAPITAL LETTER O
811 `deva` 'ठ', U+0920, DEVANAGARI LETTER TTHA
812 'व', U+0935, DEVANAGARI LETTER VA
813 'ट', U+091F, DEVANAGARI LETTER TTA
814 `dsrt` '𐐄', U+10404, DESERET CAPITAL LETTER LONG O
815 '𐐬', U+1042C, DESERET SMALL LETTER LONG O
816 `ethi` 'ዐ', U+12D0, ETHIOPIC SYLLABLE PHARYNGEAL A
817 `geor` 'ი', U+10D8, GEORGIAN LETTER IN
818 'ე', U+10D4, GEORGIAN LETTER EN
819 'ა', U+10D0, GEORGIAN LETTER AN
820 'Ი', U+1C98, GEORGIAN MTAVRULI CAPITAL LETTER IN
821 `geok` 'Ⴖ', U+10B6, GEORGIAN CAPITAL LETTER GHAN
822 'Ⴑ', U+10B1, GEORGIAN CAPITAL LETTER SAN
823 'ⴙ', U+2D19, GEORGIAN SMALL LETTER CHIN
824 `glag` 'Ⱅ', U+2C15, GLAGOLITIC CAPITAL LETTER TVRIDO
825 'ⱅ', U+2C45, GLAGOLITIC SMALL LETTER TVRIDO
826 `goth` '𐌴', U+10334, GOTHIC LETTER AIHVUS
827 '𐌾', U+1033E, GOTHIC LETTER JER
828 '𐍃', U+10343, GOTHIC LETTER SAUIL
829 `grek` '\Greek{}ο\greek{}', U+03BF, GREEK SMALL LETTER OMICRON
830 '\Greek{}Ο\greek{}', U+039F, GREEK CAPITAL LETTER OMICRON
831 `gujr` 'ટ', U+0A9F, GUJARATI LETTER TTA
832 '૦', U+0AE6, GUJARATI DIGIT ZERO
833 `guru` 'ਠ', U+0A20, GURMUKHI LETTER TTHA
834 'ਰ', U+0A30, GURMUKHI LETTER RA
835 '੦', U+0A66, GURMUKHI DIGIT ZERO
836 `hebr` 'ם', U+05DD, HEBREW LETTER FINAL MEM
837 `kali` 'ꤍ', U+A90D, KAYAH LI LETTER NGA
838 '꤀', U+A900, KAYAH LI DIGIT ZERO
839 `knda` '೦', U+0CE6, KANNADA DIGIT ZERO
840 'ಬ', U+0CAC, KANNADA LETTER BA
841 `khmr` '០', U+17E0, KHMER DIGIT ZERO
842 `lao` '໐', U+0ED0, LAO DIGIT ZERO
843 `latn` '\Latin{}o\latin{}', U+006F, LATIN SMALL LETTER O
844 '\Latin{}O\latin{}', U+004F, LATIN CAPITAL LETTER O
845 '\Latin{}0\latin{}', U+0030, DIGIT ZERO
846 `lisu` 'ꓳ', U+A4F3, LISU LETTER
847 `mlym` 'ഠ', U+0D20, MALAYALAM LETTER TTHA
848 'റ', U+0D31, MALAYALAM LETTER RRA
849 `mong` '\Mongolian{}ᡂ\mongolian{}', U+1842, MONGOLIAN LETTER CHI
850 '\Mongolian{}ᠪ\mongolian{}', U+182A, MONGOLIAN LETTER BA
851 `mymr` 'ဝ', U+101D, MYANMAR LETTER WA
852 'င', U+1004, MYANMAR LETTER NGA
853 'ဂ', U+1002, MYANMAR LETTER GA
854 `nkoo` 'ߋ', U+07CB, NKO LETTER EE
855 '߀', U+07C0, NKO DIGIT ZERO
856 `olck` 'ᱛ', U+1C5B, OL CHIKI LETTER AT
857 `orkh` '𐰗', U+10C17, OLD TURKIC LETTER YENISEI AY
858 `osge` '𐓂', U+104C2, OSAGE CAPITAL LETTER O
859 '𐓪', U+104EA, OSAGE SMALL LETTER O
860 `osma` '𐒆', U+10486, OSMANYA LETTER DEEL
861 '𐒠', U+104A0, OSMANYA DIGIT ZERO
862 `saur` 'ꢝ', U+A89D, SAURASHTRA LETTER TTHA
863 '꣐', U+A8D0, SAURASHTRA DIGIT ZERO
864 `shaw` '𐑴', U+10474, SHAVIAN LETTER OAK
865 `sinh` 'ට', U+0DA7, SINHALA LETTER ALPAPRAANA TTAYANNA
866 `sund` '᮰', U+1BB0, SUNDANESE DIGIT ZERO
867 `taml` '௦', U+0BE6, TAMIL DIGIT ZERO
868 `tavt` 'ꪒ', U+AA92, TAI VIET LETTER LOW DO
869 'ꪫ', U+AAAB, TAI VIET LETTER HIGH VO
870 `telu` '౦', U+0C66, TELUGU DIGIT ZERO
871 '౧', U+0C67, TELUGU DIGIT ONE
872 `tfng` 'ⵔ', U+2D54, TIFINAGH LETTER YAR
873 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
874 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
875 '๐', U+0E50, THAI DIGIT ZERO
876 `vaii` 'ꘓ', U+A613, VAI SYMBOL FEENG
877 'ꖜ', U+A59C, VAI SYLLABLE BHU
878 'ꖴ', U+A5B4, VAI SYLLABLE KU
881 Table: standard characters of the 'latin' writing system, special scripts
883 Script Standard characters
884 ---------- ---------------------
885 `khms` '᧡', U+19E1, KHMER SYMBOL MUOY KOET
886 '᧪', U+19EA, KHMER SYMBOL DAP KOET
887 `latb` '\Latin{}ₒ\latin{}', U+2092, LATIN SUBSCRIPT SMALL LETTER O
888 '\Latin{}₀\latin{}', U+2080, SUBSCRIPT ZERO
889 `latp` '\Latin{}ᵒ\latin{}', U+1D52, MODIFIER LETTER SMALL O
890 '\Latin{}ᴼ\latin{}', U+1D3C, MODIFIER LETTER CAPITAL O
891 '\Latin{}⁰\latin{}', U+2070, SUPERSCRIPT ZERO
896 This is a per-glyph operation.
898 + Find segments and edges.
900 + Link edges to set up stems and serifs. The abovementioned paper
901 gives more details on what exactly constitutes a stem or a serif and
902 how the algorithm works.
908 ![Two blue zones relevant to the glyph 'a'. Vertical point coordinates of
909 *all* glyphs within these zones are aligned, provided the blue zone is
910 active (this is, its vertical size is smaller than
911 3/4\ pixels).](img/blue-zones)
913 Outlines of certain characters are used to determine *blue zones*. This
914 concept is the same as with Type\ 1 fonts: All glyph points that lie in
915 certain small horizontal zones get aligned vertically.
917 The tables below show the blue zone characters of all available scripts of
918 the latin writing system; the values are hard-coded in the source code.
919 Since the auto-hinter takes mean values it is not necessary that all
920 characters of a zone are present.
922 'Round' characters in blue zones (e.g., the top and bottom of 'O' or the
923 bottom of 'g') are used to control overshoot handling.
925 Blue zones marked with an asterisk are x\ height blue zones, which are
926 adjusted to be on the pixel grid (to improve rendering at small sizes) by
927 scaling the remaining blue zones before they are adjusted to the grid. See
928 also option [`--increase-x-height`](#x-height-increase-limit).
931 Table: `adlm` (Adlam) blue zones
933 ID Blue zone Characters
934 ---- ----------- ------------
935 1 top of capital letters 𞤌 𞤅 𞤈 𞤏 𞤔 𞤚
936 2 bottom of capital letters 𞤂 𞤖
937 3* top of small letters 𞤬 𞤮 𞤻 𞤼 𞤾
938 4 bottom of small letters 𞤤 𞤨 𞤩 𞤭 𞤴 𞤸 𞤺 𞥀
941 Table: `arab` (Arabic) blue zones
943 ID Blue zone Characters
944 ---- ----------- ------------
945 1 top of letters with vertical stroke ا إ ل ك ط ظ
946 2 bottom of letters ت ث ط ظ ك
950 Table: `armn` (Armenian) blue zones
952 ID Blue zone Characters
953 ---- ----------- ------------
954 1 top of capital letters Ա Մ Ւ Փ Բ Գ Դ Օ
955 2 bottom of capital letters Ւ Ո Փ Ճ Շ Ս Տ Օ
956 3 top of ascenders of small letters ե է ի մ վ փ ֆ փ
957 4* top of small letters ա յ ւ ս գ ջ ր օ
958 5 bottom of small letters հ ո ճ ա ե ծ ս օ
959 6 bottom of descenders of small letters բ ը ի լ ղ պ փ ց
962 Table: `avst` (Avestan) blue zones
964 ID Blue zone Characters
965 ---- ----------- ------------
966 1 top of letters 𐬀 𐬁 𐬐 𐬛
967 2 bottom of letters 𐬀 𐬁
970 Table: `bamu` (Bamum) blue zones
972 ID Blue zone Characters
973 ---- ----------- ------------
974 1 top of letters ꚧ ꚨ ꛛ ꛉ ꛁ ꛈ ꛫ ꛯ
975 2 bottom of letters ꚭ ꚳ ꚶ ꛬ ꚢ ꚽ ꛯ ꛲
978 Table: `beng` (Bengali) blue zones
980 ID Blue zone Characters
981 ---- ----------- ------------
982 1 baseline (flat glyphs only) অ ড ত ন ব ভ ল ক
983 2 top of ascenders ই ট ঠ ি ী ৈ ৗ
984 3* top of baseline ও এ ড ত ন ব ল ক
985 4 bottom of base characters অ ড ত ন ব ভ ল ক
987 Contrary to scripts like latin, the baseline in Bengali is on the top, and
988 we hint from top to bottom.
991 Table: `buhd` (Buhid) blue zones
993 ID Blue zone Characters
994 ---- ----------- ------------
996 2 top of large letters ᝅ ᝊ ᝎ
997 3* top of small letters ᝂ ᝃ ᝉ ᝌ
998 4 bottom of letters ᝀ ᝃ ᝆ ᝉ ᝋ ᝏ ᝑ
1001 Table: `cakm` (Chakma) blue zones
1003 ID Blue zone Characters
1004 ---- ----------- ------------
1005 1 top of letters 𑄃 𑄅 𑄉 𑄙 𑄗
1006 2 bottom of letters 𑄅 𑄛 𑄝 𑄗 𑄓
1007 3 bottom of descenders of letters 𑄖𑄳𑄢 𑄘𑄳𑄢 𑄙𑄳𑄢 𑄤𑄳𑄢 𑄥𑄳𑄢
1010 Table: `cans` (Canadian Syllabics) blue zones
1012 ID Blue zone Characters
1013 ---- ----------- ------------
1014 1 top of letters ᗜ ᖴ ᐁ ᒣ ᑫ ᑎ ᔑ ᗰ
1015 2 bottom of letters ᗶ ᖵ ᒧ ᐃ ᑌ ᒍ ᔑ ᗢ
1016 3* top of small letters ᓓ ᓕ ᓀ ᓂ ᓄ ᕄ ᕆ ᘣ
1017 4 bottom of small letters ᕃ ᓂ ᓀ ᕂ ᓗ ᓚ ᕆ ᘣ
1018 5 top of superscript letters ᐪ ᙆ ᣘ ᐢ ᒾ ᣗ ᔆ
1019 6 bottom of superscript letters ᙆ ᗮ ᒻ ᐞ ᔆ ᒡ ᒢ ᓑ
1022 Table: `cari` (Carian) blue zones
1024 ID Blue zone Characters
1025 ---- ----------- ------------
1026 1 top of letters 𐊧 𐊫 𐊬 𐊭 𐊱 𐊺 𐊼 𐊿
1027 2 bottom of letters 𐊣 𐊧 𐊷 𐋀 𐊫 𐊸 𐋉
1030 Table: `cher` (Cherokee) blue zones
1032 ID Blue zone Characters
1033 ---- ----------- ------------
1034 1 top of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1035 2 bottom of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1036 3 top of ascenders of small letters ꮒ ꮤ ꮶ ꭴ ꭾ ꮗ ꮝ ꮿ
1037 4* top of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1038 5 bottom of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1039 6 bottom of descenders of small letters ᏸ ꮐ ꭹ ꭻ
1042 Table: `copt` (Coptic) blue zones
1044 ID Blue zone Characters
1045 ---- ----------- ------------
1046 1 top of capital letters Ⲍ Ⲏ Ⲡ Ⳟ Ⲟ Ⲑ Ⲥ Ⳋ
1047 2 bottom of capital letters Ⳑ Ⳙ Ⳟ Ⲏ Ⲟ Ⲑ Ⳝ Ⲱ
1048 3* top of small letters ⲍ ⲏ ⲡ ⳟ ⲟ ⲑ ⲥ ⳋ
1049 4 bottom of small letters ⳑ ⳙ ⳟ ⲏ ⲟ ⲑ ⳝ Ⳓ
1052 Table: `cprt` (Cypriot) blue zones
1054 ID Blue zone Characters
1055 ---- ----------- ------------
1056 1 top of letters 𐠍 𐠙 𐠳 𐠱 𐠅 𐠓 𐠣 𐠦
1057 2 bottom of letters 𐠃 𐠊 𐠛 𐠣 𐠳 𐠵 𐠐
1058 3 top of small letters 𐠈 𐠏 𐠖
1059 4 bottom of small letters 𐠈 𐠏 𐠖
1062 Table: `cyrl` (Cyrillic) blue zones
1064 ID Blue zone Characters
1065 ---- ----------- ------------
1066 1 top of capital letters \Cyrillic{}Б В Е П З О С Э\cyrillic{}
1067 2 bottom of capital letters \Cyrillic{}Б В Е Ш З О С Э\cyrillic{}
1068 3* top of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1069 4 bottom of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1070 5 bottom of descenders of small letters \Cyrillic{}р у ф\cyrillic{}
1073 Table: `deva` (Devanagari) blue zones
1075 ID Blue zone Characters
1076 ---- ----------- ------------
1077 1 top of ascenders ई ऐ ओ औ ि ी ो ौ
1078 2 top of baseline क म अ आ थ ध भ श
1079 3* top of baseline (flat glyphs only) क न म उ छ ट ठ ड
1080 4 bottom of base characters क न म उ छ ट ठ ड
1081 5 bottom of descenders ु ृ
1083 Contrary to scripts like latin, the baseline in Devanagari is on the top,
1084 and we hint from top to bottom. Note that some fonts have extreme variation
1085 in the height of the round elements in Zone\ 3; for this reason we also
1086 define Zone\ 1, which must be always present.
1089 Table: `dsrt` (Deseret) blue zones
1091 ID Blue zone Characters
1092 ---- ----------- ------------
1093 1 top of capital letters 𐐂 𐐄 𐐋 𐐗 𐐑
1094 2 bottom of capital letters 𐐀 𐐂 𐐄 𐐗 𐐛
1095 3* top of small letters 𐐪 𐐬 𐐳 𐐿 𐐹
1096 4 bottom of small letters 𐐨 𐐪 𐐬 𐐿 𐑃
1099 Table: `ethi` (Ethiopian) blue zones
1101 ID Blue zone Characters
1102 ---- ----------- ------------
1103 1 top of letters ሀ ሃ ዘ ፐ ማ በ ዋ ዐ
1104 2 bottom of letters ለ ሐ በ ዘ ሀ ሪ ዐ ጨ
1107 Table: `geok` (Georgian Khutsuri) blue zones
1109 ID Blue zone Characters
1110 ---- ----------- ------------
1111 1 top of Asomtavruli letters Ⴑ Ⴇ Ⴙ Ⴜ Ⴄ Ⴅ Ⴓ Ⴚ
1112 2 bottom of Asomtavruli letters Ⴄ Ⴅ Ⴇ Ⴈ Ⴆ Ⴑ Ⴊ Ⴋ
1113 3* top of Nuskhuri letters ⴁ ⴗ ⴂ ⴄ ⴅ ⴇ ⴔ ⴖ
1114 4 bottom of Nuskhuri letters ⴈ ⴌ ⴖ ⴎ ⴃ ⴆ ⴋ ⴢ
1115 5 top of ascender Nuskhuri letters ⴐ ⴑ ⴓ ⴕ ⴙ ⴛ ⴡ ⴣ
1116 6 bottom of Nuskhuri descender letters ⴄ ⴅ ⴔ ⴕ ⴁ ⴂ ⴘ ⴝ
1118 Georgian Asomtavruli and Nuskhuri form the old ecclesiastical script,
1119 Khutsuri. Note that fonts show a great variation in height and depth of
1120 ascender and descender letter forms.
1123 Table: `geor` (Georgian Mkhedruli) blue zones
1125 ID Blue zone Characters
1126 ---- ----------- ------------
1127 1* top of Mkhedruli letters გ დ ე ვ თ ი ო ღ
1128 2 bottom of Mkhedruli letters ა ზ მ ს შ ძ ხ ჰ
1129 3 top of ascender Mkhedruli letters ს ხ ქ ზ მ შ ჩ წ
1130 4 bottom of descender Mkhedruli letters ე ვ ჟ ტ უ ფ ქ ყ
1131 5 top of ascender Mtavruli letters Ნ Ჟ Ჳ Ჸ Გ Ე Ო Ჴ
1132 6 bottom of descender Mtavruli letters Ი Ჲ Ო Ჩ Მ Შ Ჯ Ჽ
1135 Table: `glag` (Glagolitic) blue zones
1137 ID Blue zone Characters
1138 ---- ----------- ------------
1139 1 top of capital letters Ⰵ Ⱄ Ⱚ Ⰴ Ⰲ Ⰺ Ⱛ Ⰻ
1140 2 bottom of capital letters Ⰵ Ⰴ Ⰲ Ⱚ Ⱎ Ⱑ Ⰺ Ⱄ
1141 3* top of small letters ⰵ ⱄ ⱚ ⰴ ⰲ ⰺ ⱛ ⰻ
1142 4 bottom of small letters ⰵ ⰴ ⰲ ⱚ ⱎ ⱑ ⰺ ⱄ
1145 Table: `goth` (Gothic) blue zones
1147 ID Blue zone Characters
1148 ---- ----------- ------------
1149 1 top of letters 𐌲 𐌶 𐍀 𐍄 𐌴 𐍃 𐍈 𐌾
1150 2 bottom of letters 𐌶 𐌴 𐍃 𐍈
1153 Table: `grek` (Greek) blue zones
1155 ID Blue zone Characters
1156 ---- ----------- ------------
1157 1 top of capital letters \Greek{}Γ Β Ε Ζ Θ Ο Ω\greek{}
1158 2 bottom of capital letters \Greek{}Β Δ Ζ Ξ Θ Ο\greek{}
1159 3 top of 'small beta' like letters \Greek{}β θ δ ζ λ ξ\greek{}
1160 4* top of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1161 5 bottom of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1162 6 bottom of descenders of small letters \Greek{}β γ η μ ρ φ χ ψ\greek{}
1165 Table: `gujr` (Gujarati) blue zones
1167 ID Blue zone Characters
1168 ---- ----------- ------------
1169 1* top of letters ત ન ઋ ઌ છ ટ ર ૦
1170 2 bottom of letters ખ ગ ઘ ઞ ઇ ઈ ઠ જ
1171 3 top of ascenders ઈ ઊ િ ી લી શ્ચિ જિ સી
1172 4 bottom of descenders ુ ૃ ૄ ખુ છૃ છૄ
1173 5 top of Gujarati digits ૦ ૧ ૨ ૩ ૭
1176 Table: `guru` (Gurmukhi) blue zones
1178 ID Blue zone Characters
1179 ---- ----------- ------------
1180 1 top of ascenders ਇ ਈ ਉ ਏ ਓ ੳ ਿ ੀ
1181 2 top of baseline ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1182 3* top of baseline (flat glyphs only) ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1183 4 bottom of characters ਅ ਏ ਓ ਗ ਜ ਠ ਰ ਸ
1184 5 top of Gurmukhi digits ੦ ੧ ੨ ੩ ੭
1187 Table: `hebr` (Hebrew) blue zones
1189 ID Blue zone Characters
1190 ---- ----------- ------------
1191 1 top of letters ב ד ה ח ך כ ם ס
1192 2 bottom of letters ב ט כ ם ס צ
1193 3 bottom of descenders of letters ק ך ן ף ץ
1196 Table: `kali` (Kayah Li) blue zones
1198 ID Blue zone Characters
1199 ---- ----------- ------------
1200 1* top of letters ꤅ ꤏ ꤁ ꤋ ꤀ ꤍ
1201 2 bottom of letters ꤈ ꤘ ꤀ ꤍ ꤢ
1202 3 top of ascending letters ꤖ ꤡ
1203 4 bottom of descending letters ꤑ ꤜ ꤞ
1204 5 bottom of large descending letters ꤑ꤬ ꤜ꤭ ꤔ꤬
1207 Table: `khmr` (Khmer) blue zones
1209 ID Blue zone Characters
1210 ---- ----------- ------------
1211 1* top of letters ខ ទ ន ឧ ឩ ា
1212 2 top of subscript cluster components ក្ក ក្ខ ក្គ ក្ថ
1213 3 bottom of letters ខ ឃ ច ឋ ប ម យ ឲ
1214 4 bottom of descenders ត្រ រៀ ឲ្យ អឿ
1215 5 bottom of large descenders ន្ត្រៃ ង្ខ្យ ក្បៀ ច្រៀ ន្តឿ ល្បឿ
1218 Table: `khms` (Khmer Symbols) blue zones
1220 ID Blue zone Characters
1221 ---- ----------- ------------
1222 1* top of symbols for waxing ᧠ ᧡
1223 2 bottom of symbols for waning ᧶ ᧹
1225 Khmer symbols are used for lunar dates.
1228 Table: `knda` (Kannada) blue zones
1230 ID Blue zone Characters
1231 ---- ----------- ------------
1232 1 top of letters ಇ ಊ ಐ ಣ ಸಾ ನಾ ದಾ ರಾ
1233 2 bottom of letters ಅ ಉ ಎ ಲ ೦ ೨ ೬ ೭
1236 Table: `lao` (Lao) blue zones
1238 ID Blue zone Characters
1239 ---- ----------- ------------
1240 1* top of letters າ ດ ອ ມ ລ ວ ຣ ງ
1241 2 bottom of letters າ ອ ບ ຍ ຣ ຮ ວ ຢ
1242 3 top of ascenders ປ ຢ ຟ ຝ
1243 4 top of large ascenders ໂ ໄ ໃ
1244 5 bottom of descenders ງ ຊ ຖ ຽ ໆ ຯ
1247 Table: `latb` (Latin Subscripts) 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 Subscript latin characters are similar to normal latin characters.
1261 Table: `latn` (Latin) blue zones
1263 ID Blue zone Characters
1264 ---- ----------- ------------
1265 1 top of capital letters \Latin{}T H E Z O C Q S\latin{}
1266 2 bottom of capital letters \Latin{}H E Z L O C U S\latin{}
1267 3 top of 'small f' like letters \Latin{}f i j k d b h\latin{}
1268 4* top of small letters \Latin{}u v x z o e s c\latin{}
1269 5 bottom of small letters \Latin{}n r x z o e s c\latin{}
1270 6 bottom of descenders of small letters \Latin{}p q g j y\latin{}
1273 Table: `latp` (Latin Superscripts) blue zones
1275 ID Blue zone Characters
1276 ---- ----------- ------------
1277 1 top of capital characters \Latin{}⁰ ³ ⁵ ⁷ ᵀ ᴴ ᴱ ᴼ\latin{}
1278 2 bottom of capital characters \Latin{}⁰ ¹ ² ³ ᴱ ᴸ ᴼ ᵁ\latin{}
1279 3 top of 'small f' like characters \Latin{}ᵇ ᵈ ᵏ ʰ ʲ ᶠ ⁱ\latin{}
1280 4* top of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1281 5 bottom of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1282 6 bottom of descenders of small characters \Latin{}ᵖ ʸ ᵍ\latin{}
1284 Superscript latin characters are similar to normal latin characters.
1287 Table: `lisu` (Lisu) blue zones
1289 ID Blue zone Characters
1290 ---- ----------- ------------
1291 1 top of letters ꓡ ꓧ ꓱ ꓶ ꓩ ꓚ ꓵ ꓳ
1292 2 bottom of letters ꓕ ꓜ ꓞ ꓡ ꓛ ꓢ ꓳ ꓴ
1295 Table: `mlym` (Malayalam) blue zones
1297 ID Blue zone Characters
1298 ---- ----------- ------------
1299 1 top of letters ഒ ട ഠ റ ച പ ച്ച പ്പ
1300 2 bottom of letters ട ഠ ധ ശ ഘ ച ഥ ല
1303 Table: `mong` (Mongolian) blue zones
1305 ID Blue zone Characters
1306 ---- ----------- ------------
1307 1 top of base stem \Mongolian{}ᠳ ᠴ ᠶ ᠽ ᡂ ᡊ ᡡ ᡳ\mongolian{}
1308 2 bottom of base stem \Mongolian{}ᡃ\mongolian{}
1311 Table: `mymr` (Myanmar) blue zones
1313 ID Blue zone Characters
1314 ---- ----------- ------------
1315 1* top of letters ခ ဂ င ဒ ဝ ၥ ၊ ။
1316 2 bottom of letters င ဎ ဒ ပ ဗ ဝ ၊ ။
1317 3 top of ascenders of characters ဩ ြ ၍ ၏ ၆ ါ ိ
1318 3 bottom of descenders of letters ဉ ည ဥ ဩ ဨ ၂ ၅ ၉
1321 Table: `nkoo` (N'Ko) blue zones
1323 ID Blue zone Characters
1324 ---- ----------- ------------
1325 1 top of letters ߐ ߉ ߒ ߟ ߖ ߜ ߠ ߥ
1326 2 bottom of letters ߀ ߘ ߡ ߠ ߥ
1327 3* top of small letters ߏ ߛ ߋ
1328 4 bottom of small letters ߎ ߏ ߛ ߋ
1331 Table: `olck` (Ol Chiki) blue zones
1333 ID Blue zone Characters
1334 ---- ----------- ------------
1335 1 top of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1336 2 bottom of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1339 Table: `orkh` (Old Turkic) blue zones
1341 ID Blue zone Characters
1342 ---- ----------- ------------
1343 1 top of letters 𐰗 𐰘 𐰧
1344 2 bottom of letters 𐰉 𐰗 𐰦 𐰧
1347 Table: `osge` (Osage) blue zones
1349 ID Blue zone Characters
1350 ---- ----------- ------------
1351 1 top of capital letters 𐒾 𐓍 𐓒 𐓓 𐒻 𐓂 𐒵 𐓆
1352 2 bottom of capital letters 𐒰 𐓍 𐓂 𐒿 𐓎 𐒹
1353 3 bottom of descenders of capital letters 𐒼 𐒽 𐒾
1354 4* top of small letters 𐓵 𐓶 𐓺 𐓻 𐓝 𐓣 𐓪 𐓮
1355 5 bottom of small letters 𐓘 𐓚 𐓣 𐓵 𐓡 𐓧 𐓪 𐓶
1356 6 top of ascenders of small letters 𐓤 𐓦 𐓸 𐓹 𐓛
1357 7 bottom of descenders of small letters 𐓤 𐓥 𐓦
1360 Table: `osma` (Osmanya) blue zones
1362 ID Blue zone Characters
1363 ---- ----------- ------------
1364 1 top of letters 𐒆 𐒉 𐒐 𐒒 𐒘 𐒛 𐒠 𐒣
1365 2 bottom of letters 𐒀 𐒂 𐒆 𐒈 𐒊 𐒒 𐒠 𐒩
1368 Table: `saur` (Saurashtra) blue zones
1370 ID Blue zone Characters
1371 ---- ----------- ------------
1372 1 top of letters ꢜ ꢞ ꢳ ꢂ ꢖ ꢒ ꢝ ꢛ
1373 2 bottom of letters ꢂ ꢨ ꢺ ꢤ ꢎ
1376 Table: `shaw` (Shavian) blue zones
1378 ID Blue zone Characters
1379 ---- ----------- ------------
1380 1 top of letters 𐑕 𐑙
1381 2 bottom of letters 𐑔 𐑖 𐑗 𐑹 𐑻
1382 3 bottom of descenders of letters 𐑟 𐑣
1383 4* top of small letters 𐑱 𐑲 𐑳 𐑴 𐑸 𐑺 𐑼
1384 5 bottom of small letters 𐑴 𐑻 𐑹
1387 Table: `sinh` (Sinhala) blue zones
1389 ID Blue zone Characters
1390 ---- ----------- ------------
1391 1 top of letters ඉ ක ඝ ඳ ප ය ල ෆ
1392 2 bottom of letters එ ඔ ඝ ජ ට ථ ධ ර
1393 3 bottom of descenders of letters ද ඳ උ ල තූ තු බු දු
1396 Table: `sund` (Sundanese) blue zones
1398 ID Blue zone Characters
1399 ---- ----------- ------------
1400 1 top of letters ᮋ ᮞ ᮮ ᮽ ᮰ ᮈ
1401 2 bottom of letters ᮄ ᮔ ᮕ ᮗ ᮰ ᮆ ᮈ ᮉ
1402 3 bottom of descenders of letters ᮼ ᳄
1405 Table: `taml` (Tamil) blue zones
1407 ID Blue zone Characters
1408 ---- ----------- ------------
1409 1 top of letters உ ஒ ஓ ற ஈ க ங ச
1410 2 bottom of letters க ச ல ஶ உ ங ட ப
1413 Table: `tavt` (Tai Viet) blue zones
1415 ID Blue zone Characters
1416 ---- ----------- ------------
1417 1 top of letters ꪆ ꪔ ꪒ ꪖ ꪫ
1418 2 bottom of letters ꪉ ꪫ ꪮ
1421 Table: `telu` (Telugu) blue zones
1423 ID Blue zone Characters
1424 ---- ----------- ------------
1425 1 top of letters ఇ ఌ ఙ ఞ ణ ఱ ౯
1426 2 bottom of letters అ క చ ర ఽ ౨ ౬
1429 Table: `tfng` (Tifinagh) blue zones
1431 ID Blue zone Characters
1432 ---- ----------- ------------
1433 1 top of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1434 2 bottom of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1437 Table: `thai` (Thai) blue zones
1439 ID Blue zone Characters
1440 ---- ----------- ------------
1441 1* top of letters บ เ แ อ ก า
1442 2 bottom of letters บ ป ษ ฯ อ ย ฮ
1443 3 top of ascenders of letters ป ฝ ฟ
1444 4 top of large ascenders of letters โ ใ ไ
1445 5 bottom of descenders of letters ฎ ฏ ฤ ฦ
1446 6 bottom of large descenders of letters ญ ฐ
1447 7 top of Thai digits ๐ ๑ ๓
1450 Table: `vaii` (Vai) blue zones
1452 ID Blue zone Characters
1453 ---- ----------- ------------
1454 1 top of vai letters ꗍ ꘖ ꘙ ꘜ ꖜ ꖝ ꔅ ꕢ
1455 2 bottom of vai letters ꗍ ꘖ ꘙ ꗞ ꔅ ꕢ ꖜ ꔆ
1458 ![This image shows the relevant glyph terms for vertical blue zone
1459 positions.](img/glyph-terms)
1465 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
1466 necessarily mean that the outlines are positioned *exactly* on the grid,
1467 however, especially if you want a smooth appearance at different sizes.
1468 This is the central routine of the auto-hinter; its actions are highly
1469 dependent on the used writing system. Currently, only one writing system is
1470 available (latin), providing support for scripts like Latin or Greek.
1472 * Align edges linked to blue zones.
1474 * Fit edges to the pixel grid.
1476 * Align serif edges.
1478 * Handle remaining 'strong' points. Such points are not part of an edge
1479 but are still important for defining the shape. This roughly
1480 corresponds to the `IP` TrueType instruction.
1482 * Everything else (the 'weak' points) is handled with an 'IUP'
1485 The following images illustrate the hinting process, using glyph 'a' from
1486 the freely available font '[Ubuntu Book](https://design.ubuntu.com/font/)'. The
1487 manual hints were added by [Dalton Maag Ltd], the used application to create
1488 the hinting debug snapshots was [FontForge].
1490 ![Before hinting.](img/a-before-hinting.png)
1492 ![After hinting, using manual hints.](img/a-after-hinting.png)
1494 ![After hinting, using ttfautohint. Note that the hinting process
1495 doesn't change horizontal positions.](img/a-after-autohinting.png)
1501 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
1502 a given PPEM (pixel per EM) value.
1504 In the range given by the `--hinting-range-min` and `--hinting-range-max`
1505 options, ttfautohint creates hint sets for every PPEM value. For each
1506 glyph, ttfautohint automatically determines whether a new set should be
1507 emitted for a PPEM value if it finds that it differs from a previous one.
1508 For some glyphs it is possible that one set covers, say, the range
1509 8px-1000px, while other glyphs need 10 or more such sets.
1511 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1512 one set, in the PPEM range between `--hinting-range-max` and
1513 `--hinting-limit`, it also uses just one set.
1515 One of the hinting configuration parameters is the decision which segments
1516 form an edge. For example, let us assume that two segments get aligned on a
1517 single horizontal edge at 11px, while two edges are used at 12px. This
1518 change makes ttfautohint emit a new hint set to accomodate this situation.
1519 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1520 from the 'Ubuntu book' font, processed with ttfautohint.
1522 ![Before hinting, size 11px.](img/afii10108-11px-before-hinting.png)
1524 ![After hinting, size 11px. Segments 43-27-28 and 14-15 are aligned on a
1525 single edge, as are segments 26-0-1 and
1526 20-21.](img/afii10108-11px-after-hinting.png)
1528 ![Before hinting, size 12px.](img/afii10108-12px-before-hinting.png)
1530 ![After hinting, size 12px. The segments are not aligned. While
1531 segments 43-27-28 and 20-21 now have almost the same horizontal position,
1532 they don't form an edge because the outlines passing through the segments
1533 point into different directions.](img/afii10108-12px-after-hinting.png)
1535 Obviously, the more hint sets get emitted, the larger the bytecode
1536 ttfautohint adds to the output font. To find a good value\ *n* for
1537 `--hinting-range-max`, some experimentation is necessary since *n* depends
1538 on the glyph shapes in the input font. If the value is too low, the hint
1539 set created for the PPEM value\ *n* (this hint set gets used for all larger
1540 PPEM values) might distort the outlines too much in the PPEM range given
1541 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1542 switched off). If the value is too high, the font size increases due to
1543 more hint sets without any noticeable hinting effects.
1545 Similar arguments hold for `--hinting-range-min` except that there is no
1546 lower limit at which hinting is switched off.
1548 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1549 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1550 out that four hint sets must be computed to exactly cover this hinting
1551 range: 10-15, 16-40, 41-80, and 81-100. For PPEM values below 10ppem, the
1552 hint set covering 10-15ppem is used, for PPEM values larger than 100 the
1553 hint set covering 81-100ppem is used. For PPEM values larger than 250, no
1554 hinting gets applied.
1560 The ttfautohint library (and programs) supports two solutions for handling
1561 composite glyphs, to be controlled with option
1562 [`--composites`](#hint-composites). This section contains some general
1563 information, then covers the case where the option is off, while the next
1564 section describes how ttfautohint behaves if this option is activated.
1566 Regardless of the `--composites` option, ttfautohint performs a scan over
1567 all composite glyphs to assure that components of a composite glyph inherit
1568 its style, as described [later](#opentype-features). However, components
1569 that are shifted vertically will be skipped. For example, if the glyph
1570 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1571 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1572 vertically unshifted, 'grave' does inherit the style.
1574 If `--composites` is off, components are hinted separately, then put
1575 together. Separate hinting implies that the current style's blue zones are
1576 applied to all subglyphs in its original, unshifted positions. In case you
1577 want to shift components vertically, it is *mandatory* to set bit\ 2
1578 (value\ 4), `ROUND_XY_TO_GRID`, in the flag variable of the composite glyph
1579 description to get visually pleasing results, as the images below
1582 ![Here, the subscript glyphs are composites each having a single element
1583 that is shifted down. If option `--composites` is not used, subglyphs are
1584 hinted before they are glued together (possibly applying scaling and
1585 shifting). Because the `ROUND_XY_TO_GRID` flag isn't set, the vertical
1586 translation doesn't align the subglyph to the pixel grid, causing severe
1587 distortions.](img/composite-no-round-xy-to-grid.png)
1589 ![The same as before, but with `ROUND_XY_TO_GRID` set. Now the subscript
1590 glyphs look identical to the
1591 superscripts.](img/composite-round-xy-to-grid.png)
1593 ![For comparison purposes, here the result *with* option `--composites` (and
1594 no `ROUND_XY_TO_GRID`). The composite glyphs as a whole get hinted;
1595 consequently, the subscript glyphs get separate blue zones. At the
1596 displayed size of 16ppem the vertical positions of the subscript blue
1597 zones are rounded differently if compared to the superscript zones, thus
1598 the smaller glyph height.](img/composite-no-round-xy-to-grid-option-c.png)
1601 The '\.ttfautohint' Glyph
1602 -------------------------
1604 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1605 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1606 glyph, this is, composites get recursively expanded internally so that they
1607 form simple glyphs, then hints are applied -- this is the normal working
1608 mode of FreeType's auto-hinter.
1610 One problem, however, must be solved: Hinting for subglyphs (which usually
1611 are used as normal glyphs also) must be deactivated so that nothing but the
1612 final bytecode of the composite gets executed.
1614 The trick used by ttfautohint is to prepend a composite element called
1615 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1616 job: Its bytecode increases a variable (to be more precise, it is a CVT
1617 register called `cvtl_is_subglyph` in the source code), indicating that we
1618 are within a composite glyph. The final bytecode of the composite glyph
1619 eventually decrements this variable again.
1621 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1622 subglyph 'A' as the base and 'grave' as its accent. After processing with
1623 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1624 'grave' (in this order).
1627 ------------- --------
1628 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1629 A do nothing because `cvtl_is_subglyph` > 0
1630 grave do nothing because `cvtl_is_subglyph` > 0
1631 Agrave decrease `cvtl_is_subglyph` (now: 0)
1632 apply hints because `cvtl_is_subglyph` == 0
1634 Some technical details (which you might skip): All glyph point indices get
1635 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1636 one. This must be done for both the bytecode and one subformat of
1637 OpenType's `GPOS` anchor tables.
1639 While this approach works fine on all tested platforms, there is one single
1640 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1641 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1642 the font! Under normal circumstances this never happens because
1643 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1644 some test and demo programs like FreeType's `ftview` application or other
1645 glyph viewers that are able to bypass the `cmap` table might be affected.)
1651 In FreeType terminology, a writing system is a set of functions that
1652 provides auto-hinting for certain scripts. Right now, only two writing
1653 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1654 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1655 follow in the next section.
1661 ttfautohint needs to know which script should be used to hint a specific
1662 glyph. To do so, it checks a glyph's Unicode character code whether it
1663 belongs to a given script.
1665 See '[Character Ranges](#character-ranges)' for a complete list of all
1666 handled scripts and its ranges. This list is auto-generated from a source
1667 code file, covering the 'latin' writing system. It also covers some
1668 non-latin scripts (in the Unicode sense) that have similar typographical
1671 In ttfautohint, scripts are identified by four-character tags (if there are
1672 less characters, spaces are appended). The value `none` indicates 'no
1675 Each script is represented by two tables to handle 'base' and 'non-base'
1676 characters. For ttfautohint, a non-base character is something that should
1677 not be affected by blue zones, regardless of whether this is a spacing or
1678 no-spacing glyph. In other words, non-base characters are hinted using a
1679 script's default stem width without applying blue zones.
1681 Right now, there are two pseudo-scripts that are used as fallbacks: `latb`
1682 and `latp`, used for latin subscript and superscript characters,
1683 respectively. Its main usage is support of phonetic alphabets like the IPA,
1684 which intermix those characters with normal characters sitting on the
1685 baseline, and which are not specially handled in corresponding OpenType
1686 features like `sups`.
1688 If a glyph's character code is not covered by a script range, it is handled
1689 by a *fallback script*. By default, the fallback script is `none`, which
1690 indicates handling by the 'latin' writing system without applying
1691 script-specific blue zones (but aligning stems to the grid if possible).
1692 The fallback script can be changed; see option
1693 [`--fallback-script`](#fallback-script).
1695 The user can also select whether uncovered glyphs are either hinted (which
1696 is the default) or scaled only with the fallback script's scaling
1697 parameters. This can be controlled with option
1698 [`--fallback-scaling`](#fallback-script). Note that fallback scaling only
1699 makes sense if the fallback script has x\ height blue zones, e.g., `cyrl` or
1702 As a special case, specifying `none` as a fallback script and switching on
1703 fallback scaling ('`-f none -S`'), no hinting is applied at all to uncovered
1704 glyphs – using `none` always implies a scaling factor of\ 1.
1710 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1711 and `GPOS` tables, and how they relate to scripts.)
1713 For modern OpenType fonts, character ranges are not sufficient to handle
1716 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1717 table), which handles ligatures and similar typographic features, there
1718 is no longer a one-to-one mapping from an input Unicode character to a
1719 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1720 for historical reasons, but most of them don't. While it is possible to
1721 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1722 from this area are arbitrary by definition and thus unusable for
1725 * Some features like `sups` (for handling superscript) completely change
1726 the appearance and even vertical position of the affected glyphs.
1727 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1728 auto-hinter puts them into a separate group (called *style* in FreeType
1729 speak), having its own set of blue zones.
1732 Table: OpenType features handled specially by ttfautohint
1734 Feature tag Description
1735 --------------- -------------
1736 `c2cp` petite capitals from capitals
1737 `c2sc` small capitals from capitals
1739 `pcap` petite capitals
1740 `sinf` scientific inferiors
1741 `smcp` small capitals
1747 There are two conditions to get a valid style for a feature in a given
1750 1. One of the script's standard characters must be available in the
1753 2. The feature must provide characters to form at least one blue zone; see
1754 [above](#blue-zones).
1756 An additional complication is that features from the above table might use
1757 data not only from the `GSUB` but also from the `GPOS` table, containing
1758 information for glyph positioning. For example, the `sups` feature for
1759 superscripts might use the same glyphs as the `subs` feature for subscripts,
1760 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1761 for accessing standard characters) because glyph positioning happens after
1762 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1763 contrary to `subs`, which holds the unshifted glyphs.
1765 The remaining OpenType features of a script are not handled specially; the
1766 affected glyphs are simply hinted together with the 'normal' glyphs of the
1769 Note that a font might still contain some features not covered yet: OpenType
1770 has the concept of a *default script*; its data gets used for all scripts
1771 that aren't explicitly handled in a font. By default, ttfautohint unifies
1772 all affected glyphs from default script features with the `latn` script.
1773 This can be changed with option [`--default-script`](#default-script), if
1777 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1783 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1784 font. Note that only OpenType fonts with TrueType outlines are supported.
1785 OpenType fonts with a `CFF` or `CFF2` table (this is, with PostScript
1786 outlines) won't work.
1788 * `glyf`: All hints in the table are replaced with new ones. If option
1789 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1790 the '\.ttfautohint' glyph) and all composites get an additional
1793 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1794 necessary for the new hinting bytecode.
1796 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1797 grid-fitting for standard hinting, and symmetric grid-fitting and
1798 symmetric smoothing for horizontal subpixel hinting (ClearType).
1800 * `DSIG`: If it exists, it gets replaced with a dummy version.
1801 ttfautohint can't digitally sign a font; you have to do that afterwards.
1803 * `name`: The 'version' entries are modified to add information about the
1804 parameters that have been used for calling ttfautohint. This can be
1805 controlled with the [`--no-info`](#ttfautohint-info) option. Family
1806 name entries might also be affected by option
1807 [`--family-suffix`](#family-suffix).
1809 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1810 additional '\.ttfautohint' glyph, the additional subglyphs in
1811 composites, and the new hinting bytecode.
1813 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1814 those tables are superfluous and thus removed.
1816 * `VDMX`: Removed, since it depends on the original bytecode, which
1817 ttfautohint removes. A font editor might recompute the necessary data
1824 ### Interaction With FreeType
1826 Some versions of FreeType have an experimental extension for handling
1827 subpixel hinting; it is off by default and can be activated by setting the
1828 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` to value\ 2 or\ 3 at compile time.
1829 This code has been contributed mainly by [Infinality], being a subset of his
1830 original patch. Many GNU/Linux distributions activate this code, or provide
1831 packages to activate it. [Note that starting with FreeType version 2.7 the
1832 Infinality extension is still available but superseded by a less aggressive
1833 subpixel hinting mode, to which the explanations in this section don't
1836 This extension changes the behaviour of many bytecode instructions to get
1837 better rendering results. However, not all changes are global; some of them
1838 are specific to certain fonts. For example, it contains font-specific
1839 improvements for the '[DejaVu] Sans' font family. The list of affected
1840 fonts is hard-coded; it can be found in FreeType's source code file
1843 If you are going to process such specially-handled fonts with ttfautohint,
1844 serious rendering problems might show up. Since ttfautohint (intentionally)
1845 doesn't change the font name in the `name` table, the Infinality extension
1846 has no chance to recognize that the hints are different. All such problems
1847 vanish if the font gets renamed in its `name` table (the name of the font
1848 file itself doesn't matter), for example, by using option
1849 [`--family-suffix`](#family-suffix).
1851 ### Incorrect Unicode Character Map
1853 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1854 ttfautohint. Especially older fonts do cheat; for example, there exist
1855 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1856 them work with non-localized versions of Windows\ 98, say.
1858 Since ttfautohint needs to find both standard and blue zone characters, it
1859 relies on correct Unicode values. If you want to handle such fonts, please
1860 fix their `cmap` tables accordingly before running ttfautohint.
1862 ### Irregular Glyph Heights
1864 The central concept of ttfautohint's hinting algorithm as discussed
1865 [above](#segments-and-edges) is to identify horizontal segments at extremum
1866 positions, especially for blue zones. If such a segment is missing, it
1867 cannot be associated with a blue zone, possibly leading to irregular heights
1868 for the particular glyph.
1870 Normally, a segment has a horizontal length of at least 20\ font units
1871 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1872 length of a segment must be at least 20 font units, and the height multiplied
1873 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1874 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1875 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1876 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1877 however, it is possible to define additional segments at arbitrary points
1878 that help overcome this restriction, making it possible to fix (most of)
1883 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1884 this might lead to strokes that look too thick at smaller sizes. A font
1885 designer might compensate this to a certain amount by slightly reducing the
1886 stroke width of diagonal lines. However, in many cases the sub-optimal
1887 appearance of a stroke with borders that don't exactly fit the pixel grid is
1888 not the outline itself but an incorrect gamma value of the monitor: People
1889 tend to not properly adjust it, and the default values of most operating
1890 systems are too low, causing too much darkening of such strokes. It is thus
1891 of vital importance to compare ttfautohint's results with similar fonts to
1892 exclude any systematic effect not related to the outlines themselves.
1895 Extending ttfautohint with new scripts
1896 --------------------------------------
1898 Right now, adding new scripts to ttfautohint only works on the source code
1899 level, this is, you have to patch the C\ source code.
1901 The process itself isn't very complicated; it is demonstrated best by
1902 example. The following commits in ttfautohint add Ethiopian and Armenian,
1905 | [https://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07](https://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07)
1906 | [https://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9](https://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9)
1908 It shows that you have to do the following steps.
1910 * Add blue zone character data to the file `lib/tablue.dat`.
1912 * Add the proper Unicode ranges to `lib/taranges.c`, following the
1913 structure of similar entries.
1915 * Similarly, the files `lib/tastyles.h` and `lib/ttfautohint-script.h`
1916 must be updated. The latter holds the information on the used default
1917 character or characters; it also references the corresponding script tag
1918 `HB_SCRIPT_XXX` as used by the HarfBuzz library.
1920 If there are any questions, please contact the [FreeType mailing
1921 list](https://lists.nongnu.org/mailman/listinfo/freetype) for help. Note
1922 that the script data in ttfautohint are hold in sync with FreeType's
1926 Control Instructions
1927 ====================
1929 An entry in a control instructions file has various syntax forms, which are
1930 discussed here. Brackets indicate optional elements.
1933 Common Syntax Elements
1934 ----------------------
1936 *font‑idx* gives the index of the font in a TrueType Collection, starting
1937 with value\ 0. If missing, it is set to zero. For normal TrueType fonts,
1938 only value zero is valid. A font index can be specified in decimal, octal,
1939 or hexadecimal format, the latter two indicated by the prefixes `0` and
1942 *glyph‑id* is either a glyph's name as listed in the font's `post` SFNT
1943 table or a glyph index. A glyph name consists of characters from the set
1944 '`A-Za-z0-9._`' only and does not start with a digit or period, with the
1945 exceptions of the names '`.notdef`' and '`.null`'. A glyph index starts
1946 with value\ 0 can be specified in decimal, octal, or hexadecimal format, the
1947 latter two indicated by the prefixes `0` and `0x`, respectively. Glyph
1948 names are internally converted to glyph indices.
1950 *points* are number ranges, see '[x Height Snapping
1951 Exceptions](#x-height-snapping-exceptions)' for the syntax.
1953 Similar to the Bourne shell (`sh` or `bash`), a comment starts with
1954 character '`#`'; the rest of the line is ignored. An empty line is ignored
1955 also. Both the newline character and '`;`' can be used as a separator
1956 between exception entries. A trailing '`\`' at the end of a line continues
1957 the current line on the next one.
1959 A control instructions file is parsed line by line; later entries override
1960 earlier entries (in case there is something to override).
1966 This syntax form makes it possible to override the style assignment
1967 algorithm of ttfautohint; see '[Scripts](#scripts)' and '[OpenType
1968 Features](#opentype-features)' for more details.
1970 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`@`*\ \ glyph-ids
1972 *script* is a four-letter name^[The notable exception is the tag 'lao',
1973 which originally has a trailing space as the fourth character. However,
1974 ttfautohint ignores the space.] of one of the scripts supported by
1975 ttfautohint. *feature* is one of the four-letter names of features
1976 supported by ttfautohint.
1978 The elements of *glyph-ids* are a list of comma separated *glyph-id* values
1979 or value ranges. Note that is not necessary that elements are specified in
1982 Assuming that a font contains superscript digits 'zero.sups' to 'nine.sups'
1983 together with the glyphs 'a.sups' and 'o.sups', use a line
1986 cyrl sups @ zero.sups-nine.sups, a.sups, o.sups
1989 to add those glyphs to the style handling Cyrillic superscript glyphs.
1990 However, it is still necessary that the selected script contains proper
1991 [Blue Zone characters](#blue-zones), otherwise those glyphs aren't handled
1994 Use the `--debug` command line option to see how ttfautohint assigns glyph
1995 indices of a font to styles.
1998 Stem Width Adjustments
1999 ----------------------
2001 Use the following syntax form to adjust stem width values for a given style,
2002 overriding ttfautohint's algorithm; see '[Scripts](#scripts)' and '[OpenType
2003 Features](#opentype-features)' for more details. This adjustment doesn't
2004 change the glyph shapes; it only influences the hinting process.
2006 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`w[idth]`*\ \ stem-widths
2008 *script* and *feature* are the same as with style adjustments; see above.
2009 However, *script* can additionally be the wildcard character '`*`', which
2010 indicates 'any script'. Parameter `width` can be abbreviated as '`w`'.
2012 *stem-widths* is an unsorted list of comma separated integer stem width
2013 values (in font units); the first value gives the style's default stem
2016 The effect of this adjustment depends [on the selected stem width
2017 algorithm](#stem-width-and-positioning-mode). For smooth stem width
2018 positioning, only the first (i.e., the default) value is used; it gets a
2019 higher preference than other discrete stem width choices. For strong stem
2020 width positioning, the stem widths are snapped to the provided values (if
2021 not differing too much) before rounding to an integer pixel value. For
2022 natural stem width positioning, this adjustment is ignored.
2024 A typical example is to reduce the default stem width of an extra-bold font,
2025 which gets better hinted if a stem width of, say, 100 is used instead of the
2026 default value 150. Let's also assume that the font further contains latin
2027 subscript and superscript characters that are hinted best with a stem width
2028 set to 80 font units. We can achieve this with the following lines in a
2029 control instructions file.
2038 Without the adjustment chances are very high that the 'eyes' in glyphs 'e'
2039 or 'a' of extra-bold fonts are filled at smaller PPEM values.
2041 Use the `--debug` command line option to see how ttfautohint assigns stem
2042 widths to styles by default.
2048 The following syntax forms allows adjustments of a glyph's hinting process.
2050 ### Change Direction of Points, Artificial Segments
2052 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ \ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
2054 The mutually exclusive parameters `left` and `right` (which can be
2055 abbreviated as '`l`' and '`r`', respectively) indicate that the following
2056 points have left or right 'out' direction, respectively, overriding
2057 ttfautohint's algorithm for setting point directions. The 'out direction'
2058 of a point is the direction of the outline *leaving* the point (or passing
2059 the control point). If the specified direction is identical to what
2060 ttfautohint computes, nothing special happens. Otherwise, a one-point
2061 segment with the specified direction gets created, see
2062 [above](#segments-and-edges). By default, its length is zero. Setting
2063 *left‑offset* and *right‑offset*, you can change the segment's horizontal
2064 start and end position relative to the point position. *left‑offset* and
2065 *right‑offset* are integers measured in font units.
2067 The following five images, displaying glyphs 'O' and 'Q' from the font
2068 [Halant-Regular](https://fonts.google.com/specimen/Halant), demonstrate
2069 how to use direction changes.
2071 ![The outlines of glyphs 'O' and 'Q', as displayed in FontForge. They are
2072 sufficiently similar to expect that ttfautohint hints them equally.
2073 However, this is not the case.](img/Halant-Regular-O-Q.png)
2075 ![The same glyphs, shown at 12px before hinting. [Please ignore the outline
2076 distortion in the upper right of glyph 'O'; this is a bug in FontForge
2077 while running the TrueType
2078 debugger.]](img/Halant-Regular-O-Q-unhinted-12px.png)
2080 ![Using only ttfautohint's '`-a sss`' parameter to force strong stem width
2081 and positioning, the hinting of glyph 'Q' is really bad, making the glyph
2082 vertically two pixels larger! Reason is that this glyph doesn't contain a
2083 horizontal segment at the baseline blue zone (*y*\ =\ 1; this corresponds
2084 to the segment 13-14 in the 'O' glyph). Normally, segment 1-2 would form
2085 a 'stem' with the baseline segment (as segment 7-8 does in glyph 'O').
2086 Instead, it forms a stem with segment 19-20, which gets moved down
2087 (*y*\ =\ −1) because the whole glyph appears to be
2088 stretched.](img/Halant-Regular-O-good-Q-badly-hinted-12px.png)
2090 ![To fix the problem, we change the direction of point\ 38 to 'left' by
2091 writing a line '`Q left 38`' (without the quotes) to a control description
2092 file `Halant-Regular.txt`. Adding option '`-m Halant-Regular.txt`' to
2093 ttfautohint, we get the shown image as a result, which is much better:
2094 Segment 1-2 now properly forms a stem with our artificial one-point
2095 segment\ 38, and the 'O'-like shape is properly positioned. However,
2096 there is still room for improvement: Segment 19-20 is also positioned at
2097 the baseline, making the connection between the 'O' shape and the tail too
2098 thin.](img/Halant-Regular-O-good-Q-better-hinted-12px.png)
2100 ![By giving the one-point segment\ 38 a horizontal width, we can prevent
2101 that segment 19-20 gets positioned at the baseline: Replace the line in
2102 the previous image description with '`Q left 38 (−70,20)`', making the
2103 segment extend 70 font units to the left and 20 to the right of point\ 38.
2104 The exact offset values don't matter; it's only important to start left of
2105 point\ 19. Another solution to the problem is to artificially change the
2106 direction of segment 19-20 by adding a second line '`Q right 19-20`' to
2107 the control instructions file; for our 'Q' glyph, this produces almost
2108 exactly the same hinting results. Note that such direction changes only
2109 influence the hinting process; an outline's direction won't be changed at
2110 all.](img/Halant-Regular-O-good-Q-well-hinted-12px.png)
2112 ### Unset Direction of Points
2114 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ \ points\
2116 Parameter `nodir` (or '`n`') sets the 'out' direction of the following
2117 points to 'no direction', this is, neither left nor right. If the specified
2118 direction is identical to what ttfautohint computes, nothing special
2119 happens. Otherwise, ttfautohint no longer considers those points as part of
2120 horizontal segments, thus treating them as ['weak'](#grid-fitting) points.
2122 Modifying or adding segments doesn't directly modify the outlines; it only
2123 influences the hinting process.
2125 ### Delta Exceptions
2127 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ \ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ \ ppems\
2129 The mutually exclusive parameters `touch` and `point` (which can be
2130 abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply delta
2131 exceptions for the given points, shifting them by the given values. Delta
2132 exceptions entered with `touch` are applied before the final 'IUP'
2133 (*interpolate untouched points*) instructions in a glyph's bytecode,
2134 exceptions entered with `point` after 'IUP' (please consult Greg Hitchcock's
2135 [ClearType Whitepaper] for more on pre-IUP and post-IUP delta hints).
2136 Additionally, the `touch` parameter makes the bytecode *touch* the affected
2137 points; such points are no longer affected by 'IUP' at all. Note that in
2138 ClearType mode all deltas along the x\ axis are discarded, and deltas along
2139 the y\ axis are only executed for touched points. As a consequence,
2140 vertical delta exceptions entered with `point` should not be used in
2141 ClearType mode.^[Unfortunately, there is a bug in FreeType prior to version
2142 2.5.4 (released in December 2014) that completely disables vertical delta
2143 exceptions if subpixel hinting is activated. For this reason you should
2144 expect that the `touch` parameter fails on older GNU/Linux distributions.]
2146 *ppems*, similar to *points*, are number ranges, see '[x Height Snapping
2147 Exceptions](#x-height-snapping-exceptions)' for the syntax.
2149 *x‑shift* and *y‑shift* represent real numbers that get rounded to multiples
2150 of 1/8 pixels. The entries for `xshift` ('`x`') and `yshift` ('`y`') are
2151 optional; if missing, the corresponding value is set to zero. If both
2152 values are zero, the delta exception entry is ignored as a whole.
2154 Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0]. Values
2155 for *ppems* must be in the range [6;53]. Values for *points* are limited by
2156 the number of points in the glyph.
2158 Note that only character '`.`' is recognized as a decimal point, and a
2159 thousands separator is not accepted.
2161 As an example for delta instructions, let's assume that you want to shift
2162 points 2, 3, and\ 4 in glyph 'Aacute' at PPEM sizes 12 and\ 13 by a vertical
2163 amount of 0.25 pixels. This corresponds to the line
2166 Aacute touch 2-4 yshift 0.25 @ 12, 13
2169 in a control instructions file. Since we use `touch` and not `point`,
2170 points 2, 3, and\ 4 are no longer subject to the final 'IUP' instruction,
2171 which interpolates weak, untouched point positions between strong, touched
2172 ones, cf. the description
2173 [here](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM05/Chap5.html#IUP).