| blob | f997dbb00d890940e8fc797bf6c7d1cf03292b48 |
1 % ttfautohint
2 % Werner Lemberg
3 %
5 <!--
6 Copyright (C) 2011-2022 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.
15 -->
18 ---
19 header-includes:
20 - \hyphenation{ttf-auto-hint}
21 ---
24 Introduction
25 ============
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),
39 respectively.
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
52 > further clarity.
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:
58 >
59 > - At small sizes, chance effects should not be allowed to magnify small
60 > differences in the original outline design of a glyph.
61 >
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:
105 ```
106 SVTCA[0]
107 PUSHB[ ] /* 3 values pushed */
108 18 1 0
109 CALL[ ]
110 PUSHB[ ] /* 2 values pushed */
111 15 4
112 MIRP[01001]
113 PUSHB[ ] /* 3 values pushed */
114 7 3 0
115 CALL[ ]
116 ```
118 Another major obstacle is the fact that font designers usually aren't
119 programmers.
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.
126 Why ttfautohint?
127 ----------------
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.
149 'Smooth' hinting
150 ----------------
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
159 render very light.
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 
191 Both the GUI and console version share the same features, to be discussed in
192 the next subsection.
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 ---------------------
204 ```
205 ttfautohint [OPTION]... [IN-FILE [OUT-FILE]]
206 ```
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.
214 ```
215 ttfautohint -v -t -m foo-control.txt foo.ttf foo-autohinted.ttf
216 ```
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.
222 ```
223 cat foo.ttf | ttfautohint -v -t -m foo-control.txt > foo-autohinted.ttf
224 ```
227 Calling `ttfautohintGUI`
228 ------------------------
230 ```
231 ttfautohintGUI [OPTION]...
232 ```
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.
250 Options
251 -------
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
256 `--foo`\ *bar*.
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
283 small sizes.
285 
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
309 bytecode larger.
311 ### Default Script
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.
321 ### Fallback Script
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.
333 ### Hinting Limit
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
340 larger than 200.
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)'
369 from Vernon Adams.
371 
379 
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)'
404 for more details.
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
416 script at all).
418 In the GUI, uncheck the 'Default Fallback Stem Width' box to activate
419 this feature.
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
457 almost all clipping.
459 ### Adjust Subglyphs
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
468 is not the case.
470 ### Hint Composites
472 `--composites`, `-c`
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 –
477 usually, it doesn't.
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).
483 ### Symbol Font
485 `--symbol`, `-s`
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.
499 ### Dehint
501 `--dehint`, `-d`
502 : Strip off all hints without generating new hints. Consequently, all
503 other hinting options are ignored. This option is intended for testing
504 purposes.
506 ### ttfautohint Info
508 `--no-info`, `-n`
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
512 info' combo box.
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
530 `--ttfa-table`, `-t`
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.
543 ### Family Suffix
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
565 also the default).
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
578 contrast.
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
622 option `-a nnn`.
624 In the GUI, simply select the desired stem width algorithm in the three
625 combo boxes.
627 
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.
640 `-w` `-a`
641 ------ ------
642 `""` `qqq`
643 `g` `sqq`
644 `G` `qsq`
645 `D` `qqs`
646 `gG` `ssq`
647 `gD` `sqs`
648 `GD` `qss`
649 `gGD` `sss`
651 ### Miscellaneous
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.
669 `--help`, `-h`
670 : On the console, print a brief documentation on standard output and exit.
671 This doesn't work with `ttfautohintGUI` on MS Windows.
673 `--version`, `-v`
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.,
688 ```
689 ttfautohint --debug -l 15 -r 15 ... > debug.txt 2>&1
690 ```
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).
708 Segments and Edges
709 ------------------
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 
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 
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
736 example.
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
742 files.
744 The analysis to find segments and edges is specific to a writing
745 system, see [below](#writing-systems).
748 Feature Analysis
749 ----------------
751 The auto-hinter analyzes a font in two steps. Right now, everything
752 described here happens for the horizontal axis only, providing vertical
753 hinting.
755 * Global Analysis
757 This affects the hinting of all glyphs, trying to give them a uniform
758 appearance.
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 `hmnp` '𞄨', U+1E128, NYIAKENG PUACHUE HMONG LETTER O
838 `kali` 'ꤍ', U+A90D, KAYAH LI LETTER NGA
839 '꤀', U+A900, KAYAH LI DIGIT ZERO
840 `knda` '೦', U+0CE6, KANNADA DIGIT ZERO
841 'ಬ', U+0CAC, KANNADA LETTER BA
842 `khmr` '០', U+17E0, KHMER DIGIT ZERO
843 `lao` '໐', U+0ED0, LAO DIGIT ZERO
844 `latn` '\Latin{}o\latin{}', U+006F, LATIN SMALL LETTER O
845 '\Latin{}O\latin{}', U+004F, LATIN CAPITAL LETTER O
846 '\Latin{}0\latin{}', U+0030, DIGIT ZERO
847 `lisu` 'ꓳ', U+A4F3, LISU LETTER
848 `medf` '𖹡', U+16E61, MEDEFAIDRIN SMALL LETTER S
849 '𖹛', U+16E5B, MEDEFAIDRIN CAPITAL LETTER N
850 '𖹯', U+16E6F, MEDEFAIDRIN SMALL LETTER E
851 `mlym` 'ഠ', U+0D20, MALAYALAM LETTER TTHA
852 'റ', U+0D31, MALAYALAM LETTER RRA
853 `mong` '\Mongolian{}ᡂ\mongolian{}', U+1842, MONGOLIAN LETTER CHI
854 '\Mongolian{}ᠪ\mongolian{}', U+182A, MONGOLIAN LETTER BA
855 `mymr` 'ဝ', U+101D, MYANMAR LETTER WA
856 'င', U+1004, MYANMAR LETTER NGA
857 'ဂ', U+1002, MYANMAR LETTER GA
858 `nkoo` 'ߋ', U+07CB, NKO LETTER EE
859 '߀', U+07C0, NKO DIGIT ZERO
860 `olck` 'ᱛ', U+1C5B, OL CHIKI LETTER AT
861 `orkh` '𐰗', U+10C17, OLD TURKIC LETTER YENISEI AY
862 `osge` '𐓂', U+104C2, OSAGE CAPITAL LETTER O
863 '𐓪', U+104EA, OSAGE SMALL LETTER O
864 `osma` '𐒆', U+10486, OSMANYA LETTER DEEL
865 '𐒠', U+104A0, OSMANYA DIGIT ZERO
866 `rohg` '𐴰', HANIFI ROHINGYA DIGIT ZERO
867 `saur` 'ꢝ', U+A89D, SAURASHTRA LETTER TTHA
868 '꣐', U+A8D0, SAURASHTRA DIGIT ZERO
869 `shaw` '𐑴', U+10474, SHAVIAN LETTER OAK
870 `sinh` 'ට', U+0DA7, SINHALA LETTER ALPAPRAANA TTAYANNA
871 `sund` '᮰', U+1BB0, SUNDANESE DIGIT ZERO
872 `taml` '௦', U+0BE6, TAMIL DIGIT ZERO
873 `tavt` 'ꪒ', U+AA92, TAI VIET LETTER LOW DO
874 'ꪫ', U+AAAB, TAI VIET LETTER HIGH VO
875 `telu` '౦', U+0C66, TELUGU DIGIT ZERO
876 '౧', U+0C67, TELUGU DIGIT ONE
877 `tfng` 'ⵔ', U+2D54, TIFINAGH LETTER YAR
878 `thai` 'า', U+0E32, THAI CHARACTER SARA AA
879 'ๅ', U+0E45, THAI CHARACTER LAKKHANGYAO
880 '๐', U+0E50, THAI DIGIT ZERO
881 `vaii` 'ꘓ', U+A613, VAI SYMBOL FEENG
882 'ꖜ', U+A59C, VAI SYLLABLE BHU
883 'ꖴ', U+A5B4, VAI SYLLABLE KU
884 `yezi` '𐺋', U+10E8B, YEZIDI LETTER DAL
885 '𐺦', U+10EA6, YEZIDI LETTER EW
888 Table: standard characters of the 'latin' writing system, special scripts
890 Script Standard characters
891 ---------- ---------------------
892 `khms` '᧡', U+19E1, KHMER SYMBOL MUOY KOET
893 '᧪', U+19EA, KHMER SYMBOL DAP KOET
894 `latb` '\Latin{}ₒ\latin{}', U+2092, LATIN SUBSCRIPT SMALL LETTER O
895 '\Latin{}₀\latin{}', U+2080, SUBSCRIPT ZERO
896 `latp` '\Latin{}ᵒ\latin{}', U+1D52, MODIFIER LETTER SMALL O
897 '\Latin{}ᴼ\latin{}', U+1D3C, MODIFIER LETTER CAPITAL O
898 '\Latin{}⁰\latin{}', U+2070, SUPERSCRIPT ZERO
901 * Glyph Analysis
903 This is a per-glyph operation.
905 + Find segments and edges.
907 + Link edges to set up stems and serifs. The abovementioned paper
908 gives more details on what exactly constitutes a stem or a serif and
909 how the algorithm works.
912 Blue Zones
913 ----------
915 
920 Outlines of certain characters are used to determine *blue zones*. This
921 concept is the same as with Type\ 1 fonts: All glyph points that lie in
922 certain small horizontal zones get aligned vertically.
924 The tables below show the blue zone characters of all available scripts of
925 the latin writing system; the values are hard-coded in the source code.
926 Since the auto-hinter takes mean values it is not necessary that all
927 characters of a zone are present.
929 'Round' characters in blue zones (e.g., the top and bottom of 'O' or the
930 bottom of 'g') are used to control overshoot handling.
932 Blue zones marked with an asterisk are x\ height blue zones, which are
933 adjusted to be on the pixel grid (to improve rendering at small sizes) by
934 scaling the remaining blue zones before they are adjusted to the grid. See
935 also option [`--increase-x-height`](#x-height-increase-limit).
938 Table: `adlm` (Adlam) blue zones
940 ID Blue zone Characters
941 ---- ----------- ------------
942 1 top of capital letters 𞤌 𞤅 𞤈 𞤏 𞤔 𞤚
943 2 bottom of capital letters 𞤂 𞤖
944 3* top of small letters 𞤬 𞤮 𞤻 𞤼 𞤾
945 4 bottom of small letters 𞤤 𞤨 𞤩 𞤭 𞤴 𞤸 𞤺 𞥀
948 Table: `arab` (Arabic) blue zones
950 ID Blue zone Characters
951 ---- ----------- ------------
952 1 top of letters with vertical stroke ا إ ل ك ط ظ
953 2 bottom of letters ت ث ط ظ ك
954 3 glyph joining ـ
957 Table: `armn` (Armenian) blue zones
959 ID Blue zone Characters
960 ---- ----------- ------------
961 1 top of capital letters Ա Մ Ւ Փ Բ Գ Դ Օ
962 2 bottom of capital letters Ւ Ո Փ Ճ Շ Ս Տ Օ
963 3 top of ascenders of small letters ե է ի մ վ փ ֆ փ
964 4* top of small letters ա յ ւ ս գ ջ ր օ
965 5 bottom of small letters հ ո ճ ա ե ծ ս օ
966 6 bottom of descenders of small letters բ ը ի լ ղ պ փ ց
969 Table: `avst` (Avestan) blue zones
971 ID Blue zone Characters
972 ---- ----------- ------------
973 1 top of letters 𐬀 𐬁 𐬐 𐬛
974 2 bottom of letters 𐬀 𐬁
977 Table: `bamu` (Bamum) blue zones
979 ID Blue zone Characters
980 ---- ----------- ------------
981 1 top of letters ꚧ ꚨ ꛛ ꛉ ꛁ ꛈ ꛫ ꛯ
982 2 bottom of letters ꚭ ꚳ ꚶ ꛬ ꚢ ꚽ ꛯ ꛲
985 Table: `beng` (Bengali) blue zones
987 ID Blue zone Characters
988 ---- ----------- ------------
989 1 baseline (flat glyphs only) অ ড ত ন ব ভ ল ক
990 2 top of ascenders ই ট ঠ ি ী ৈ ৗ
991 3* top of baseline ও এ ড ত ন ব ল ক
992 4 bottom of base characters অ ড ত ন ব ভ ল ক
994 Contrary to scripts like latin, the baseline in Bengali is on the top, and
995 we hint from top to bottom.
998 Table: `buhd` (Buhid) blue zones
1000 ID Blue zone Characters
1001 ---- ----------- ------------
1002 1 top of letters ᝐ ᝈ
1003 2 top of large letters ᝅ ᝊ ᝎ
1004 3* top of small letters ᝂ ᝃ ᝉ ᝌ
1005 4 bottom of letters ᝀ ᝃ ᝆ ᝉ ᝋ ᝏ ᝑ
1008 Table: `cakm` (Chakma) blue zones
1010 ID Blue zone Characters
1011 ---- ----------- ------------
1012 1 top of letters 𑄃 𑄅 𑄉 𑄙 𑄗
1013 2 bottom of letters 𑄅 𑄛 𑄝 𑄗 𑄓
1014 3 bottom of descenders of letters 𑄖𑄳𑄢 𑄘𑄳𑄢 𑄙𑄳𑄢 𑄤𑄳𑄢 𑄥𑄳𑄢
1017 Table: `cans` (Canadian Syllabics) blue zones
1019 ID Blue zone Characters
1020 ---- ----------- ------------
1021 1 top of letters ᗜ ᖴ ᐁ ᒣ ᑫ ᑎ ᔑ ᗰ
1022 2 bottom of letters ᗶ ᖵ ᒧ ᐃ ᑌ ᒍ ᔑ ᗢ
1023 3* top of small letters ᓓ ᓕ ᓀ ᓂ ᓄ ᕄ ᕆ ᘣ
1024 4 bottom of small letters ᕃ ᓂ ᓀ ᕂ ᓗ ᓚ ᕆ ᘣ
1025 5 top of superscript letters ᐪ ᙆ ᣘ ᐢ ᒾ ᣗ ᔆ
1026 6 bottom of superscript letters ᙆ ᗮ ᒻ ᐞ ᔆ ᒡ ᒢ ᓑ
1029 Table: `cari` (Carian) blue zones
1031 ID Blue zone Characters
1032 ---- ----------- ------------
1033 1 top of letters 𐊧 𐊫 𐊬 𐊭 𐊱 𐊺 𐊼 𐊿
1034 2 bottom of letters 𐊣 𐊧 𐊷 𐋀 𐊫 𐊸 𐋉
1037 Table: `cher` (Cherokee) blue zones
1039 ID Blue zone Characters
1040 ---- ----------- ------------
1041 1 top of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1042 2 bottom of capital letters Ꮖ Ꮋ Ꭼ Ꮓ Ꭴ Ꮳ Ꭶ Ꮥ
1043 3 top of ascenders of small letters ꮒ ꮤ ꮶ ꭴ ꭾ ꮗ ꮝ ꮿ
1044 4* top of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1045 5 bottom of small letters ꮖ ꭼ ꮓ ꮠ ꮳ ꭶ ꮥ ꮻ
1046 6 bottom of descenders of small letters ᏸ ꮐ ꭹ ꭻ
1049 Table: `copt` (Coptic) blue zones
1051 ID Blue zone Characters
1052 ---- ----------- ------------
1053 1 top of capital letters Ⲍ Ⲏ Ⲡ Ⳟ Ⲟ Ⲑ Ⲥ Ⳋ
1054 2 bottom of capital letters Ⳑ Ⳙ Ⳟ Ⲏ Ⲟ Ⲑ Ⳝ Ⲱ
1055 3* top of small letters ⲍ ⲏ ⲡ ⳟ ⲟ ⲑ ⲥ ⳋ
1056 4 bottom of small letters ⳑ ⳙ ⳟ ⲏ ⲟ ⲑ ⳝ Ⳓ
1059 Table: `cprt` (Cypriot) blue zones
1061 ID Blue zone Characters
1062 ---- ----------- ------------
1063 1 top of letters 𐠍 𐠙 𐠳 𐠱 𐠅 𐠓 𐠣 𐠦
1064 2 bottom of letters 𐠃 𐠊 𐠛 𐠣 𐠳 𐠵 𐠐
1065 3 top of small letters 𐠈 𐠏 𐠖
1066 4 bottom of small letters 𐠈 𐠏 𐠖
1069 Table: `cyrl` (Cyrillic) blue zones
1071 ID Blue zone Characters
1072 ---- ----------- ------------
1073 1 top of capital letters \Cyrillic{}Б В Е П З О С Э\cyrillic{}
1074 2 bottom of capital letters \Cyrillic{}Б В Е Ш З О С Э\cyrillic{}
1075 3* top of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1076 4 bottom of small letters \Cyrillic{}х п н ш е з о с\cyrillic{}
1077 5 bottom of descenders of small letters \Cyrillic{}р у ф\cyrillic{}
1080 Table: `deva` (Devanagari) blue zones
1082 ID Blue zone Characters
1083 ---- ----------- ------------
1084 1 top of ascenders ई ऐ ओ औ ि ी ो ौ
1085 2 top of baseline क म अ आ थ ध भ श
1086 3* top of baseline (flat glyphs only) क न म उ छ ट ठ ड
1087 4 bottom of base characters क न म उ छ ट ठ ड
1088 5 bottom of descenders ु ृ
1090 Contrary to scripts like latin, the baseline in Devanagari is on the top,
1091 and we hint from top to bottom. Note that some fonts have extreme variation
1092 in the height of the round elements in Zone\ 3; for this reason we also
1093 define Zone\ 1, which must be always present.
1096 Table: `dsrt` (Deseret) blue zones
1098 ID Blue zone Characters
1099 ---- ----------- ------------
1100 1 top of capital letters 𐐂 𐐄 𐐋 𐐗 𐐑
1101 2 bottom of capital letters 𐐀 𐐂 𐐄 𐐗 𐐛
1102 3* top of small letters 𐐪 𐐬 𐐳 𐐿 𐐹
1103 4 bottom of small letters 𐐨 𐐪 𐐬 𐐿 𐑃
1106 Table: `ethi` (Ethiopian) blue zones
1108 ID Blue zone Characters
1109 ---- ----------- ------------
1110 1 top of letters ሀ ሃ ዘ ፐ ማ በ ዋ ዐ
1111 2 bottom of letters ለ ሐ በ ዘ ሀ ሪ ዐ ጨ
1114 Table: `geok` (Georgian Khutsuri) blue zones
1116 ID Blue zone Characters
1117 ---- ----------- ------------
1118 1 top of Asomtavruli letters Ⴑ Ⴇ Ⴙ Ⴜ Ⴄ Ⴅ Ⴓ Ⴚ
1119 2 bottom of Asomtavruli letters Ⴄ Ⴅ Ⴇ Ⴈ Ⴆ Ⴑ Ⴊ Ⴋ
1120 3* top of Nuskhuri letters ⴁ ⴗ ⴂ ⴄ ⴅ ⴇ ⴔ ⴖ
1121 4 bottom of Nuskhuri letters ⴈ ⴌ ⴖ ⴎ ⴃ ⴆ ⴋ ⴢ
1122 5 top of ascender Nuskhuri letters ⴐ ⴑ ⴓ ⴕ ⴙ ⴛ ⴡ ⴣ
1123 6 bottom of Nuskhuri descender letters ⴄ ⴅ ⴔ ⴕ ⴁ ⴂ ⴘ ⴝ
1125 Georgian Asomtavruli and Nuskhuri form the old ecclesiastical script,
1126 Khutsuri. Note that fonts show a great variation in height and depth of
1127 ascender and descender letter forms.
1130 Table: `geor` (Georgian Mkhedruli) blue zones
1132 ID Blue zone Characters
1133 ---- ----------- ------------
1134 1* top of Mkhedruli letters გ დ ე ვ თ ი ო ღ
1135 2 bottom of Mkhedruli letters ა ზ მ ს შ ძ ხ ჰ
1136 3 top of ascender Mkhedruli letters ს ხ ქ ზ მ შ ჩ წ
1137 4 bottom of descender Mkhedruli letters ე ვ ჟ ტ უ ფ ქ ყ
1138 5 top of ascender Mtavruli letters Ნ Ჟ Ჳ Ჸ Გ Ე Ო Ჴ
1139 6 bottom of descender Mtavruli letters Ი Ჲ Ო Ჩ Მ Შ Ჯ Ჽ
1142 Table: `glag` (Glagolitic) blue zones
1144 ID Blue zone Characters
1145 ---- ----------- ------------
1146 1 top of capital letters Ⰵ Ⱄ Ⱚ Ⰴ Ⰲ Ⰺ Ⱛ Ⰻ
1147 2 bottom of capital letters Ⰵ Ⰴ Ⰲ Ⱚ Ⱎ Ⱑ Ⰺ Ⱄ
1148 3* top of small letters ⰵ ⱄ ⱚ ⰴ ⰲ ⰺ ⱛ ⰻ
1149 4 bottom of small letters ⰵ ⰴ ⰲ ⱚ ⱎ ⱑ ⰺ ⱄ
1152 Table: `goth` (Gothic) blue zones
1154 ID Blue zone Characters
1155 ---- ----------- ------------
1156 1 top of letters 𐌲 𐌶 𐍀 𐍄 𐌴 𐍃 𐍈 𐌾
1157 2 bottom of letters 𐌶 𐌴 𐍃 𐍈
1160 Table: `grek` (Greek) blue zones
1162 ID Blue zone Characters
1163 ---- ----------- ------------
1164 1 top of capital letters \Greek{}Γ Β Ε Ζ Θ Ο Ω\greek{}
1165 2 bottom of capital letters \Greek{}Β Δ Ζ Ξ Θ Ο\greek{}
1166 3 top of 'small beta' like letters \Greek{}β θ δ ζ λ ξ\greek{}
1167 4* top of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1168 5 bottom of small letters \Greek{}α ε ι ο π σ τ ω\greek{}
1169 6 bottom of descenders of small letters \Greek{}β γ η μ ρ φ χ ψ\greek{}
1172 Table: `gujr` (Gujarati) blue zones
1174 ID Blue zone Characters
1175 ---- ----------- ------------
1176 1* top of letters ત ન ઋ ઌ છ ટ ર ૦
1177 2 bottom of letters ખ ગ ઘ ઞ ઇ ઈ ઠ જ
1178 3 top of ascenders ઈ ઊ િ ી લી શ્ચિ જિ સી
1179 4 bottom of descenders ુ ૃ ૄ ખુ છૃ છૄ
1180 5 top of Gujarati digits ૦ ૧ ૨ ૩ ૭
1183 Table: `guru` (Gurmukhi) blue zones
1185 ID Blue zone Characters
1186 ---- ----------- ------------
1187 1 top of ascenders ਇ ਈ ਉ ਏ ਓ ੳ ਿ ੀ
1188 2 top of baseline ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1189 3* top of baseline (flat glyphs only) ਕ ਗ ਙ ਚ ਜ ਤ ਧ ਸ
1190 4 bottom of characters ਅ ਏ ਓ ਗ ਜ ਠ ਰ ਸ
1191 5 top of Gurmukhi digits ੦ ੧ ੨ ੩ ੭
1194 Table: `hebr` (Hebrew) blue zones
1196 ID Blue zone Characters
1197 ---- ----------- ------------
1198 1 top of letters ב ד ה ח ך כ ם ס
1199 2 bottom of letters ב ט כ ם ס צ
1200 3 bottom of descenders of letters ק ך ן ף ץ
1203 Table: `hmnp` (Nyiakeng Puachue Hmong) blue zones
1205 ID Blue zone Characters
1206 ---- ----------- ------------
1207 1 top of letters 𞄀 𞄁 𞄈 𞄑 𞄧 𞄬
1208 2 bottom of letters 𞄁 𞄜 𞄠 𞄡 𞄤 𞅂
1211 Table: `kali` (Kayah Li) blue zones
1213 ID Blue zone Characters
1214 ---- ----------- ------------
1215 1* top of letters ꤅ ꤏ ꤁ ꤋ ꤀ ꤍ
1216 2 bottom of letters ꤈ ꤘ ꤀ ꤍ ꤢ
1217 3 top of ascending letters ꤖ ꤡ
1218 4 bottom of descending letters ꤑ ꤜ ꤞ
1219 5 bottom of large descending letters ꤑ꤬ ꤜ꤭ ꤔ꤬
1222 Table: `khmr` (Khmer) blue zones
1224 ID Blue zone Characters
1225 ---- ----------- ------------
1226 1* top of letters ខ ទ ន ឧ ឩ ា
1227 2 top of subscript cluster components ក្ក ក្ខ ក្គ ក្ថ
1228 3 bottom of letters ខ ឃ ច ឋ ប ម យ ឲ
1229 4 bottom of descenders ត្រ រៀ ឲ្យ អឿ
1230 5 bottom of large descenders ន្ត្រៃ ង្ខ្យ ក្បៀ ច្រៀ ន្តឿ ល្បឿ
1233 Table: `khms` (Khmer Symbols) blue zones
1235 ID Blue zone Characters
1236 ---- ----------- ------------
1237 1* top of symbols for waxing ᧠ ᧡
1238 2 bottom of symbols for waning ᧶ ᧹
1240 Khmer symbols are used for lunar dates.
1243 Table: `knda` (Kannada) blue zones
1245 ID Blue zone Characters
1246 ---- ----------- ------------
1247 1 top of letters ಇ ಊ ಐ ಣ ಸಾ ನಾ ದಾ ರಾ
1248 2 bottom of letters ಅ ಉ ಎ ಲ ೦ ೨ ೬ ೭
1251 Table: `lao` (Lao) blue zones
1253 ID Blue zone Characters
1254 ---- ----------- ------------
1255 1* top of letters າ ດ ອ ມ ລ ວ ຣ ງ
1256 2 bottom of letters າ ອ ບ ຍ ຣ ຮ ວ ຢ
1257 3 top of ascenders ປ ຢ ຟ ຝ
1258 4 top of large ascenders ໂ ໄ ໃ
1259 5 bottom of descenders ງ ຊ ຖ ຽ ໆ ຯ
1262 Table: `latb` (Latin Subscripts) blue zones
1264 ID Blue zone Characters
1265 ---- ----------- ------------
1266 1 top of capital characters \Latin{}₀ ₃ ₅ ₇ ₈\latin{}
1267 2 bottom of capital characters \Latin{}₀ ₁ ₂ ₃ ₈\latin{}
1268 3 top of 'small f' like characters \Latin{}ᵢ ⱼ ₕ ₖ ₗ\latin{}
1269 4* top of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1270 5 bottom of small characters \Latin{}ₐ ₑ ₒ ₓ ₙ ₛ ᵥ ᵤ ᵣ\latin{}
1271 6 bottom of descenders of small characters \Latin{}ᵦ ᵧ ᵨ ᵩ ₚ\latin{}
1273 Subscript latin characters are similar to normal latin characters.
1276 Table: `latn` (Latin) blue zones
1278 ID Blue zone Characters
1279 ---- ----------- ------------
1280 1 top of capital letters \Latin{}T H E Z O C Q S\latin{}
1281 2 bottom of capital letters \Latin{}H E Z L O C U S\latin{}
1282 3 top of 'small f' like letters \Latin{}f i j k d b h\latin{}
1283 4* top of small letters \Latin{}u v x z o e s c\latin{}
1284 5 bottom of small letters \Latin{}n r x z o e s c\latin{}
1285 6 bottom of descenders of small letters \Latin{}p q g j y\latin{}
1288 Table: `latp` (Latin Superscripts) blue zones
1290 ID Blue zone Characters
1291 ---- ----------- ------------
1292 1 top of capital characters \Latin{}⁰ ³ ⁵ ⁷ ᵀ ᴴ ᴱ ᴼ\latin{}
1293 2 bottom of capital characters \Latin{}⁰ ¹ ² ³ ᴱ ᴸ ᴼ ᵁ\latin{}
1294 3 top of 'small f' like characters \Latin{}ᵇ ᵈ ᵏ ʰ ʲ ᶠ ⁱ\latin{}
1295 4* top of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1296 5 bottom of small characters \Latin{}ᵉ ᵒ ʳ ˢ ˣ ᶜ ᶻ\latin{}
1297 6 bottom of descenders of small characters \Latin{}ᵖ ʸ ᵍ\latin{}
1299 Superscript latin characters are similar to normal latin characters.
1302 Table: `lisu` (Lisu) blue zones
1304 ID Blue zone Characters
1305 ---- ----------- ------------
1306 1 top of letters ꓡ ꓧ ꓱ ꓶ ꓩ ꓚ ꓵ ꓳ
1307 2 bottom of letters ꓕ ꓜ ꓞ ꓡ ꓛ ꓢ ꓳ ꓴ
1310 Table: `medf` (Medefaidrin) blue zones
1312 ID Blue zone Characters
1313 ---- ----------- ------------
1314 1 top of capital letters 𖹀 𖹁 𖹂 𖹃 𖹏 𖹚 𖹟
1315 2 bottom of capital letters 𖹀 𖹁 𖹂 𖹃 𖹏 𖹚 𖹒 𖹓
1316 3 top of ascenders of small letters 𖹤 𖹬 𖹧 𖹴 𖹶 𖹾
1317 4* top of small letters 𖹠 𖹡 𖹢 𖹹 𖹳 𖹮
1318 5 bottom of small letters 𖹠 𖹡 𖹢 𖹳 𖹭 𖹽
1319 6 bottom of descenders of small letters 𖹥 𖹨 𖹩
1320 7 top of Medefaidrin digits 𖺀 𖺅 𖺈 𖺄 𖺍
1323 Table: `mlym` (Malayalam) blue zones
1325 ID Blue zone Characters
1326 ---- ----------- ------------
1327 1 top of letters ഒ ട ഠ റ ച പ ച്ച പ്പ
1328 2 bottom of letters ട ഠ ധ ശ ഘ ച ഥ ല
1331 Table: `mong` (Mongolian) blue zones
1333 ID Blue zone Characters
1334 ---- ----------- ------------
1335 1 top of base stem \Mongolian{}ᠳ ᠴ ᠶ ᠽ ᡂ ᡊ ᡡ ᡳ\mongolian{}
1336 2 bottom of base stem \Mongolian{}ᡃ\mongolian{}
1339 Table: `mymr` (Myanmar) blue zones
1341 ID Blue zone Characters
1342 ---- ----------- ------------
1343 1* top of letters ခ ဂ င ဒ ဝ ၥ ၊ ။
1344 2 bottom of letters င ဎ ဒ ပ ဗ ဝ ၊ ။
1345 3 top of ascenders of characters ဩ ြ ၍ ၏ ၆ ါ ိ
1346 3 bottom of descenders of letters ဉ ည ဥ ဩ ဨ ၂ ၅ ၉
1349 Table: `nkoo` (N'Ko) blue zones
1351 ID Blue zone Characters
1352 ---- ----------- ------------
1353 1 top of letters ߐ ߉ ߒ ߟ ߖ ߜ ߠ ߥ
1354 2 bottom of letters ߀ ߘ ߡ ߠ ߥ
1355 3* top of small letters ߏ ߛ ߋ
1356 4 bottom of small letters ߎ ߏ ߛ ߋ
1359 Table: `olck` (Ol Chiki) blue zones
1361 ID Blue zone Characters
1362 ---- ----------- ------------
1363 1 top of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1364 2 bottom of letters ᱛ ᱜ ᱝ ᱡ ᱢ ᱥ
1367 Table: `orkh` (Old Turkic) blue zones
1369 ID Blue zone Characters
1370 ---- ----------- ------------
1371 1 top of letters 𐰗 𐰘 𐰧
1372 2 bottom of letters 𐰉 𐰗 𐰦 𐰧
1375 Table: `osge` (Osage) blue zones
1377 ID Blue zone Characters
1378 ---- ----------- ------------
1379 1 top of capital letters 𐒾 𐓍 𐓒 𐓓 𐒻 𐓂 𐒵 𐓆
1380 2 bottom of capital letters 𐒰 𐓍 𐓂 𐒿 𐓎 𐒹
1381 3 bottom of descenders of capital letters 𐒼 𐒽 𐒾
1382 4* top of small letters 𐓵 𐓶 𐓺 𐓻 𐓝 𐓣 𐓪 𐓮
1383 5 bottom of small letters 𐓘 𐓚 𐓣 𐓵 𐓡 𐓧 𐓪 𐓶
1384 6 top of ascenders of small letters 𐓤 𐓦 𐓸 𐓹 𐓛
1385 7 bottom of descenders of small letters 𐓤 𐓥 𐓦
1388 Table: `osma` (Osmanya) blue zones
1390 ID Blue zone Characters
1391 ---- ----------- ------------
1392 1 top of letters 𐒆 𐒉 𐒐 𐒒 𐒘 𐒛 𐒠 𐒣
1393 2 bottom of letters 𐒀 𐒂 𐒆 𐒈 𐒊 𐒒 𐒠 𐒩
1396 Table: `rohg` (Hanifi Rohingya) blue zones
1398 ID Blue zone Characters
1399 ---- ----------- ------------
1400 1 top of letters with vertical stroke 𐴃 𐴀 𐴆 𐴖 𐴕
1401 2 bottom of letters 𐴔 𐴖 𐴕 𐴑 𐴐
1402 3 glyph joining ـ
1405 Table: `saur` (Saurashtra) blue zones
1407 ID Blue zone Characters
1408 ---- ----------- ------------
1409 1 top of letters ꢜ ꢞ ꢳ ꢂ ꢖ ꢒ ꢝ ꢛ
1410 2 bottom of letters ꢂ ꢨ ꢺ ꢤ ꢎ
1413 Table: `shaw` (Shavian) blue zones
1415 ID Blue zone Characters
1416 ---- ----------- ------------
1417 1 top of letters 𐑕 𐑙
1418 2 bottom of letters 𐑔 𐑖 𐑗 𐑹 𐑻
1419 3 bottom of descenders of letters 𐑟 𐑣
1420 4* top of small letters 𐑱 𐑲 𐑳 𐑴 𐑸 𐑺 𐑼
1421 5 bottom of small letters 𐑴 𐑻 𐑹
1424 Table: `sinh` (Sinhala) blue zones
1426 ID Blue zone Characters
1427 ---- ----------- ------------
1428 1 top of letters ඉ ක ඝ ඳ ප ය ල ෆ
1429 2 bottom of letters එ ඔ ඝ ජ ට ථ ධ ර
1430 3 bottom of descenders of letters ද ඳ උ ල තූ තු බු දු
1433 Table: `sund` (Sundanese) blue zones
1435 ID Blue zone Characters
1436 ---- ----------- ------------
1437 1 top of letters ᮋ ᮞ ᮮ ᮽ ᮰ ᮈ
1438 2 bottom of letters ᮄ ᮔ ᮕ ᮗ ᮰ ᮆ ᮈ ᮉ
1439 3 bottom of descenders of letters ᮼ ᳄
1442 Table: `taml` (Tamil) blue zones
1444 ID Blue zone Characters
1445 ---- ----------- ------------
1446 1 top of letters உ ஒ ஓ ற ஈ க ங ச
1447 2 bottom of letters க ச ல ஶ உ ங ட ப
1450 Table: `tavt` (Tai Viet) blue zones
1452 ID Blue zone Characters
1453 ---- ----------- ------------
1454 1 top of letters ꪆ ꪔ ꪒ ꪖ ꪫ
1455 2 bottom of letters ꪉ ꪫ ꪮ
1458 Table: `telu` (Telugu) blue zones
1460 ID Blue zone Characters
1461 ---- ----------- ------------
1462 1 top of letters ఇ ఌ ఙ ఞ ణ ఱ ౯
1463 2 bottom of letters అ క చ ర ఽ ౨ ౬
1466 Table: `tfng` (Tifinagh) blue zones
1468 ID Blue zone Characters
1469 ---- ----------- ------------
1470 1 top of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1471 2 bottom of letters ⵔ ⵙ ⵛ ⵞ ⴵ ⴼ ⴹ ⵎ
1474 Table: `thai` (Thai) blue zones
1476 ID Blue zone Characters
1477 ---- ----------- ------------
1478 1* top of letters บ เ แ อ ก า
1479 2 bottom of letters บ ป ษ ฯ อ ย ฮ
1480 3 top of ascenders of letters ป ฝ ฟ
1481 4 top of large ascenders of letters โ ใ ไ
1482 5 bottom of descenders of letters ฎ ฏ ฤ ฦ
1483 6 bottom of large descenders of letters ญ ฐ
1484 7 top of Thai digits ๐ ๑ ๓
1487 Table: `vaii` (Vai) blue zones
1489 ID Blue zone Characters
1490 ---- ----------- ------------
1491 1 top of letters ꗍ ꘖ ꘙ ꘜ ꖜ ꖝ ꔅ ꕢ
1492 2 bottom of letters ꗍ ꘖ ꘙ ꗞ ꔅ ꕢ ꖜ ꔆ
1495 Table: `yezi` (Yezidi) blue zones
1497 ID Blue zone Characters
1498 ---- ----------- ------------
1499 1* top of letters 𐺁 𐺂 𐺃 𐺄 𐺆 𐺉 𐺋
1500 2 bottom of letters 𐺁 𐺄 𐺆 𐺋 𐺍 𐺐
1501 3 top of ascenders of letters 𐺀 𐺠 𐺡
1502 4 bottom of descenders of letters 𐺂 𐺃 𐺕 𐺛 𐺜 𐺝 𐺨
1505 
1509 Grid Fitting
1510 ------------
1512 Aligning outlines along the grid lines is called *grid fitting*. It doesn't
1513 necessarily mean that the outlines are positioned *exactly* on the grid,
1514 however, especially if you want a smooth appearance at different sizes.
1515 This is the central routine of the auto-hinter; its actions are highly
1516 dependent on the used writing system. Currently, only one writing system is
1517 available (latin), providing support for scripts like Latin or Greek.
1519 * Align edges linked to blue zones.
1521 * Fit edges to the pixel grid.
1523 * Align serif edges.
1525 * Handle remaining 'strong' points. Such points are not part of an edge
1526 but are still important for defining the shape. This roughly
1527 corresponds to the `IP` TrueType instruction.
1529 * Everything else (the 'weak' points) is handled with an 'IUP'
1530 instruction.
1532 The following images illustrate the hinting process, using glyph 'a' from
1533 the freely available font '[Ubuntu Book](https://design.ubuntu.com/font/)'. The
1534 manual hints were added by [Dalton Maag Ltd], the used application to create
1535 the hinting debug snapshots was [FontForge].
1537 
1539 
1541 
1545 Hint Sets
1546 ---------
1548 In ttfautohint terminology, a *hint set* is the *optimal* configuration for
1549 a given PPEM (pixel per EM) value.
1551 In the range given by the `--hinting-range-min` and `--hinting-range-max`
1552 options, ttfautohint creates hint sets for every PPEM value. For each
1553 glyph, ttfautohint automatically determines whether a new set should be
1554 emitted for a PPEM value if it finds that it differs from a previous one.
1555 For some glyphs it is possible that one set covers, say, the range
1556 8px-1000px, while other glyphs need 10 or more such sets.
1558 In the PPEM range below `--hinting-range-min`, ttfautohint always uses just
1559 one set, in the PPEM range between `--hinting-range-max` and
1560 `--hinting-limit`, it also uses just one set.
1562 One of the hinting configuration parameters is the decision which segments
1563 form an edge. For example, let us assume that two segments get aligned on a
1564 single horizontal edge at 11px, while two edges are used at 12px. This
1565 change makes ttfautohint emit a new hint set to accomodate this situation.
1566 The next images illustrate this, using a Cyrillic letter (glyph 'afii10108')
1567 from the 'Ubuntu book' font, processed with ttfautohint.
1569 
1571 
1575 
1577 
1582 Obviously, the more hint sets get emitted, the larger the bytecode
1583 ttfautohint adds to the output font. To find a good value\ *n* for
1584 `--hinting-range-max`, some experimentation is necessary since *n* depends
1585 on the glyph shapes in the input font. If the value is too low, the hint
1586 set created for the PPEM value\ *n* (this hint set gets used for all larger
1587 PPEM values) might distort the outlines too much in the PPEM range given
1588 by\ *n* and the value set by `--hinting-limit` (at which hinting gets
1589 switched off). If the value is too high, the font size increases due to
1590 more hint sets without any noticeable hinting effects.
1592 Similar arguments hold for `--hinting-range-min` except that there is no
1593 lower limit at which hinting is switched off.
1595 An example. Let's assume that we have a hinting range 10\ <= ppem <=\ 100,
1596 and the hinting limit is set to 250. For a given glyph, ttfautohint finds
1597 out that four hint sets must be computed to exactly cover this hinting
1598 range: 10-15, 16-40, 41-80, and 81-100. For PPEM values below 10ppem, the
1599 hint set covering 10-15ppem is used, for PPEM values larger than 100 the
1600 hint set covering 81-100ppem is used. For PPEM values larger than 250, no
1601 hinting gets applied.
1604 Composite Glyphs
1605 ----------------
1607 The ttfautohint library (and programs) supports two solutions for handling
1608 composite glyphs, to be controlled with option
1609 [`--composites`](#hint-composites). This section contains some general
1610 information, then covers the case where the option is off, while the next
1611 section describes how ttfautohint behaves if this option is activated.
1613 Regardless of the `--composites` option, ttfautohint performs a scan over
1614 all composite glyphs to assure that components of a composite glyph inherit
1615 its style, as described [later](#opentype-features). However, components
1616 that are shifted vertically will be skipped. For example, if the glyph
1617 'Agrave' uses a shifted 'grave' accent glyph, the accent is ignored. On the
1618 other hand, if there is a glyph 'agrave' that uses the same 'grave' glyph
1619 vertically unshifted, 'grave' does inherit the style.
1621 If `--composites` is off, components are hinted separately, then put
1622 together. Separate hinting implies that the current style's blue zones are
1623 applied to all subglyphs in its original, unshifted positions. In case you
1624 want to shift components vertically, it is *mandatory* to set bit\ 2
1625 (value\ 4), `ROUND_XY_TO_GRID`, in the flag variable of the composite glyph
1626 description to get visually pleasing results, as the images below
1627 demonstrate.
1629 
1636 
1640 
1648 The '\.ttfautohint' Glyph
1649 -------------------------
1651 If option [`--composites`](#hint-composites) is used, ttfautohint doesn't
1652 hint subglyphs of composite glyphs separately. Instead, it hints the whole
1653 glyph, this is, composites get recursively expanded internally so that they
1654 form simple glyphs, then hints are applied -- this is the normal working
1655 mode of FreeType's auto-hinter.
1657 One problem, however, must be solved: Hinting for subglyphs (which usually
1658 are used as normal glyphs also) must be deactivated so that nothing but the
1659 final bytecode of the composite gets executed.
1661 The trick used by ttfautohint is to prepend a composite element called
1662 '\.ttfautohint', a dummy glyph with a single point, and which has a single
1663 job: Its bytecode increases a variable (to be more precise, it is a CVT
1664 register called `cvtl_is_subglyph` in the source code), indicating that we
1665 are within a composite glyph. The final bytecode of the composite glyph
1666 eventually decrements this variable again.
1668 As an example, let's consider composite glyph 'Agrave' ('À'), which has the
1669 subglyph 'A' as the base and 'grave' as its accent. After processing with
1670 ttfautohint it consists of three components: '\.ttfautohint', 'A', and
1671 'grave' (in this order).
1673 Bytecode of Action
1674 ------------- --------
1675 .ttfautohint increase `cvtl_is_subglyph` (now: 1)
1676 A do nothing because `cvtl_is_subglyph` > 0
1677 grave do nothing because `cvtl_is_subglyph` > 0
1678 Agrave decrease `cvtl_is_subglyph` (now: 0)
1679 apply hints because `cvtl_is_subglyph` == 0
1681 Some technical details (which you might skip): All glyph point indices get
1682 adjusted since each '\.ttfautohint' subglyph shifts all following indices by
1683 one. This must be done for both the bytecode and one subformat of
1684 OpenType's `GPOS` anchor tables.
1686 While this approach works fine on all tested platforms, there is one single
1687 drawback: Direct rendering of the '\.ttfautohint' subglyph (this is,
1688 rendering as a stand-alone glyph) disables proper hinting of all glyphs in
1689 the font! Under normal circumstances this never happens because
1690 '\.ttfautohint' doesn't have an entry in the font's `cmap` table. (However,
1691 some test and demo programs like FreeType's `ftview` application or other
1692 glyph viewers that are able to bypass the `cmap` table might be affected.)
1695 Writing Systems
1696 ---------------
1698 In FreeType terminology, a writing system is a set of functions that
1699 provides auto-hinting for certain scripts. Right now, only two writing
1700 systems from FreeType's auto-hinter are available in ttfautohint: 'dummy'
1701 and 'latin'. The former handles the 'no-script' case; details to 'latin'
1702 follow in the next section.
1705 Scripts
1706 -------
1708 ttfautohint needs to know which script should be used to hint a specific
1709 glyph. To do so, it checks a glyph's Unicode character code whether it
1710 belongs to a given script.
1712 See '[Character Ranges](#character-ranges)' for a complete list of all
1713 handled scripts and its ranges. This list is auto-generated from a source
1714 code file, covering the 'latin' writing system. It also covers some
1715 non-latin scripts (in the Unicode sense) that have similar typographical
1716 properties.
1718 In ttfautohint, scripts are identified by four-character tags (if there are
1719 less characters, spaces are appended). The value `none` indicates 'no
1720 script'.
1722 Each script is represented by two tables to handle 'base' and 'non-base'
1723 characters. For ttfautohint, a non-base character is something that should
1724 not be affected by blue zones, regardless of whether this is a spacing or
1725 no-spacing glyph. In other words, non-base characters are hinted using a
1726 script's default stem width without applying blue zones.
1728 Right now, there are two pseudo-scripts that are used as fallbacks: `latb`
1729 and `latp`, used for latin subscript and superscript characters,
1730 respectively. Its main usage is support of phonetic alphabets like the IPA,
1731 which intermix those characters with normal characters sitting on the
1732 baseline, and which are not specially handled in corresponding OpenType
1733 features like `sups`.
1735 If a glyph's character code is not covered by a script range, it is handled
1736 by a *fallback script*. By default, the fallback script is `none`, which
1737 indicates handling by the 'latin' writing system without applying
1738 script-specific blue zones (but aligning stems to the grid if possible).
1739 The fallback script can be changed; see option
1740 [`--fallback-script`](#fallback-script).
1742 The user can also select whether uncovered glyphs are either hinted (which
1743 is the default) or scaled only with the fallback script's scaling
1744 parameters. This can be controlled with option
1745 [`--fallback-scaling`](#fallback-script). Note that fallback scaling only
1746 makes sense if the fallback script has x\ height blue zones, e.g., `cyrl` or
1747 `latn`.
1749 As a special case, specifying `none` as a fallback script and switching on
1750 fallback scaling ('`-f none -S`'), no hinting is applied at all to uncovered
1751 glyphs – using `none` always implies a scaling factor of\ 1.
1754 OpenType Features
1755 -----------------
1757 (Please read the [OpenType specification] for details on *features*, `GSUB`,
1758 and `GPOS` tables, and how they relate to scripts.)
1760 For modern OpenType fonts, character ranges are not sufficient to handle
1761 scripts.
1763 * Due to glyph substitution in the font (as specified in a font's `GSUB`
1764 table), which handles ligatures and similar typographic features, there
1765 is no longer a one-to-one mapping from an input Unicode character to a
1766 glyph index. Some ligatures, like 'fi', actually do have Unicode values
1767 for historical reasons, but most of them don't. While it is possible to
1768 map ligature glyphs into Unicode's Private Use Area (PUA), code values
1769 from this area are arbitrary by definition and thus unusable for
1770 ttfautohint.
1772 * Some features like `sups` (for handling superscript) completely change
1773 the appearance and even vertical position of the affected glyphs.
1774 Obviously, the blue zones for 'normal' glyphs no longer fit, thus the
1775 auto-hinter puts them into a separate group (called *style* in FreeType
1776 speak), having its own set of blue zones.
1779 Table: OpenType features handled specially by ttfautohint
1781 Feature tag Description
1782 --------------- -------------
1783 `c2cp` petite capitals from capitals
1784 `c2sc` small capitals from capitals
1785 `ordn` ordinals
1786 `pcap` petite capitals
1787 `sinf` scientific inferiors
1788 `smcp` small capitals
1789 `subs` subscript
1790 `sups` superscript
1791 `titl` titling
1794 There are two conditions to get a valid style for a feature in a given
1795 script.
1797 1. One of the script's standard characters must be available in the
1798 feature.
1800 2. The feature must provide characters to form at least one blue zone; see
1801 [above](#blue-zones).
1803 An additional complication is that features from the above table might use
1804 data not only from the `GSUB` but also from the `GPOS` table, containing
1805 information for glyph positioning. For example, the `sups` feature for
1806 superscripts might use the same glyphs as the `subs` feature for subscripts,
1807 simply moved up. ttfautohint skips such vertically shifted glyphs (except
1808 for accessing standard characters) because glyph positioning happens after
1809 hinting. Continuing our example, the `sups` feature wouldn't form a style,
1810 contrary to `subs`, which holds the unshifted glyphs.
1812 The remaining OpenType features of a script are not handled specially; the
1813 affected glyphs are simply hinted together with the 'normal' glyphs of the
1814 script.
1816 Note that a font might still contain some features not covered yet: OpenType
1817 has the concept of a *default script*; its data gets used for all scripts
1818 that aren't explicitly handled in a font. By default, ttfautohint unifies
1819 all affected glyphs from default script features with the `latn` script.
1820 This can be changed with option [`--default-script`](#default-script), if
1821 necessary.
1824 ttfautohint uses the [HarfBuzz] library for handling OpenType features.
1827 SFNT Tables
1828 -----------
1830 ttfautohint touches almost all SFNT tables within a TrueType or OpenType
1831 font. Note that only OpenType fonts with TrueType outlines are supported.
1832 OpenType fonts with a `CFF` or `CFF2` table (this is, with PostScript
1833 outlines) won't work.
1835 * `glyf`: All hints in the table are replaced with new ones. If option
1836 [`--composites`](#hint-composites) is used, one glyph gets added (namely
1837 the '\.ttfautohint' glyph) and all composites get an additional
1838 component.
1840 * `cvt`, `prep`, and `fpgm`: These tables get replaced with data
1841 necessary for the new hinting bytecode.
1843 * `gasp`: Set up to always use grayscale rendering, for all sizes, with
1844 grid-fitting for standard hinting, and symmetric grid-fitting and
1845 symmetric smoothing for horizontal subpixel hinting (ClearType).
1847 * `DSIG`: If it exists, it gets replaced with a dummy version.
1848 ttfautohint can't digitally sign a font; you have to do that afterwards.
1850 * `name`: The 'version' entries are modified to add information about the
1851 parameters that have been used for calling ttfautohint. This can be
1852 controlled with the [`--no-info`](#ttfautohint-info) option. Family
1853 name entries might also be affected by option
1854 [`--family-suffix`](#family-suffix).
1856 * `GPOS`, `hmtx`, `loca`, `head`, `maxp`, `post`: Updated to fit the
1857 additional '\.ttfautohint' glyph, the additional subglyphs in
1858 composites, and the new hinting bytecode.
1860 * `LTSH`, `hdmx`: Since ttfautohint doesn't do any horizontal hinting,
1861 those tables are superfluous and thus removed.
1863 * `VDMX`: Removed, since it depends on the original bytecode, which
1864 ttfautohint removes. A font editor might recompute the necessary data
1865 later on.
1868 Problems
1869 --------
1871 ### Interaction With FreeType
1873 Some versions of FreeType have an experimental extension for handling
1874 subpixel hinting; it is off by default and can be activated by setting the
1875 macro `TT_CONFIG_OPTION_SUBPIXEL_HINTING` to value\ 2 or\ 3 at compile time.
1876 This code has been contributed mainly by [Infinality], being a subset of his
1877 original patch. Many GNU/Linux distributions activate this code, or provide
1878 packages to activate it. [Note that starting with FreeType version 2.7 the
1879 Infinality extension is still available but superseded by a less aggressive
1880 subpixel hinting mode, to which the explanations in this section don't
1881 apply.]
1883 This extension changes the behaviour of many bytecode instructions to get
1884 better rendering results. However, not all changes are global; some of them
1885 are specific to certain fonts. For example, it contains font-specific
1886 improvements for the '[DejaVu] Sans' font family. The list of affected
1887 fonts is hard-coded; it can be found in FreeType's source code file
1888 `ttsubpix.c`.
1890 If you are going to process such specially-handled fonts with ttfautohint,
1891 serious rendering problems might show up. Since ttfautohint (intentionally)
1892 doesn't change the font name in the `name` table, the Infinality extension
1893 has no chance to recognize that the hints are different. All such problems
1894 vanish if the font gets renamed in its `name` table (the name of the font
1895 file itself doesn't matter), for example, by using option
1896 [`--family-suffix`](#family-suffix).
1898 ### Incorrect Unicode Character Map
1900 Fonts with an incorrect Unicode `cmap` table will not be properly hinted by
1901 ttfautohint. Especially older fonts do cheat; for example, there exist
1902 Hebrew fonts that map its glyphs to character codes 'A', 'B', etc., to make
1903 them work with non-localized versions of Windows\ 98, say.
1905 Since ttfautohint needs to find both standard and blue zone characters, it
1906 relies on correct Unicode values. If you want to handle such fonts, please
1907 fix their `cmap` tables accordingly before running ttfautohint.
1909 ### Irregular Glyph Heights
1911 The central concept of ttfautohint's hinting algorithm as discussed
1912 [above](#segments-and-edges) is to identify horizontal segments at extremum
1913 positions, especially for blue zones. If such a segment is missing, it
1914 cannot be associated with a blue zone, possibly leading to irregular heights
1915 for the particular glyph.
1917 Normally, a segment has a horizontal length of at least 20\ font units
1918 (assuming 2048 units per EM)^[To be more precise, the sum of the height and
1919 length of a segment must be at least 20 font units, and the height multiplied
1920 by\ 14 must not exceed the length. Thus (19,1) is also a valid minimum
1921 (length,height) pair, while (18,2) isn't. The value\ 20 is heuristic and
1922 hard-coded, as is the value\ 14 (corresponding to a slope of approx.
1923 4.1°).]. Using a [Control Instructions File](#control-instructions-file),
1924 however, it is possible to define additional segments at arbitrary points
1925 that help overcome this restriction, making it possible to fix (most of)
1926 such problems.
1928 ### Diagonals
1930 ttfautohint doesn't handle diagonal lines specially. For thin outlines,
1931 this might lead to strokes that look too thick at smaller sizes. A font
1932 designer might compensate this to a certain amount by slightly reducing the
1933 stroke width of diagonal lines. However, in many cases the sub-optimal
1934 appearance of a stroke with borders that don't exactly fit the pixel grid is
1935 not the outline itself but an incorrect gamma value of the monitor: People
1936 tend to not properly adjust it, and the default values of most operating
1937 systems are too low, causing too much darkening of such strokes. It is thus
1938 of vital importance to compare ttfautohint's results with similar fonts to
1939 exclude any systematic effect not related to the outlines themselves.
1942 Extending ttfautohint with new scripts
1943 --------------------------------------
1945 Right now, adding new scripts to ttfautohint only works on the source code
1946 level, this is, you have to patch the C\ source code.
1948 The process itself isn't very complicated; it is demonstrated best by
1949 example. The following commits in ttfautohint add Ethiopian and Armenian,
1950 respectively.
1952 | [https://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07](https://repo.or.cz/ttfautohint.git/commitdiff/d14c7c07)
1953 | [https://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9](https://repo.or.cz/ttfautohint.git/commitdiff/b5022cd9)
1955 It shows that you have to do the following steps.
1957 * Add blue zone character data to the file `lib/tablue.dat`.
1959 * Add the proper Unicode ranges to `lib/taranges.c`, following the
1960 structure of similar entries.
1962 * Similarly, the files `lib/tastyles.h` and `lib/ttfautohint-script.h`
1963 must be updated. The latter holds the information on the used default
1964 character or characters; it also references the corresponding script tag
1965 `HB_SCRIPT_XXX` as used by the HarfBuzz library.
1967 If there are any questions, please contact the [FreeType mailing
1968 list](https://lists.nongnu.org/mailman/listinfo/freetype) for help. Note
1969 that the script data in ttfautohint are hold in sync with FreeType's
1970 auto-hinter.
1973 Control Instructions
1974 ====================
1976 An entry in a control instructions file has various syntax forms, which are
1977 discussed here. Brackets indicate optional elements.
1980 Common Syntax Elements
1981 ----------------------
1983 *font‑idx* gives the index of the font in a TrueType Collection, starting
1984 with value\ 0. If missing, it is set to zero. For normal TrueType fonts,
1985 only value zero is valid. A font index can be specified in decimal, octal,
1986 or hexadecimal format, the latter two indicated by the prefixes `0` and
1987 `0x`, respectively.
1989 *glyph‑id* is either a glyph's name as listed in the font's `post` SFNT
1990 table or a glyph index. A glyph name consists of characters from the set
1991 '`A-Za-z0-9._`' only and does not start with a digit or period, with the
1992 exceptions of the names '`.notdef`' and '`.null`'. A glyph index starts
1993 with value\ 0 can be specified in decimal, octal, or hexadecimal format, the
1994 latter two indicated by the prefixes `0` and `0x`, respectively. Glyph
1995 names are internally converted to glyph indices.
1997 *points* are number ranges, see '[x Height Snapping
1998 Exceptions](#x-height-snapping-exceptions)' for the syntax.
2000 Similar to the Bourne shell (`sh` or `bash`), a comment starts with
2001 character '`#`'; the rest of the line is ignored. An empty line is ignored
2002 also. Both the newline character and '`;`' can be used as a separator
2003 between exception entries. A trailing '`\`' at the end of a line continues
2004 the current line on the next one.
2006 A control instructions file is parsed line by line; later entries override
2007 earlier entries (in case there is something to override).
2010 Style Adjustments
2011 -----------------
2013 This syntax form makes it possible to override the style assignment
2014 algorithm of ttfautohint; see '[Scripts](#scripts)' and '[OpenType
2015 Features](#opentype-features)' for more details.
2017 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`@`*\ \ glyph-ids
2019 *script* is a four-letter name^[The notable exception is the tag 'lao',
2020 which originally has a trailing space as the fourth character. However,
2021 ttfautohint ignores the space.] of one of the scripts supported by
2022 ttfautohint. *feature* is one of the four-letter names of features
2023 supported by ttfautohint.
2025 The elements of *glyph-ids* are a list of comma separated *glyph-id* values
2026 or value ranges. Note that is not necessary that elements are specified in
2027 increasing order.
2029 Assuming that a font contains superscript digits 'zero.sups' to 'nine.sups'
2030 together with the glyphs 'a.sups' and 'o.sups', use a line
2032 ```
2033 cyrl sups @ zero.sups-nine.sups, a.sups, o.sups
2034 ```
2036 to add those glyphs to the style handling Cyrillic superscript glyphs.
2037 However, it is still necessary that the selected script contains proper
2038 [Blue Zone characters](#blue-zones), otherwise those glyphs aren't handled
2039 at all.
2041 Use the `--debug` command line option to see how ttfautohint assigns glyph
2042 indices of a font to styles.
2045 Stem Width Adjustments
2046 ----------------------
2048 Use the following syntax form to adjust stem width values for a given style,
2049 overriding ttfautohint's algorithm; see '[Scripts](#scripts)' and '[OpenType
2050 Features](#opentype-features)' for more details. This adjustment doesn't
2051 change the glyph shapes; it only influences the hinting process.
2053 > *\[*\ font-idx\ *\]*\ \ script\ \ feature\ \ *`w[idth]`*\ \ stem-widths
2055 *script* and *feature* are the same as with style adjustments; see above.
2056 However, *script* can additionally be the wildcard character '`*`', which
2057 indicates 'any script'. Parameter `width` can be abbreviated as '`w`'.
2059 *stem-widths* is an unsorted list of comma separated integer stem width
2060 values (in font units); the first value gives the style's default stem
2061 width.
2063 The effect of this adjustment depends [on the selected stem width
2064 algorithm](#stem-width-and-positioning-mode). For smooth stem width
2065 positioning, only the first (i.e., the default) value is used; it gets a
2066 higher preference than other discrete stem width choices. For strong stem
2067 width positioning, the stem widths are snapped to the provided values (if
2068 not differing too much) before rounding to an integer pixel value. For
2069 natural stem width positioning, this adjustment is ignored.
2071 A typical example is to reduce the default stem width of an extra-bold font,
2072 which gets better hinted if a stem width of, say, 100 is used instead of the
2073 default value 150. Let's also assume that the font further contains latin
2074 subscript and superscript characters that are hinted best with a stem width
2075 set to 80 font units. We can achieve this with the following lines in a
2076 control instructions file.
2079 ```
2080 * dflt width 100
2081 latb dflt width 80
2082 latp dflt width 80
2083 ```
2085 Without the adjustment chances are very high that the 'eyes' in glyphs 'e'
2086 or 'a' of extra-bold fonts are filled at smaller PPEM values.
2088 Use the `--debug` command line option to see how ttfautohint assigns stem
2089 widths to styles by default.
2092 Glyph Adjustments
2093 -----------------
2095 The following syntax forms allows adjustments of a glyph's hinting process.
2097 ### Change Direction of Points, Artificial Segments
2099 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`l`\[`eft`\]|`r`\[`ight`\]*\ \ points\ \ *\[*\ *`(`*\ left‑offset\ *`,`*\ right‑offset\ *`)`*\ *\]*\
2101 The mutually exclusive parameters `left` and `right` (which can be
2102 abbreviated as '`l`' and '`r`', respectively) indicate that the following
2103 points have left or right 'out' direction, respectively, overriding
2104 ttfautohint's algorithm for setting point directions. The 'out direction'
2105 of a point is the direction of the outline *leaving* the point (or passing
2106 the control point). If the specified direction is identical to what
2107 ttfautohint computes, nothing special happens. Otherwise, a one-point
2108 segment with the specified direction gets created, see
2109 [above](#segments-and-edges). By default, its length is zero. Setting
2110 *left‑offset* and *right‑offset*, you can change the segment's horizontal
2111 start and end position relative to the point position. *left‑offset* and
2112 *right‑offset* are integers measured in font units.
2114 The following five images, displaying glyphs 'O' and 'Q' from the font
2115 [Halant-Regular](https://fonts.google.com/specimen/Halant), demonstrate
2116 how to use direction changes.
2118 
2122 ![The same glyphs, shown at 12px before hinting. [Please ignore the outline
2123 distortion in the upper right of glyph 'O'; this is a bug in FontForge
2124 while running the TrueType
2125 debugger.]](img/Halant-Regular-O-Q-unhinted-12px.png)
2127 
2137 
2147 
2159 ### Unset Direction of Points
2161 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`n`\[`odir`\]*\ \ points\
2163 Parameter `nodir` (or '`n`') sets the 'out' direction of the following
2164 points to 'no direction', this is, neither left nor right. If the specified
2165 direction is identical to what ttfautohint computes, nothing special
2166 happens. Otherwise, ttfautohint no longer considers those points as part of
2167 horizontal segments, thus treating them as ['weak'](#grid-fitting) points.
2169 Modifying or adding segments doesn't directly modify the outlines; it only
2170 influences the hinting process.
2172 ### Delta Exceptions
2174 > *\[*\ font‑idx\ *\]*\ \ glyph‑id\ \ *`t`\[`ouch`\]|`p`\[`oint`\]*\ \ points\ \ *\[*\ *`x`\[`shift`\]*\ x‑shift\ *\]*\ \ *\[*\ *`y`\[`shift`\]*\ y‑shift\ *\]*\ \ *`@`*\ \ ppems\
2176 The mutually exclusive parameters `touch` and `point` (which can be
2177 abbreviated as '`t`' and '`p`', respectively) make ttfautohint apply delta
2178 exceptions for the given points, shifting them by the given values. Delta
2179 exceptions entered with `touch` are applied before the final 'IUP'
2180 (*interpolate untouched points*) instructions in a glyph's bytecode,
2181 exceptions entered with `point` after 'IUP' (please consult Greg Hitchcock's
2182 [ClearType Whitepaper] for more on pre-IUP and post-IUP delta hints).
2183 Additionally, the `touch` parameter makes the bytecode *touch* the affected
2184 points; such points are no longer affected by 'IUP' at all. Note that in
2185 ClearType mode all deltas along the x\ axis are discarded, and deltas along
2186 the y\ axis are only executed for touched points. As a consequence,
2187 vertical delta exceptions entered with `point` should not be used in
2188 ClearType mode.^[Unfortunately, there is a bug in FreeType prior to version
2189 2.5.4 (released in December 2014) that completely disables vertical delta
2190 exceptions if subpixel hinting is activated. For this reason you should
2191 expect that the `touch` parameter fails on older GNU/Linux distributions.]
2193 *ppems*, similar to *points*, are number ranges, see '[x Height Snapping
2194 Exceptions](#x-height-snapping-exceptions)' for the syntax.
2196 *x‑shift* and *y‑shift* represent real numbers that get rounded to multiples
2197 of 1/8 pixels. The entries for `xshift` ('`x`') and `yshift` ('`y`') are
2198 optional; if missing, the corresponding value is set to zero. If both
2199 values are zero, the delta exception entry is ignored as a whole.
2201 Values for *x‑shift* and *y‑shift* must be in the range [−1.0;1.0]. Values
2202 for *ppems* must be in the range [6;53]. Values for *points* are limited by
2203 the number of points in the glyph.
2205 Note that only character '`.`' is recognized as a decimal point, and a
2206 thousands separator is not accepted.
2208 As an example for delta instructions, let's assume that you want to shift
2209 points 2, 3, and\ 4 in glyph 'Aacute' at PPEM sizes 12 and\ 13 by a vertical
2210 amount of 0.25 pixels. This corresponds to the line
2212 ```
2213 Aacute touch 2-4 yshift 0.25 @ 12, 13
2214 ```
2216 in a control instructions file. Since we use `touch` and not `point`,
2217 points 2, 3, and\ 4 are no longer subject to the final 'IUP' instruction,
2218 which interpolates weak, untouched point positions between strong, touched
2219 ones, cf. the description
2220 [here](https://developer.apple.com/fonts/TrueType-Reference-Manual/RM05/Chap5.html#IUP).