pygfx.geometries.TextGeometry

class pygfx.geometries.TextGeometry(text=None, *, markdown=None, screen_space=False, font_size=12, anchor='middle-center', anchor_offset=0, max_width=0, line_height=1.2, text_align='left', text_align_last='auto', family=None, direction=None)

Bases: Geometry

Geometry specific for representing text.

The TextGeometry creates and stores the geometry to render a piece of text. It can be provided as plain text or in markdown to support basic formatting.

Parameters:

  • text (str) – The plain text to render (optional).

  • markdown (str) – The text to render, formatted as markdown (optional). See set_markdown() for details on the supported formatting.

  • screen_space (bool) – Whether the text is rendered in screen space, in contrast to world space.

  • font_size (float) – The size of the font, in object coordinates or pixel screen coordinates, depending on the value of the screen_space property. Default 12.

  • anchor (str) – The position of the origin of the text. Default “middle-center”.

  • anchor_offset (float) – The offset (extra margin) for the ‘top’, ‘bottom’, ‘left’, and ‘right’ anchors.

  • max_width (float) – The maximum width of the text. Words are wrapped if necessary. A value of zero means no wrapping. Default zero.

  • line_height (float) – A factor to scale the distance between lines. A value of 1 means the “native” font’s line distance. Default 1.2.

  • text_align (str) – The horizontal alignment of the inline-level content. Can be “start”, “end”, “left”, “right”, “center”, “justify” or “justify-all”. Default “left”. Text alignment is ignored for top to bottom (‘ttb’) and bottom to top (‘btt’) directions.

  • text_align_last (str) – The horizontal alignment of the last line of the content element. Can be “start”, “end”, “left”, “right”, “center”, “justify” or “auto”. Default “auto”. Text alignment is ignored for top to bottom (‘ttb’) and bottom to top (‘btt’) directions.

  • family (str, tuple) – The name(s) of the font to prefer. If multiple names are given, they are preferred in the given order. Characters that are not supported by any of the given fonts are rendered with the default font (from the Noto Sans collection).

  • direction (str) – The text direction. By default the text direction is determined automatically, but is always horizontal. Can be set to ‘lrt’, ‘rtl’, ‘ttb’ or ‘btt’.

property screen_space

Text size unit (screen vs local).

Returns:

screen_space – If False, text size uses the unit of the local frame (e.g. cm). Otherwise it is uses the logical screen’s units (e.g. px). The latter mode is typically used for annotations.

Return type:

bool

Notes

Regardless of choice, the local object’s rotation and scale will still transform the text.

set_text_items(text_items)

Update the text using one or more TextItems.

Note

This is considered a low level function to provide more control. Use set_text or set_markdown for more convenience.

Parameters:

text_items (list) – A list of pygfx.TextItem objects to update the text with.

Notes

If the new text has more glyphs than the current one a new (larger) buffer is created. Otherwise, the previous buffers are reused.

set_text(text, family=None, style=None, weight=None)

Update the text.

Parameters:

  • text (str) – The new text.

  • family (str, tuple) – The name(s) of the preferred font(s) to prefer. If multiple names are given, they are preferred in the given order. Characters that are not supported by any of the given fonts are rendered with the default font.

  • style (str) – The style of the font (normal, italic, oblique). Default “normal”.

  • weight (str, int) – The weight of the font. E.g. “normal” or “bold” or a number between 100 and 900. Default “normal”.

See also

TextGeometry.set_text_items

set_markdown(markdown, family=None)

Update the text using markdown formatting.

The supported subset of markdown is limited to surrounding pieces of text with single and double stars for slanted and bold text respectively.

Parameters:

  • markdown (str) – The new text (including markdown).

  • family (str, tuple) – The name(s) of the font(s) to prefer. If multiple names are given, they are preferred in the given order. Characters that are not supported by any of the given fonts are rendered with the default font.

See also

TextGeometry.set_text_items

get_bounding_box()

Compute the axis-aligned bounding box.

Computes the aabb based on either positions or the shape of the grid buffer. If both are present, the bounding box will be computed based on the positions buffer.

Returns:

aabb – The axis-aligned bounding box given by the “smallest” (lowest value) and “largest” (highest value) corners. Is None when the geometry has no finite positions.

Return type:

ndarray, [2, 3] or None

apply_layout()

Update the internal contained glyphs.

To overload this with a custom layout, overload _apply_layout().

property font_size

The text size.

For text rendered in screen space (screen_space property is set), the size is in logical pixels, and the object’s local transform affects the final text size.

For text rendered in world space (screen_space property is not set), the size is in object coordinates, and the the object’s world-transform affects the final text size.

Notes

Font size is indicative only. Final glyph size further depends on the font family, as glyphs may be smaller (or larger) than the indicative size. Final glyph size may further vary based on additional formatting applied a particular subsection.

property max_width

The maximum width of the text. Text will wrap if beyond this limit. The coordinate system that this applies to is the same as for font_size. Set to 0 for no wrap. Default 0.

TEXT WRAPPING IS NOT YET IMPLEMENTED

property line_height

The relative height of a line of text, used to set the distance between lines. Default 1.2.

property text_align

Set the alignment of wrapped text. Can be start, end, or center. Default “start”.

Text alignment is ignored for top to bottom (‘ttb’) and bottom to top (‘btt’) directions.

property text_align_last

Set the alignment of the last line of text. Default “auto”.

Text alignment is ignored for top to bottom (‘ttb’) and bottom to top (‘btt’) directions.

property anchor

The position of the origin of the text. This is a string representing the vertical and horizontal anchors, separated by a dash, e.g. “top-left” or “bottom-center”.

  • Vertical values: “top”, “middle”, “baseline”, “bottom”.

  • Horizontal values: “left”, “center”, “right”.

property anchor_offset

The offset (extra margin) for the ‘top’, ‘bottom’, ‘left’, and ‘right’ anchors.