1|Travis Build Status| |Appveyor Build status| |Coverage Status| |PyPI| |Gitter Chat| 2 3What is this? 4~~~~~~~~~~~~~ 5 6| fontTools is a library for manipulating fonts, written in Python. The 7 project includes the TTX tool, that can convert TrueType and OpenType 8 fonts to and from an XML text format, which is also called TTX. It 9 supports TrueType, OpenType, AFM and to an extent Type 1 and some 10 Mac-specific formats. The project has an `MIT open-source 11 licence <LICENSE>`__. 12| Among other things this means you can use it free of charge. 13 14Installation 15~~~~~~~~~~~~ 16 17FontTools requires `Python <http://www.python.org/download/>`__ 2.7, 3.4 18or later. 19 20**NOTE** After January 1 2019, until no later than June 30 2019, the support 21for *Python 2.7* will be limited to only bug fixes, and no new features will 22be added to the ``py27`` branch. The upcoming FontTools 4.x series will require 23*Python 3.5* or above. You can read more `here <https://python3statement.org>`__ 24and `here <https://github.com/fonttools/fonttools/issues/765>`__ for the 25reasons behind this decision. 26 27The package is listed in the Python Package Index (PyPI), so you can 28install it with `pip <https://pip.pypa.io>`__: 29 30.. code:: sh 31 32 pip install fonttools 33 34If you would like to contribute to its development, you can clone the 35repository from GitHub, install the package in 'editable' mode and 36modify the source code in place. We recommend creating a virtual 37environment, using `virtualenv <https://virtualenv.pypa.io>`__ or 38Python 3 `venv <https://docs.python.org/3/library/venv.html>`__ module. 39 40.. code:: sh 41 42 # download the source code to 'fonttools' folder 43 git clone https://github.com/fonttools/fonttools.git 44 cd fonttools 45 46 # create new virtual environment called e.g. 'fonttools-venv', or anything you like 47 python -m virtualenv fonttools-venv 48 49 # source the `activate` shell script to enter the environment (Un*x); to exit, just type `deactivate` 50 . fonttools-venv/bin/activate 51 52 # to activate the virtual environment in Windows `cmd.exe`, do 53 fonttools-venv\Scripts\activate.bat 54 55 # install in 'editable' mode 56 pip install -e . 57 58TTX – From OpenType and TrueType to XML and Back 59~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60 61Once installed you can use the ``ttx`` command to convert binary font 62files (``.otf``, ``.ttf``, etc) to the TTX XML format, edit them, and 63convert them back to binary format. TTX files have a .ttx file 64extension. 65 66.. code:: sh 67 68 ttx /path/to/font.otf 69 ttx /path/to/font.ttx 70 71The TTX application can be used in two ways, depending on what 72platform you run it on: 73 74- As a command line tool (Windows/DOS, Unix, macOS) 75- By dropping files onto the application (Windows, macOS) 76 77TTX detects what kind of files it is fed: it will output a ``.ttx`` file 78when it sees a ``.ttf`` or ``.otf``, and it will compile a ``.ttf`` or 79``.otf`` when the input file is a ``.ttx`` file. By default, the output 80file is created in the same folder as the input file, and will have the 81same name as the input file but with a different extension. TTX will 82*never* overwrite existing files, but if necessary will append a unique 83number to the output filename (before the extension) such as 84``Arial#1.ttf`` 85 86When using TTX from the command line there are a bunch of extra options. 87These are explained in the help text, as displayed when typing 88``ttx -h`` at the command prompt. These additional options include: 89 90- specifying the folder where the output files are created 91- specifying which tables to dump or which tables to exclude 92- merging partial ``.ttx`` files with existing ``.ttf`` or ``.otf`` 93 files 94- listing brief table info instead of dumping to ``.ttx`` 95- splitting tables to separate ``.ttx`` files 96- disabling TrueType instruction disassembly 97 98The TTX file format 99------------------- 100 101The following tables are currently supported: 102 103.. begin table list 104.. code:: 105 106 BASE, CBDT, CBLC, CFF, CFF2, COLR, CPAL, DSIG, EBDT, EBLC, FFTM, 107 Feat, GDEF, GMAP, GPKG, GPOS, GSUB, Glat, Gloc, HVAR, JSTF, LTSH, 108 MATH, META, MVAR, OS/2, SING, STAT, SVG, Silf, Sill, TSI0, TSI1, 109 TSI2, TSI3, TSI5, TSIB, TSID, TSIJ, TSIP, TSIS, TSIV, TTFA, VDMX, 110 VORG, VVAR, ankr, avar, bsln, cidg, cmap, cvar, cvt, feat, fpgm, 111 fvar, gasp, gcid, glyf, gvar, hdmx, head, hhea, hmtx, kern, lcar, 112 loca, ltag, maxp, meta, mort, morx, name, opbd, post, prep, prop, 113 sbix, trak, vhea and vmtx 114.. end table list 115 116Other tables are dumped as hexadecimal data. 117 118TrueType fonts use glyph indices (GlyphIDs) to refer to glyphs in most 119places. While this is fine in binary form, it is really hard to work 120with for humans. Therefore we use names instead. 121 122The glyph names are either extracted from the ``CFF`` table or the 123``post`` table, or are derived from a Unicode ``cmap`` table. In the 124latter case the Adobe Glyph List is used to calculate names based on 125Unicode values. If all of these methods fail, names are invented based 126on GlyphID (eg ``glyph00142``) 127 128It is possible that different glyphs use the same name. If this happens, 129we force the names to be unique by appending ``#n`` to the name (``n`` 130being an integer number.) The original names are being kept, so this has 131no influence on a "round tripped" font. 132 133Because the order in which glyphs are stored inside the binary font is 134important, we maintain an ordered list of glyph names in the font. 135 136Other Tools 137~~~~~~~~~~~ 138 139Commands for merging and subsetting fonts are also available: 140 141.. code:: sh 142 143 pyftmerge 144 pyftsubset 145 146fontTools Python Module 147~~~~~~~~~~~~~~~~~~~~~~~ 148 149The fontTools Python module provides a convenient way to 150programmatically edit font files. 151 152.. code:: py 153 154 >>> from fontTools.ttLib import TTFont 155 >>> font = TTFont('/path/to/font.ttf') 156 >>> font 157 <fontTools.ttLib.TTFont object at 0x10c34ed50> 158 >>> 159 160A selection of sample Python programs is in the 161`Snippets <https://github.com/fonttools/fonttools/blob/master/Snippets/>`__ 162directory. 163 164Optional Requirements 165--------------------- 166 167The ``fontTools`` package currently has no (required) external dependencies 168besides the modules included in the Python Standard Library. 169However, a few extra dependencies are required by some of its modules, which 170are needed to unlock optional features. 171The ``fonttools`` PyPI distribution also supports so-called "extras", i.e. a 172set of keywords that describe a group of additional dependencies, which can be 173used when installing via pip, or when specifying a requirement. 174For example: 175 176.. code:: sh 177 178 pip install fonttools[ufo,lxml,woff,unicode] 179 180This command will install fonttools, as well as the optional dependencies that 181are required to unlock the extra features named "ufo", etc. 182 183- ``Lib/fontTools/misc/etree.py`` 184 185 The module exports a ElementTree-like API for reading/writing XML files, and 186 allows to use as the backend either the built-in ``xml.etree`` module or 187 `lxml <https://http://lxml.de>`__. The latter is preferred whenever present, 188 as it is generally faster and more secure. 189 190 *Extra:* ``lxml`` 191 192- ``Lib/fontTools/ufoLib`` 193 194 Package for reading and writing UFO source files; it requires: 195 196 * `fs <https://pypi.org/pypi/fs>`__: (aka ``pyfilesystem2``) filesystem 197 abstraction layer. 198 199 * `enum34 <https://pypi.org/pypi/enum34>`__: backport for the built-in ``enum`` 200 module (only required on Python < 3.4). 201 202 *Extra:* ``ufo`` 203 204- ``Lib/fontTools/ttLib/woff2.py`` 205 206 Module to compress/decompress WOFF 2.0 web fonts; it requires: 207 208 * `brotli <https://pypi.python.org/pypi/Brotli>`__: Python bindings of 209 the Brotli compression library. 210 211 *Extra:* ``woff`` 212 213- ``Lib/fontTools/ttLib/sfnt.py`` 214 215 To better compress WOFF 1.0 web fonts, the following module can be used 216 instead of the built-in ``zlib`` library: 217 218 * `zopfli <https://pypi.python.org/pypi/zopfli>`__: Python bindings of 219 the Zopfli compression library. 220 221 *Extra:* ``woff`` 222 223- ``Lib/fontTools/unicode.py`` 224 225 To display the Unicode character names when dumping the ``cmap`` table 226 with ``ttx`` we use the ``unicodedata`` module in the Standard Library. 227 The version included in there varies between different Python versions. 228 To use the latest available data, you can install: 229 230 * `unicodedata2 <https://pypi.python.org/pypi/unicodedata2>`__: 231 ``unicodedata`` backport for Python 2.7 and 3.5 updated to the latest 232 Unicode version 9.0. Note this is not necessary if you use Python 3.6 233 as the latter already comes with an up-to-date ``unicodedata``. 234 235 *Extra:* ``unicode`` 236 237- ``Lib/fontTools/varLib/interpolatable.py`` 238 239 Module for finding wrong contour/component order between different masters. 240 It requires one of the following packages in order to solve the so-called 241 "minimum weight perfect matching problem in bipartite graphs", or 242 the Assignment problem: 243 244 * `scipy <https://pypi.python.org/pypi/scipy>`__: the Scientific Library 245 for Python, which internally uses `NumPy <https://pypi.python.org/pypi/numpy>`__ 246 arrays and hence is very fast; 247 * `munkres <https://pypi.python.org/pypi/munkres>`__: a pure-Python 248 module that implements the Hungarian or Kuhn-Munkres algorithm. 249 250 *Extra:* ``interpolatable`` 251 252- ``Lib/fontTools/varLib/plot.py`` 253 254 Module for visualizing DesignSpaceDocument and resulting VariationModel. 255 256 * `matplotlib <https://pypi.org/pypi/matplotlib>`__: 2D plotting library. 257 258 *Extra:* ``plot`` 259 260- ``Lib/fontTools/misc/symfont.py`` 261 262 Advanced module for symbolic font statistics analysis; it requires: 263 264 * `sympy <https://pypi.python.org/pypi/sympy>`__: the Python library for 265 symbolic mathematics. 266 267 *Extra:* ``symfont`` 268 269- ``Lib/fontTools/t1Lib.py`` 270 271 To get the file creator and type of Macintosh PostScript Type 1 fonts 272 on Python 3 you need to install the following module, as the old ``MacOS`` 273 module is no longer included in Mac Python: 274 275 * `xattr <https://pypi.python.org/pypi/xattr>`__: Python wrapper for 276 extended filesystem attributes (macOS platform only). 277 278 *Extra:* ``type1`` 279 280- ``Lib/fontTools/pens/cocoaPen.py`` 281 282 Pen for drawing glyphs with Cocoa ``NSBezierPath``, requires: 283 284 * `PyObjC <https://pypi.python.org/pypi/pyobjc>`__: the bridge between 285 Python and the Objective-C runtime (macOS platform only). 286 287- ``Lib/fontTools/pens/qtPen.py`` 288 289 Pen for drawing glyphs with Qt's ``QPainterPath``, requires: 290 291 * `PyQt5 <https://pypi.python.org/pypi/PyQt5>`__: Python bindings for 292 the Qt cross platform UI and application toolkit. 293 294- ``Lib/fontTools/pens/reportLabPen.py`` 295 296 Pen to drawing glyphs as PNG images, requires: 297 298 * `reportlab <https://pypi.python.org/pypi/reportlab>`__: Python toolkit 299 for generating PDFs and graphics. 300 301Testing 302~~~~~~~ 303 304To run the test suite, you need to install `pytest <http://docs.pytest.org/en/latest/>`__. 305When you run the ``pytest`` command, the tests will run against the 306installed ``fontTools`` package, or the first one found in the 307``PYTHONPATH``. 308 309You can also use `tox <https://tox.readthedocs.io/en/latest/>`__ to 310automatically run tests on different Python versions in isolated virtual 311environments. 312 313.. code:: sh 314 315 pip install tox 316 tox 317 318Note that when you run ``tox`` without arguments, the tests are executed 319for all the environments listed in tox.ini's ``envlist``. In our case, 320this includes Python 2.7 and 3.7, so for this to work the ``python2.7`` 321and ``python3.7`` executables must be available in your ``PATH``. 322 323You can specify an alternative environment list via the ``-e`` option, 324or the ``TOXENV`` environment variable: 325 326.. code:: sh 327 328 tox -e py27 329 TOXENV="py36-cov,htmlcov" tox 330 331Development Community 332~~~~~~~~~~~~~~~~~~~~~ 333 334TTX/FontTools development is ongoing in an active community of 335developers, that includes professional developers employed at major 336software corporations and type foundries as well as hobbyists. 337 338Feature requests and bug reports are always welcome at 339https://github.com/fonttools/fonttools/issues/ 340 341The best place for discussions about TTX from an end-user perspective as 342well as TTX/FontTools development is the 343https://groups.google.com/d/forum/fonttools mailing list. There is also 344a development https://groups.google.com/d/forum/fonttools-dev mailing 345list for continuous integration notifications. You can also email Behdad 346privately at behdad@behdad.org 347 348History 349~~~~~~~ 350 351The fontTools project was started by Just van Rossum in 1999, and was 352maintained as an open source project at 353http://sourceforge.net/projects/fonttools/. In 2008, Paul Wise (pabs3) 354began helping Just with stability maintenance. In 2013 Behdad Esfahbod 355began a friendly fork, thoroughly reviewing the codebase and making 356changes at https://github.com/behdad/fonttools to add new features and 357support for new font formats. 358 359Acknowledgements 360~~~~~~~~~~~~~~~~ 361 362In alphabetical order: 363 364Olivier Berten, Samyak Bhuta, Erik van Blokland, Petr van Blokland, 365Jelle Bosma, Sascha Brawer, Tom Byrer, Frédéric Coiffier, Vincent 366Connare, Dave Crossland, Simon Daniels, Behdad Esfahbod, Behnam 367Esfahbod, Hannes Famira, Sam Fishman, Matt Fontaine, Yannis Haralambous, 368Greg Hitchcock, Jeremie Hornus, Khaled Hosny, John Hudson, Denis Moyogo 369Jacquerye, Jack Jansen, Tom Kacvinsky, Jens Kutilek, Antoine Leca, 370Werner Lemberg, Tal Leming, Peter Lofting, Cosimo Lupo, Masaya Nakamura, 371Dave Opstad, Laurence Penney, Roozbeh Pournader, Garret Rieger, Read 372Roberts, Guido van Rossum, Just van Rossum, Andreas Seidel, Georg 373Seifert, Miguel Sousa, Adam Twardoch, Adrien Tétar, Vitaly Volkov, Paul 374Wise. 375 376Copyrights 377~~~~~~~~~~ 378 379| Copyright (c) 1999-2004 Just van Rossum, LettError 380 (just@letterror.com) 381| See `LICENSE <LICENSE>`__ for the full license. 382 383Copyright (c) 2000 BeOpen.com. All Rights Reserved. 384 385Copyright (c) 1995-2001 Corporation for National Research Initiatives. 386All Rights Reserved. 387 388Copyright (c) 1991-1995 Stichting Mathematisch Centrum, Amsterdam. All 389Rights Reserved. 390 391Have fun! 392 393.. |Travis Build Status| image:: https://travis-ci.org/fonttools/fonttools.svg 394 :target: https://travis-ci.org/fonttools/fonttools 395.. |Appveyor Build status| image:: https://ci.appveyor.com/api/projects/status/0f7fmee9as744sl7/branch/master?svg=true 396 :target: https://ci.appveyor.com/project/fonttools/fonttools/branch/master 397.. |Coverage Status| image:: https://codecov.io/gh/fonttools/fonttools/branch/master/graph/badge.svg 398 :target: https://codecov.io/gh/fonttools/fonttools 399.. |PyPI| image:: https://img.shields.io/pypi/v/fonttools.svg 400 :target: https://pypi.org/project/FontTools 401.. |Gitter Chat| image:: https://badges.gitter.im/fonttools-dev/Lobby.svg 402 :alt: Join the chat at https://gitter.im/fonttools-dev/Lobby 403 :target: https://gitter.im/fonttools-dev/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge 404
