{"id":13802129,"url":"https://github.com/peterhinch/micropython-font-to-py","last_synced_at":"2025-04-08T09:06:53.498Z","repository":{"id":43620153,"uuid":"71622179","full_name":"peterhinch/micropython-font-to-py","owner":"peterhinch","description":"A Python 3 utility to convert fonts to Python source capable of being frozen as bytecode","archived":false,"fork":false,"pushed_at":"2025-02-09T09:53:03.000Z","size":389,"stargazers_count":414,"open_issues_count":8,"forks_count":73,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-01T07:48:49.948Z","etag":null,"topics":["fonts","micropython","python-3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peterhinch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-22T06:50:27.000Z","updated_at":"2025-03-17T19:35:07.000Z","dependencies_parsed_at":"2024-03-28T12:49:54.684Z","dependency_job_id":"cd4a319e-a634-4541-b06f-763b887e3ce5","html_url":"https://github.com/peterhinch/micropython-font-to-py","commit_stats":{"total_commits":130,"total_committers":5,"mean_commits":26.0,"dds":"0.038461538461538436","last_synced_commit":"01949e4cdfef929c12a1bf2caf2e3219d79a0aa7"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-font-to-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-font-to-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-font-to-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterhinch%2Fmicropython-font-to-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peterhinch","download_url":"https://codeload.github.com/peterhinch/micropython-font-to-py/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247809964,"owners_count":20999816,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fonts","micropython","python-3"],"created_at":"2024-08-04T00:01:36.808Z","updated_at":"2025-04-08T09:06:53.477Z","avatar_url":"https://github.com/peterhinch.png","language":"Python","funding_links":[],"categories":["Libraries","Python"],"sub_categories":["Display"],"readme":"# MicroPython font handling\n\nThis repository defines a method of creating and deploying fonts for use with\nMicroPython display drivers. A PC utility renders industry standard font files\nas a bitmap in the form of Python sourcecode. A MicroPython module enables such\nfiles to be displayed on devices with suitable device drivers. These include\nOLED displays using the SSD1306 chip and the official device driver. Compatible\ndrivers for a variety of display technologies are available as part of the\n[nano-gui repository](https://github.com/peterhinch/micropython-nano-gui).\n\n# 1. Introduction\n\nMicroPython platforms generally have limited RAM, but more abundant storage in\nthe form of flash memory. Font files tend to be relatively large. The\nconventional technique of rendering strings to a device involves loading the\nentire font into RAM. This is fast but RAM intensive. The alternative of storing\nthe font as a random access file and loading individual glyphs into RAM on\ndemand is too slow for reasonable performance on most display devices.\n\nThis alternative implements a font as a Python source file, with the data being\ndeclared as `bytes` objects. Such a file may be frozen as bytecode: this\ninvolves building the firmware from source with the Python file in a specific\ndirectory. On import very little RAM is used, yet the data may be accessed\nfast. Note that the use of frozen bytecode is entirely optional: font files may\nbe imported in the normal way if RAM usage is not an issue.\n\nThe resultant file is usable with two varieties of display device drivers:\n\n 1. Drivers where the display class is subclassed from the official\n `framebuffer` class.\n 2. Drivers for displays where the frame buffer is implemented in the display\n device hardware.\n\n# 2. Solution\n\nThis comprises four components, links to docs below:\n\n 1. [font_to_py.py](./FONT_TO_PY.md) This utility runs on a PC and converts an\n industry standard font file to Python source. See below.\n 2. [Writer and CWriter classes](./writer/WRITER.md) These facilitate rendering\n text to a monochrome or colour display having a suitable device driver.\n 3. [Creating icon fonts](./icon_fonts/README.md) Ways to incorporate icons in\n a Python font file.\n 4. [Device driver notes](./writer/DRIVERS.md). Notes for authors of display\n device drivers. Provides details of the font file format and information on\n ensuring compatibility with the `Writer` classes.\n\n# 3. font_to_py.py\n\nThis command line utility is written in Python 3 and runs on a PC. To convert\na scalable font to Python the utility takes input a font file in `ttf` or `otf`\nform together with a height in pixels and outputs a Python source file\ncontaining the font as a bitmap. Fixed and variable pitch rendering are\nsupported. The design has the following aims:\n\n * Independence of specific display hardware.\n * The path from font file to Python code to be fully open source.\n\nThe first is achieved by supplying hardware specific arguments to the utility.\nThese define horizontal or vertical mapping and the bit order for font data.\n\nThe second is achieved by using Freetype and the Freetype Python bindings. Its\nuse is documented [here](./FONT_TO_PY.md). This also details measurements of\nRAM usage when importing fonts stored as frozen bytecode.\n\n## 3.1 Small fonts\n\nConverting scalable `ttf` or `otf` files programmatically works best for larger\nfonts. For small fonts it is best to use hand-designed bitmapped font files.\nThese are now supported: `bdf` or `pcf` font files may be converted to Python\nsource in the same format as files originating from scalable fonts. See also\n[microPyEZfonts](https://github.com/easytarget/microPyEZfonts) which includes\ncompatible small fonts (in `examples/fonts`).\n\n## 3.2 Limitations\n\nKerning is not supported. Fonts are one bit per pixel. Colour displays are\nsupported by the `CWriter` class which adds colour information at the rendering\nstage. This assumes that all pixels of a character are coloured identically.\n\nBy default the `font_to_py.py` utility produces the ASCII character set from\n`chr(32)` to `chr(126)` inclusive. Command line options enable the character\nset to be modified to include arbitrary Unicode characters. Alternative sets\nmay be specified such as for non-English languages. Efficient support is now\nprovided for sparse character sets.\n\n# 4. Font file interface\n\nA font file is imported in the usual way e.g. `import font14`. Python font\nfiles contain the following functions. These return values defined by the\narguments which were provided to `font_to_py.py`:\n\n`height` Returns height in pixels.  \n`max_width` Returns maximum width of a glyph in pixels.  \n`baseline` Offset from top of glyph to the baseline.  \n`hmap` Returns `True` if font is horizontally mapped.  \n`reverse` Returns `True` if bit reversal was specified.  \n`monospaced` Returns `True` if monospaced rendering was specified.  \n`min_ch` Returns the ordinal value of the lowest character in the file.  \n`max_ch` Returns the ordinal value of the highest character in the file.\n\nGlyphs are returned with the `get_ch` function. Its argument is a Unicode\ncharacter and it returns the following values:\n\n * A `memoryview` object containing the glyph bytes.\n * The height in pixels.\n * The character width in pixels.\n\nThe `font_to_py.py` utility allows a default glyph to be specified (typically\n`?`). If called with an undefined character, this glyph will be returned.\n\nThe `min_ch` and `max_ch` functions are mainly relevant to contiguous character\nsets.\n\n# 5. Licence\n\nAll code is released under the MIT licence.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterhinch%2Fmicropython-font-to-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterhinch%2Fmicropython-font-to-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterhinch%2Fmicropython-font-to-py/lists"}