BlackFoundryCom / black-renderer

Apache License 2.0
33 stars 7 forks source link

Python package

BlackRenderer

BlackRenderer is a Python-based renderer for OpenType COLR fonts, with multiple backends. It supports the new COLRv1 format as well as the old COLR format. It fully supports variable fonts, including variable COLRv1 data.

Big Smiley Face Icon

Features

Tool usage example

BlackRenderer comes with an hb-view-like command line tool, that can be used like this:

$ blackrenderer font.ttf ABC🤩 output.png --font-size=100

Library usage examples

There is a high level function to render a text string:

from blackrenderer.render import renderText

renderText("myfont.ttf", "ABC", "output.png")  # or "output.svg"

The full renderText() signature is:

def renderText(
    fontPath,
    textString,
    outputPath,
    *,
    fontSize=250,
    margin=20,
    features=None,
    variations=None,
    backendName=None,
)

For more control, the library exposes two main parts: the BlackRendererFont class, and a set of backend classes. Each backend provides a Canvas class. You pass a Canvas instance to a BlackRendererFont instance when drawing a glyph. Most backends also have a Surface class, which is a generalized convenience class to produce a canvas for a bitmap (or SVG document) for a specific box. Here is a minimal example:

from blackrenderer.font import BlackRendererFont
from blackrenderer.backends import getSurfaceClass

brFont = BlackRendererFont("my_colr_font.ttf")
glyphName = "A"
boundingBox = brFont.getGlyphBounds(glyphName)
surfaceClass = getSurfaceClass("skia")
surface = surfaceClass()
with surface.canvas(boundingBox)
    brFont.drawGlyph(glyphName, canvas)
surface.saveImage("image.png")

Canvas objects support the following transformation methods:

Save/restore is done with a context manager:

with canvas.savedState():
    canvas.scale(0.3)
    ...draw stuff...

Install

If you have a Python 3 environment set up, then all you need to do is:

$ pip install blackrenderer

Install for contributing / setting up an environment

Have Python 3.7 or higher installed.

Open Terminal.

"cd" into the project repo directory.

Create a virtual environment:

Activate the venv:

(You need to activate the virtual environment for every new terminal session.)

Upgrade pip:

Install the requirements:

Install blackrenderer in editable mode:

Run the tests:

Maintainers: how to release

To cut a release, make an annotated git tag, where the tag is in this format: v1.2.3, where 1, 2 and 3 represent major, minor and micro version numbers. You can add "aN" or "bN" or "rc" to mark alpha, beta or "release candidate" versions. Examples: v1.2.3, v1.2.3b2, v1.2.3a4, v1.2.3rc.

The message for the annotated tag should contain the release notes.

Then use "git push --follow-tags" to trigger the release bot. Example session:

This process will create a GitHub release, as well as upload the package to PyPI.