mirror of
https://github.com/python-pillow/Pillow.git
synced 2025-10-26 13:41:08 +03:00
141 lines
4.7 KiB
ReStructuredText
141 lines
4.7 KiB
ReStructuredText
|
|
.. _text-anchors:
|
|
|
|
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.
|
|
|
|
Specifying an anchor
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
An anchor is specified with a two-character string. The first character is the
|
|
horizontal alignment, the second character is the vertical alignment.
|
|
For example, the default value of ``la`` for horizontal text means left-ascender
|
|
aligned text.
|
|
|
|
When drawing text with :py:meth:`PIL.ImageDraw.ImageDraw.text` with a specific anchor,
|
|
the text will be placed such that the specified anchor point is at the ``xy`` coordinates.
|
|
|
|
For example, in the following image, the text is ``ms`` (middle-baseline) aligned, with
|
|
``xy`` at the intersection of the two lines:
|
|
|
|
.. image:: ../../Tests/images/test_anchor_quick_ms.png
|
|
:alt: ms (middle-baseline) aligned text.
|
|
:align: left
|
|
|
|
::
|
|
|
|
from PIL import Image, ImageDraw, ImageFont
|
|
|
|
font = ImageFont.truetype("Tests/fonts/NotoSans-Regular.ttf", 48)
|
|
im = Image.new("RGB", (200, 200), "white")
|
|
d = ImageDraw.Draw(im)
|
|
d.line(((0, 100), (200, 100)), "gray")
|
|
d.line(((100, 0), (100, 200)), "gray")
|
|
d.text((100, 100), "Quick", fill="black", anchor="ms", font=font)
|
|
|
|
.. container:: clearer
|
|
|
|
|
|
|
|
|
.. only: comment
|
|
The container above prevents the image alignment from affecting the following text.
|
|
|
|
Quick reference
|
|
^^^^^^^^^^^^^^^
|
|
|
|
.. image:: ../resources/anchor_horizontal.svg
|
|
:alt: Horizontal text
|
|
:align: center
|
|
|
|
.. image:: ../resources/anchor_vertical.svg
|
|
:alt: Vertical text
|
|
:align: center
|
|
|
|
Horizontal anchor alignment
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
``l`` --- left
|
|
Anchor is to the left of the text.
|
|
|
|
For *horizontal* text this is the origin of the first glyph, as shown in the `FreeType tutorial`_.
|
|
|
|
``m`` --- middle
|
|
Anchor is horizontally centered with the text.
|
|
|
|
For *vertical* text it is recommended to use ``s`` (baseline) alignment instead,
|
|
as it does not change based on the specific glyphs of the given text.
|
|
|
|
``r`` --- right
|
|
Anchor is to the right of the text.
|
|
|
|
For *horizontal* text this is the advanced origin of the last glyph, as shown in the `FreeType tutorial`_.
|
|
|
|
``s`` --- baseline *(vertical text only)*
|
|
Anchor is at the baseline (middle) of the text. The exact alignment depends on the font.
|
|
|
|
For *vertical* text this is the recommended alignment,
|
|
as it does not change based on the specific glyphs of the given text
|
|
(see image for vertical text above).
|
|
|
|
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.
|
|
|
|
See `Font metrics on Wikipedia`_ for more information.
|
|
|
|
``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.
|
|
|
|
``m`` --- middle
|
|
Anchor is vertically centered with the text.
|
|
|
|
For *horizontal* text this is the midpoint of the first ascender line and the last descender line.
|
|
|
|
``s`` --- baseline *(horizontal text only)*
|
|
Anchor is at the baseline (bottom) of the first line of text, only descenders extend below the anchor.
|
|
|
|
See `Font metrics on Wikipedia`_ for more information.
|
|
|
|
``b`` --- bottom *(single-line text only)*
|
|
Anchor is at the bottom of the text.
|
|
|
|
For *vertical* text this is the advanced origin of the last glyph, as shown in the `FreeType tutorial`_.
|
|
|
|
For *horizontal* text it is recommended to use ``d`` (descender) alignment instead,
|
|
as it does not change based on the specific glyphs of the given text.
|
|
|
|
``d`` --- descender / bottom *(horizontal text only)*
|
|
Anchor is at the descender line (bottom) of the last line of text, as defined by the font.
|
|
|
|
See `Font metrics on Wikipedia`_ for more information.
|
|
|
|
Examples
|
|
^^^^^^^^
|
|
|
|
The following image shows several examples of anchors for horizontal text.
|
|
In each section the ``xy`` parameter was set to the center shown by the intersection
|
|
of the two lines.
|
|
|
|
.. comment: Image generated with ../example/anchors.py
|
|
|
|
.. image:: ../example/anchors.webp
|
|
:alt: Text anchor examples
|
|
:align: center
|
|
|
|
.. _Font metrics on Wikipedia: https://en.wikipedia.org/wiki/Typeface#Font_metrics
|
|
.. _FreeType tutorial: https://freetype.org/freetype2/docs/tutorial/step2.html
|