Default anchor documentation incorrect for horizontal text (`text` and `textbbox`)

[djhoese]

What did you do?

Read the documentation and the source code. I was mostly updating code to use textbbox instead of textsize and couldn't figure out why my text wasn't lining up the way I expected. The documentation for text and textbbox both say anchor defaults to "top left". This is only true for vertical (non-horizontal/) text.

https://pillow.readthedocs.io/en/stable/reference/ImageDraw.html#PIL.ImageDraw.ImageDraw.text

https://pillow.readthedocs.io/en/stable/reference/ImageDraw.html#PIL.ImageDraw.ImageDraw.textbbox

What did you expect to happen?

I expected similar results between the old textsize and the newer textbbox so I could adjust the position of the text for the old code I was updating. This old code adjusts the position rather than adjust the anchor to support multiple drawing backends (avoid passing anchor which other drawing backends might not understand).

What actually happened?

Unless I'm misreading the source code, the default anchor for horizontal text is "la":

Pillow/src/_imagingft.c

Lines 624 to 626 in 54c5631

	if (anchor == NULL) {
	anchor = horizontal_dir ? "la" : "lt";
	}

What are your OS, Python and Pillow versions?

• OS: Ubuntu
• Python: 3.11
• Pillow: 10.1.0

from PIL import Image, ImageDraw, ImageFont

font = ImageFont.load_default(size=40)
img = Image.new("RGB", (800, 800))
draw = ImageDraw.Draw(img)

text = "A"
pos = (400, 400)
bbox = draw.textbbox(pos, text, font, anchor="lt")
print("'lt' anchor bbox: ", bbox)
bbox = draw.textbbox(pos, text, font, anchor="la")
print("'la' anchor bbox: ", bbox)
bbox = draw.textbbox(pos, text, font)
print("Default anchor bbox: ", bbox)

'lt' anchor bbox:  (400, 400, 426, 428)
'la' anchor bbox:  (400, 411, 426, 439)
Default anchor bbox:  (400, 411, 426, 439)

[djhoese]

For what it's worth, my workaround for my problem of getting the overall offset of the text height was to take bottom - pos[1] which then includes the extra space added on by the ascender anchor.

[nulano]

I suppose it's not perfectly obvious, but "top left" is an ambiguous term; both la and lt are "top left", for different definitions of "top". This is clarified at the top of https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html#text-anchors:

The anchor parameter determines the alignment of drawn text relative to the xy parameter. The default alignment is top left, specifically la (left-ascender) for horizontal text and lt (left-top) for vertical text.

This was already the default before anchors were implemented.

---

I expected similar results between the old textsize and the newer textbbox so I could adjust the position of the text for the old code I was updating.

The default anchor for both is the same, however textsize had a bug¹ where it didn't include the top offset. This is explained in the documentation for the (now removed) textsize function:

Pillow/docs/reference/ImageDraw.rst

Lines 489 to 492 in 2045906

	.. note:: For historical reasons this function measures text height from
	the ascender line instead of the top, see :ref:`text-anchors`.
	If you wish to measure text height from the top, it is recommended
	to use :meth:`textbbox` with ``anchor='lt'`` instead.

In other words, the textsize function returned the following tuple:

left, top, right, bottom = font.getbbox(text)
assert font.getsize(text) == (right - left, bottom)

¹ It is unclear whether it is a documentation bug or an implementation bug, because the word "height" is ambiguous.

[djhoese]

Thanks for the quick response. I see what you're saying.

The docs say:

The default alignment is top left.

So you're saying:

I suppose it's not perfectly obvious, but "top left" is an ambiguous term; both la and lt are "top left",

I think it is easy to get confused by this because the "ambiguous" term uses the exact/precise terminology from the anchor page: top = "t", left = "l" => "top left" = "lt".

[djhoese]

If this is clear to others then no need to keep this open. I'll close this since my questions were answered.

[nulano]

https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html#vertical-anchor-alignment

Vertical anchor alignment

a — ascender / top (horizontal text only)
Anchor is at the ascender line (top) of the first line of text, as defined by the font.

a is stated to be the "ascender line", i.e. the line at the "top" of a line of text.

So in a sense, both t and a are the "top" of a line of text, for different definitions of "top".

A further complication is that anchors are only supported for fonts loaded with ImageFont.truetype; other fonts simply align the text by the top left point as they have no knowledge about the ascender line.

Continuing the text from (emphasis added) https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html#text-anchors:

The anchor parameter determines the alignment of drawn text relative to the xy parameter. The default alignment is top left, specifically la (left-ascender) for horizontal text and lt (left-top) for vertical text.

This parameter is only supported by OpenType/TrueType fonts. Other fonts may ignore the parameter and use the default (top left) alignment.

So while I agree the statement from draw.textbbox and related functions is confusing, I'm not entirely sure how it could be improved. What do you think of the following?

The text anchor alignment. Determines the relative location of the anchor to the text. The default alignment is top left, either la or lt. See Text anchors for details. This parameter is ignored for non-TrueType fonts.

[djhoese]

The text anchor alignment. Determines the relative location of the anchor to the text. The default alignment is top left, either la or lt. See Text anchors for details. This parameter is ignored for non-TrueType fonts.

Thoughts on "either la (horizontal) or lt (vertical)"? Or some other indication about which default is used when?

[nulano]

That doesn't mention non-TrueType fonts, but I think this would be good:

The text anchor alignment. Determines the relative location of the anchor to the text. The default alignment is top left, either la (horizontal text with TrueType font) or lt (otherwise). See Text anchors for details. This parameter is ignored for non-TrueType fonts.

(it does say it is ignored for non-TrueType fonts, but that is because those use the default, which is equivalent to lt for a TrueType font)

[djhoese]

Ah I see. Good point on the "otherwise". Given the length of the parenthetical, you could just make it part of the sentence:

The default alignment is top left which is "la" for horizontal text with TrueType fonts or "lt" otherwise.

Not sure I understood this or if I just missed it, but besides historical and backwards compatibility reasons, shouldn't the default alignment be "lt" for all orientations and fonts? Just for consistency?

[nulano]

For horizontal text, t alignment can change depending on the text being drawn, a alignment is always the same.

For example, the two words xyz and abc would be aligned differently with t alignment because the letter b is taller than the other letters.

OTOH, there is no ascender line when you have vertical text, but t alignment with vertical text is consistent (it isn't measured based on the bounding box but based on the "pen line" - see FreeType documentation).

From https://pillow.readthedocs.io/en/stable/handbook/text-anchors.html#vertical-anchor-alignment:

t — top (single-line text only)
Anchor is at the top of the text.

For vertical text this is the origin of the first glyph, as shown in the FreeType tutorial.

For horizontal text it is recommended to use a (ascender) alignment instead, as it does not change based on the specific glyphs of the given text..

The old ImageFont.ImageFont format is monospaced, so the top of each glyph is the same. Although it does not support anchors, it renders text in a way that is similar to lt for TrueType fonts.

[djhoese]

Ok so the "la" horizontal anchor is ideal but only available for some fonts. So the choice was best possible option versus consistent behavior (same anchor) of inconsistent placement (dependent on character height). Makes sense. I just wanted to make sure I was understanding the decision.

[nulano]

Correct. Additionally, it just so happens that this matches the historical behavior from before the anchor parameter was implemented.

[nulano]

I've created #7600 to update the documentation.