Debian Codegraph @

docs/tutorial.rst

raw
1 Tutorial
2 ========
3
4 This document will guide you through installing the ``bdflib`` library,
5 and using it to read, modify and write a font.
6
7 Installation
8 ------------
9
10 For this tutorial,
11 we will install ``bdflib`` in a "virtual environment"
12 so it doesn't interfere with any other Python libraries or applications
13 that might be installed on your system.
14
15 1. Create a virtual environment named ``bdflib-tutorial``:
16
17 .. code-block:: console
18
19 $ python3 -m venv bdflib-tutorial
20
21 2. Install the ``bdflib`` library into the virtual environment:
22
23 .. code-block:: console
24
25 $ bdflib-tutorial/bin/pip install bdflib
26
27 3. Launch Python from the virtual environment:
28
29 .. code-block:: console
30
31 $ bdflib-tutorial/bin/python
32
33 4. Verify that ``bdflib`` is properly installed:
34
35 .. doctest::
36
37 >>> import bdflib
38 >>> bdflib.__version__
39 '2.1.0'
40
41 Reading an existing font
42 ------------------------
43
44 The most basic thing you'll want to do with ``bdflib``
45 is to read in an existing font in the BDF format.
46 For this tutorial,
47 we'll use the following font.
48 Copy and paste it
49 into a text editor and save it as ``tutorial.bdf``,
50 or :download:`download it <tutorial.bdf>`:
51
52 .. literalinclude:: tutorial.bdf
53
54 Reading in a BDF file is really easy:
55
56 >>> from bdflib import reader
57 >>> with open("docs/tutorial.bdf", "rb") as handle:
58 ... font = reader.read_bdf(handle)
59
60 Of course,
61 instead of ``docs/tutorial.bdf``
62 you should use the actual path to your ``tutorial.bdf`` file.
63
64 When you call :func:`.read_bdf`,
65 you get back a :class:`.Font` object
66 which represents the font, its metadata, and all its glyphs.
67 For example, our font has a name and a point-size:
68
69 .. doctest::
70 :pyversion: >= 3.0
71
72 >>> font.name
73 b'Tutorial Font'
74 >>> font.ptSize
75 9
76
77 Our font also has a glyph for lowercase letter "o":
78
79 >>> letter_o = font[ord("o")]
80
81 ``letter_o`` is a :class:`.Glyph` object
82 representing the glyph and its properties.
83
84 .. doctest::
85 :pyversion: >= 3.0
86
87 >>> letter_o.name
88 b'o'
89
90 To help debugging,
91 ``bdflib`` can render a glyph bitmap to a printable string:
92
93 >>> print(letter_o)
94 |###.
95 #...#
96 #...#
97 #...#
98 +###-
99
100 * ``#`` characters represent pixels that are drawn
101 * ``.`` characters represent pixels that are blank
102 * ``-`` and ``|`` represent the X and Y axes
103 (mostly obscured by drawn pixels in the above example)
104 * ``+`` represents the origin where they cross over
105
106 When you draw a glyph at a particular point on-screen,
107 the glyph's origin is put on that exact point.
108 It's usually the bottom-left corner of the glyph,
109 but some glyphs may start above and to the right
110 (like an apostrophe)
111 and some glyphs may start below and to the left
112 (like a lower-case ``j``).
113
114 Adding a glyph
115 --------------
116
117 Once you have a :class:`.Font` object,
118 you can modify it.
119 For example,
120 you can add a new glyph
121 with the :meth:`.new_glyph_from_data` method.
122 Let's add a glyph for U+0302 COMBINING CIRCUMFLEX ACCENT.
123
124 We start by designing our glyph.
125 A circumflex is an angle pointing up,
126 and at the size of our letter "o", it might look like this::
127
128 ..#..
129 .#.#.
130 #...#
131
132 BDF files encode each row of the glyph
133 as a binary number,
134 where a 1 means a drawn pixel and a 0 means no pixel.
135 In Python, that might look like this::
136
137 0b00100
138 0b01010
139 0b10001
140
141 However,
142 BDF uses the traditonal mathematical coordinate system
143 with 0,0 in the bottom left.
144 If we put the above binary numbers in coordinate order,
145 from bottom to top,
146 we get the Python encoding of the bitmap::
147
148 [0b10001, 0b01010, 0b00100]
149
150 Now we can add our new glyph:
151
152 >>> combining_circumflex = font.new_glyph_from_data(
153 ... # Adobe says glyphs not in the Adobe Glyph List and with codepoints
154 ... # below 0xFFFF should be named 'uni' + four hex digits of the
155 ... # codepoint.
156 ... name=b"uni0302",
157 ... # The bitmap we created above.
158 ... data=[0b10001, 0b01010, 0b00100],
159 ... # We don't need to shift this glyph to the left or right.
160 ... bbX=0,
161 ... # Capitals for this font are 9px high, then leave a 1px gap.
162 ... bbY=10,
163 ... # This glyph is 5px wide.
164 ... bbW=5,
165 ... # This glyph is 3px tall.
166 ... bbH=3,
167 ... # 5px wide, 1px gap, so the next character is 6px to the right.
168 ... advance=6,
169 ... # This is character U+0302.
170 ... codepoint=0x0302,
171 ... )
172
173 And now we have our circumflex glyph,
174 ready to combine with anything else
175 without overlapping:
176
177 >>> print(combining_circumflex)
178 |.#..
179 |#.#.
180 #...#
181 |....
182 |....
183 |....
184 |....
185 |....
186 |....
187 |....
188 |....
189 |....
190 +----
191
192 Merging glyphs
193 --------------
194
195 We have a glyph for LATIN SMALL LETTER O,
196 and we have a glyph for COMBINING CIRCUMFLEX ACCENT,
197 but there's also a Unicode character named
198 LATIN SMALL LETTER O WITH CIRCUMFLEX.
199 We could just draw it ourselves from scratch,
200 like we did with COMBINING CIRCUMFLEX ACCENT,
201 but it seems a waste of energy
202 when we already have the component glyphs available.
203 Luckily,
204 the :meth:`.Glyph.merge_glyph()` method
205 makes it easy to, well, merge two existing glyphs together.
206
207 First, we'll need to create the new glyph
208 using the new name and codepoint,
209 but re-using other properties from the base glyph:
210
211 >>> letter_o_with_circumflex = font.new_glyph_from_data(
212 ... name=b"ocircumflex",
213 ... data=letter_o.data,
214 ... bbX=letter_o.bbX,
215 ... bbY=letter_o.bbY,
216 ... bbW=letter_o.bbW,
217 ... bbH=letter_o.bbH,
218 ... advance=letter_o.advance,
219 ... codepoint=0x00F4,
220 ... )
221
222 Next, we'll merge the circumflex glyph on top.
223 Since the circumflex glyph was positioned
224 to sit above nine-pixel-tall capitals
225 but this is a five-pixel-tall lowercase letter,
226 we'll need to move the circumflex down by four pixels:
227
228 >>> letter_o_with_circumflex.merge_glyph(
229 ... other=combining_circumflex,
230 ... atX=0,
231 ... atY=-4,
232 ... )
233
234 The result is a lowercase "o"
235 with a circumflex resting snugly on top!
236
237 >>> print(letter_o_with_circumflex)
238 |.#..
239 |#.#.
240 #...#
241 |....
242 |###.
243 #...#
244 #...#
245 #...#
246 +###-
247
248 If you want to automatically generate
249 as many glyphs as possible
250 from the base and combining glyphs in your font,
251 take a look at the :mod:`.glyph_combining` module.
252
253 Writing a font
254 --------------
255
256 Now that we've customised our font,
257 we can write the result to a new file:
258
259 >>> from bdflib import writer
260 >>> with open("docs/tutorial2.bdf", "wb") as handle:
261 ... writer.write_bdf(font, handle)
262
263 Once again,
264 the path ``docs/tutorial2.bdf``
265 can be whatever path you like.