Add getlength and getbbox functions for TrueType fonts

[nulano]

Third part of #4724, adding getlength and getbbox for TrueType fonts.

Changes proposed in this pull request:

• Add functions FreeTypeFont.getlength and ImageDraw.textlength which measure the advance length of text instead of the rendered width/height. These functions are both very precise (return the exact values from FreeType/Raqm) and fast (2-3x faster depending on the string, font, and layout engine). ImageDraw.textlength falls back on ImageDraw.textsize if using a non-FreeType font. Helps ImageFont module: getsize is slow? #4651, Font spacing changes #3977 (comment), font.getsize() changes after installing libraqm #4483, Obtain Character-Level Bounding Boxes of Generated Text #3921, Character bounding boxes and negative offsetx #4789.
• Update ImageDraw.multiline_text to use this new value, see test case test_imagefontctl.test_combine_multiline for an example (essentially fixing multiline version of issue Vertical text alignment ignores yOffset #4553).
• Add functions FreeTypeFont.getbbox and ImageDraw.[multiline_]textbbox, inspired by Fix return value of FreeTypeFont.textsize() does not include font offsets #784 (comment), which are a direct way to access the internal FreeTypeFont.font.getsize function, see Character bounding boxes and negative offsetx #4789 (comment) for the reasoning. This function will fail for non-FreeType fonts. Helps Obtain Character-Level Bounding Boxes of Generated Text #3921, Character bounding boxes and negative offsetx #4789.

[nulano]

Add functions FreeTypeFont.getlength... These functions are both very ... fast (2-3x faster depending on the string, font, and layout engine).

Using this PR I get (Windows 10 laptop):

ImageFont.LAYOUT_BASIC, getsize: 0.040550500000000045
ImageFont.LAYOUT_BASIC, getbbox: 0.040425799999999956
ImageFont.LAYOUT_BASIC, getlength: 0.019836500000000035
ImageFont.LAYOUT_RAQM, getsize: 0.030743399999999532
ImageFont.LAYOUT_RAQM, getbbox: 0.030728799999999445
ImageFont.LAYOUT_RAQM, getlength: 0.009379100000000307

Using master I get:

ImageFont.LAYOUT_BASIC, getsize: 0.040138600000000135
ImageFont.LAYOUT_RAQM, getsize: 0.030360500000000012

Using 7.2.0 from PyPI I get:

ImageFont.LAYOUT_BASIC, getsize: 0.040966599999999964
ImageFont.LAYOUT_RAQM, getsize: 0.030823299999999776

Code used (click to expand)

def run_test(function, layout):
    try:
        print(
            f"{layout}, {function}:",
            min(timeit.repeat(
                f"font.{function}('Hello world')",
                f"from PIL import ImageFont; font = ImageFont.truetype('Tests/fonts/FreeMono.ttf', 20, layout_engine={layout})",
                number=100, repeat=30,
            ))
        )
    except AttributeError:
        return -1

[hugovk]

Some minor bits n pieces.

[hugovk]

This should also have release notes, can be here or in another PR.

[nulano]

Did you see my comment #4959 (comment) about "following"/"given" text? GitHub insists on hiding it for me.

I have written the release notes in a separate branch so it will be a followup PR in a few minutes.

[hugovk]

Did you see my comment #4959 (comment) about "following"/"given" text? GitHub insists on hiding it for me.

Thanks, I'd missed that too. Thanks for the explanation!

[radarhere]

@nulano if you wouldn't mind helping my understanding, if getlength will

measure the advance length of text instead of the rendered width/height

then why wouldn't we want to use getsize width when determining the max_width of a rendered line? You mentioned that getlength is faster. Is this just for performance?