Text3D

Text3D#

Text3D(
string: str,
*,
depth: float | None = None,
width: float | None = None,
height: float | None = None,
center: VectorLikeFloat | None = (0.0, 0.0, 0.0),
normal: VectorLikeFloat = (0.0, 0.0, 1.0),
) → PolyData[source]#

Create 3D text from a string.

The text may be configured to have a specified width, height, or depth.

Parameters:
stringstr

String to generate 3D text from. If None or an empty string, the output mesh will have a single point at center.

depthfloat, optional

Depth of the text. If None, the depth is set to half the height by default. Set to 0.0 for planar text.

Changed in version 0.43: The default depth is now calculated dynamically as half the height. Previously, the default depth had a fixed value of 0.5.

widthfloat, optional

Width of the text. If None, the width is scaled proportional to height.

Added in version 0.43.

heightfloat, optional

Height of the text. If None, the height is scaled proportional to width.

Added in version 0.43.

centerVectorLikeFloat | None, default: (0.0, 0.0, 0.0)

Center of the text, defined as the middle of the axis-aligned bounding box of the text. If None, the text is not centered: its baseline starts at the origin and its back face lies in the plane through the origin perpendicular to normal.

Added in version 0.43.

Changed in version 0.50: Allow None to keep the text at its origin.

normalVectorLikeFloat, default: (0.0, 0.0, 1.0)

Normal direction of the text. The direction is parallel to the depth of the text and points away from the front surface of the text. A normal alone does not uniquely specify the text’s orientation, since the text can also rotate about that normal. Use pyvista.Transform with pyvista.DataObjectFilters.transform() to control the full orientation, as shown in the examples.

Added in version 0.43.

Returns:
pyvista.PolyData

3D text mesh.

Examples#

Download Python source code | Download Jupyter notebook

Create 3D text.

>>> import pyvista as pv
>>> text_mesh = pv.Text3D('PyVista')
>>> text_mesh.plot(cpos='xy', show_bounds=True)
../../../_images/pyvista-Text3D-50fea30087e8d400_00_00.png

Create planar text.

>>> text_mesh = pv.Text3D('PyVista', depth=0)
>>> text_mesh.plot(cpos='xy', show_bounds=True)
../../../_images/pyvista-Text3D-50fea30087e8d400_01_00.png

Set the depth explicitly.

>>> text_mesh = pv.Text3D('PyVista', depth=5)
>>> text_mesh.plot(cpos='xy', show_bounds=True)
../../../_images/pyvista-Text3D-50fea30087e8d400_02_00.png

Set the width explicitly. The height and depth are automatically scaled proportionally.

>>> text_mesh = pv.Text3D('PyVista', width=10)
>>> text_mesh.plot(cpos='xy', show_bounds=True)
../../../_images/pyvista-Text3D-50fea30087e8d400_03_00.png

Set the height explicitly. The width and depth are automatically scaled proportionally.

>>> text_mesh = pv.Text3D('PyVista', height=10)
>>> text_mesh.plot(cpos='xy', show_bounds=True)
../../../_images/pyvista-Text3D-50fea30087e8d400_04_00.png

Set the height and width. The depth is automatically scaled proportional to height.

>>> text_mesh = pv.Text3D('PyVista', height=10, width=10)
>>> text_mesh.plot(cpos='xy', show_bounds=True)
../../../_images/pyvista-Text3D-50fea30087e8d400_05_00.png

Set the height, width, and depth independently, and adjust the center.

>>> text_mesh = pv.Text3D(
...     'PyVista', height=10, width=10, depth=0, center=(5, 5, 0)
... )
>>> text_mesh.plot(cpos='xy', show_bounds=True)
../../../_images/pyvista-Text3D-50fea30087e8d400_06_00.png

Control the full orientation with an explicit transform. Create planar text with the default normal: it lies in the xy plane, reads along +x, and extends upward along +y. Rotate it 30 degrees about z, then 90 degrees about x, and finally translate it. The default post-multiplication mode applies these operations in the order shown.

>>> text_mesh = pv.Text3D('PyVista', depth=0)
>>> transform = pv.Transform().rotate_z(30).rotate_x(90).translate((1, 2, 3))
>>> oriented_text = text_mesh.transform(transform, inplace=False)

The transformed normal points along -y. Changing the first rotation changes the text’s rotation about that normal without changing the normal itself. The original text_mesh is unchanged.

See Also#

pyvista.Text3DSource

Generate text with a reusable source.