| 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. |