README.rst
1|Travis Build Status| |PyPI Version| |Codecov| |Gitter Chat|
2
3glyphsLib
4=========
5
6This library provides a bridge from Glyphs source files (.glyphs) to
7UFOs and Designspace files via `defcon <https://github.com/typesupply/defcon/>`__ and `designspaceLib <https://github.com/fonttools/fonttools>`__.
8
9The main methods for conversion are found in ``__init__.py``.
10Intermediate data can be accessed without actually writing UFOs, if
11needed.
12
13Write and return UFOs
14^^^^^^^^^^^^^^^^^^^^^
15
16The following code will write UFOs and a Designspace file to disk.
17
18.. code:: python
19
20 import glyphsLib
21
22 master_dir = 'master_ufos'
23 ufos, designspace_path = glyphsLib.build_masters('MyFont.glyphs', master_dir)
24
25If you want to interpolate instances, please use fontmake instead. It uses this library under the hood when dealing with Glyphs files.
26
27Load UFO objects without writing
28^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
29
30.. code:: python
31
32 import glyphsLib
33
34 ufos = glyphsLib.load_to_ufos('MyFont.glyphs')
35
36Read and write Glyphs data as Python objects
37^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
38
39.. code:: python
40
41 from glyphsLib import GSFont
42
43 font = GSFont(glyphs_file)
44 font.save(glyphs_file)
45
46The ``glyphsLib.classes`` module aims to provide an interface similar to
47Glyphs.app's `Python Scripting API <https://docu.glyphsapp.com>`__.
48
49Note that currently not all the classes and methods may be fully
50implemented. We try to keep up to date, but if you find something that
51is missing or does not work as expected, please open a issue.
52
53.. TODO Briefly state how much of the Glyphs.app API is currently covered,
54 and what is not supported yet.
55
56Go back and forth between UFOs and Glyphs
57^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
58
591. You can use the ``ufo2glyphs`` and ``glyphs2ufo`` command line scripts to
60 round-trip your source files. By default, the scripts try to preserve as
61 much metadata as possible.
62
63 .. code::
64
65 # Generate master UFOs and Designspace file
66 glyphs2ufo Example.glyphs
67
68 # Go back
69 ufo2glyphs Example.designspace
70
71 # You can also combine single UFOs into a Glyphs source file.
72 ufo2glyphs Example-Regular.ufo Example-Bold.ufo
73
742. Without a designspace file, using for example the
75 `Inria fonts by Black[Foundry] <https://github.com/BlackFoundry/InriaFonts/tree/master/masters/INRIA-SANS>`__:
76
77 .. code:: python
78
79 import glob
80 from defcon import Font
81 from glyphsLib import to_glyphs
82
83 ufos = [Font(path) for path in glob.glob('*Italic.ufo')]
84 # Sort the UFOs because glyphsLib will create masters in the same order
85 ufos = sorted(ufos, key=lambda ufo: ufo.info.openTypeOS2WeightClass)
86 font = to_glyphs(ufos)
87 font.save('InriaSansItalic.glyphs')
88
89 `Here is the resulting glyphs file <https://gist.githubusercontent.com/belluzj/cc3d43bf9b1cf22fde7fd4d2b97fdac4/raw/3222a2bfcf6554aa56a21b80f8fba82f1c5d7444/InriaSansItalic.glyphs>`__
90
913. With a designspace, using
92 `Spectral from Production Type <https://github.com/productiontype/Spectral/tree/master/sources>`__:
93
94 .. code:: python
95
96 import glob
97 from fontTools.designspaceLib import DesignSpaceDocument
98 from glyphsLib import to_glyphs
99
100 doc = DesignSpaceDocument()
101 doc.read('spectral-build-roman.designspace')
102 font = to_glyphs(doc)
103 font.save('SpectralRoman.glyphs')
104
105 `Here is the resulting glyphs file <https://gist.githubusercontent.com/belluzj/cc3d43bf9b1cf22fde7fd4d2b97fdac4/raw/3222a2bfcf6554aa56a21b80f8fba82f1c5d7444/SpectralRoman.glyphs>`__
106
1074. In both programmatic cases, if you intend to go back to UFOs after modifying
108 the file with Glyphs, you should use the ``minimize_ufo_diffs`` parameter to
109 minimize the amount of diffs that will show up in git after the back and
110 forth. To do so, the glyphsLib will add some bookkeeping values in various
111 ``userData`` fields. For example, it will try to remember which GSClass came
112 from groups.plist or from the feature file.
113
114The same option exists for people who want to do Glyphs->UFOs->Glyphs:
115``minimize_glyphs_diffs``, which will add some bookkeeping data in UFO ``lib``.
116For example, it will keep the same UUIDs for Glyphs layers, and so will need
117to store those layer UUIDs in the UFOs.
118
119.. code:: python
120
121 import glob
122 import os
123 from fontTools.designspaceLib import DesignSpaceDocument
124 from glyphsLib import to_glyphs, to_designspace, GSFont
125
126 doc = DesignSpaceDocument()
127 doc.read('spectral-build-roman.designspace')
128 font = to_glyphs(doc, minimize_ufo_diffs=True)
129 doc2 = to_designspace(font, propagate_anchors=False)
130 # UFOs are in memory only, attached to the doc via `sources`
131 # Writing doc2 over the original doc should generate very few git diffs (ideally none)
132 doc2.write(doc.path)
133 for source in doc2.sources:
134 path = os.path.join(os.path.dirname(doc.path), source.filename)
135 # You will want to use ufoNormalizer after
136 source.font.save(path)
137
138 font = GSFont('SpectralRoman.glyphs')
139 doc = to_designspace(font, minimize_glyphs_diffs=True, propagate_anchors=False)
140 font2 = to_glyphs(doc)
141 # Writing font2 over font should generate very few git diffs (ideally none):
142 font2.save(font.filepath)
143
144In practice there are always a few diffs on things that don't really make a
145difference, like optional things being added/removed or whitespace changes or
146things getting reordered...
147
148.. |Travis Build Status| image:: https://travis-ci.org/googlei18n/glyphsLib.svg
149 :target: https://travis-ci.org/googlei18n/glyphsLib
150.. |PyPI Version| image:: https://img.shields.io/pypi/v/glyphsLib.svg
151 :target: https://pypi.org/project/glyphsLib/
152.. |Codecov| image:: https://codecov.io/gh/googlei18n/glyphsLib/branch/master/graph/badge.svg
153 :target: https://codecov.io/gh/googlei18n/glyphsLib
154.. |Gitter Chat| image:: https://badges.gitter.im/fonttools-dev/glyphsLib.svg
155 :alt: Join the chat at https://gitter.im/fonttools-dev/glyphsLib
156 :target: https://gitter.im/fonttools-dev/glyphsLib?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
157