A font library and writer for small OLED and LCD displays using the framebuffer

[easytarget]

This is something that came out of a couple of projects I am working on; both need to display simple status and value information on small monochrome displays.

I struggled to find a simple way to do 'big' fonts on their small displays; most of the alternatives are either too complex (LVGL) or specialised, eg; 'here are the 3 fonts + hacked driver I made for my project'.

I missed having something like the u8g2 font+driver system that I've used for arduino/C projects. @peterhinch 's writer class comes closest, but still left me having to source and convert fonts.

So, I used Peters excellent work as a basis and created my own font library, and a simple writer class to use them.

Proudly Presenting:

https://github.com/easytarget/microPyEZfonts

There are 90'ish font/size combinations from 5px to 64px height, the selection includes helvetica, times, courier and new century. Plus a number of other appropriate fonts such as spleen, tom-thumb, u8g2 native, plus some symbol, battery and 7-segment fonts. Each comes in 3 flavors; 'all', 'ascii' and 'numeric' to help with memory considerations.

All these can be used with Peters writer class and his nano-gui.

There is also a simplified font writer class that supports any framebuffer compatible display:

• The font file you want to use needs to be imported, and the ezFBfont class initialised against it.
• You can set default colors (including transparency), horizontal alignment (left, center, right) and vertical alignment (top, center, bottom and baseline) at init, and also change them on the fly.
• You write to the screen with font.write(str,x,y) , and optionally provide the same color and alignment arguments as above.
• Multiple lines are supported, and the horizontal alignment also works as justification
• There is a font.rect() method that takes the same arguments as write() and returns x,y,w,h values that can be passed to the framebuffer.rect() method to clean the written text.

That's pretty much it; There is a veritable TL;DR of documentation in the repo, with working examples etc.

[peterhinch]

I trust you've checked the legal status of these fonts. The reason my repo includes a minimal selection of Python fonts is that I wanted to be sure that the source ttf files were copyright free. A prime reason for writing the CPython converter was to ensure that users were responsible for checking copyright on any fonts they used.

As a general point I think it would help users to clarify the differences - and the commonality - between our approaches.

Benefits of PyEZfonts:

• Transparency support.
• Improved vertical alignment support (arguably a weakness in my implementation).
• Fonts are pre-converted.

Functionality provided by different means:

• The functionality of font.rect is provided in the GUI Label class. This ensures that old text is cleared before updating and allows dynamic color changes.
• Multi-line support (with scrolling) is provided by the textbox class.

Benefits of font-to-py:

• Generality: any font in one of the four industry standard formats may be converted. Large fonts with a restricted character set (e.g. for clock displays) may be created; also other character sets such as Cyrillic. Support for sparse fonts.
• Hopefully no legal risk :)

I think it's also worth stating that, because your fonts were created with font-to-py, they are compatible with nano-gui, micropython-touch and micro-gui.

[easytarget]

That's a good explanation of the differences, thank you.

Another advantage of your tools is that they give you control over padding, and do reverse fonts.

Copyright got some serious consideration, this isn't my first time in this swamp.. The fonts here are safe to redistribute.

• Specifically; they are all sourced (as .bdf's) from the u8g2 project. This means that I started from a curated list of redistributable and open fonts.
• I then select a subset of font families from that list. Each one of these was manually reviewed by me to double-check the terms. Including searching out and going to the upstream source when needed.
• My converter script preserves all comments and copyright strings from the source in the resulting .py font files.

The only fonts that were not specifically created and released as open source are the X11 ones. Those are freely redistributable so long as the copyright notice is preserved, but not properly open (as evidenced by their history with XOrg & XFree). They are, however, very useful and so are included here.

Thinking about this it is a very good idea for me to:

• Add the above notes on provenance (fleshed out) to the documentation in the fonts part of the repo.
• Add the X11/digital licence to my main Licence page (following the example from the u8g2 licence page).

[bdbarnett]

Hello,

Just wanted to give you a heads up that I have included PyEZfonts in MPDisplay. I see you have linked to MPDisplay and I appreciate that very much. I chose to include your font class because:

1. it doesn't use anything MicroPython specific, like viper, so it can run on CPython and CircuitPython
2. it allows transparent backgrounds
3. it uses @peterhinch's font converter and is based on his work, which I admire

I had to subclass it as EZFont to make _put_char able to write using the .pixel() method as opposed to writing directly into bytearray or memoryview because one the targets I write to is the display driver itself, which ISN'T subclassed from framebuffer. That gives it the ability to write to any object with ,height and ,width attributes and a .pixel() method, not just framebuffers.

I need to make it return an Area object like the rest of the drawing primitives in MPDisplay. That return object may be used by the end-user to update smaller regions of the diplay instead of the whole thing.

Great work!

[peterhinch]

The key to measuring RAM use is always to do gc.collect() before executing gc.mem_free().

Re RAM, RP2040 is relatively well-endowed. Some platforms are restricted - ESP8266 has about 35KiB, some have even less.

[easytarget]

Being reminded to run gc.collect() is good, but I mostly needed to read the docs on memory use and building firmware.

But first I needed to finish off the main part of this; a marquee class and a proper write-up with examples of the unicode font generation process without sidetracking too badly. Sorry for the delay.

I wasn't clear in the post above; the glyph data is stored as a bytes object in a dictionary and a memoryview object returned to that.

I just completed testing with my fonts frozen in firmware and the results are excellent. You do get the mutable dictionary object on the heap, but as far as I can tell it contains references to the frozen bytes objects, and they are not held in RAM.

I have a esp8266 test rig; and can build the firmware for this. When I put the full 64x64 openiconic font pack in as a frozen module it only takes 2.2K on import. This is an extreme example, at 455K for the raw .py file, and 177K for the frozen_mpy version, it far exceeds the available ram. Yet it works perfectly.

I think the real factor here is how many chars are in the set (and hence, how many entries in the dict), the above set has 223 chars, a more normal ascii charset uses proportionally less memory on import. The WxH size of the font makes no difference.

[peterhinch]

Thanks for testing - that is an interesting result. It seems my approach was over cautious in designing my own indexing scheme.

[easytarget]

Ok; I wrote my testing up;
https://github.com/easytarget/microPyEZfonts/blob/main/examples/memory-test/import_test.md

Interesting results; clearly show how efficient your binary packed fonts are when frozen and when uploaded to the filesystem.

But I'm also pleased that the dictionary based approach works as well as it does 😄 . When frozen the size on import is still relatively small, and directly related to the number of characters in the module, And when uploaded to the device filesystem they are typically using 50% more RAM than the equivalent binary fonts. Quite acceptable for my intended usage scenarios.

[peterhinch]

Your results for freezing my font files accord with my tests (~400 bytes per font, regardless of dimensions or number of glyphs). The results using a dict make sense: the size grows with the number of keys, but crucially the glyph data is not copied to RAM.

Useful and informative results!