Home

If you're new to Python
and VPython: Introduction

A VPython tutorial

Pictures of 3D objects

What's new in VPython 6

VPython web site
VPython license
Python web site
Math module (sqrt etc.)
Numpy module (arrays)

 
text
text

text

With the text object you can display 3D text. The green 3D text shown above was created with the following statement:

text(text='My text is\ngreen',
    align='center', depth=-0.3, color=color.green)

Labels were added to the display above to illustrate some of the main attributes of the text object; the full program text3d.py can be seen in the VPython examples. Whether you extrude into or out of the screen, the text is created so that it is readable left to right from the normal viewing position, in the +z direction. If you wish to position the text differently, change the axis from its default value of (1,0,0).

Here is a list of text attributes:

pos; x,y,z The location of the baseline of the text, to the left, to the right, or at the center of the text, as per align.

align Specify 'left' (default), 'right', or 'center'.

text The text to be displayed, such as My Text in the example above. Python Unicode strings are supported. Currently it is not possible to display more than a single line of text with one text object.

font Name of the desired font; for example, 'sans', or 'serif' (default), or 'monospace' (fixed-width). You can also give specific names such as "Times" or "Verdana". An attempt is made to find a font name that best matches the name you specify. If there is no match, font defaults to 'sans'.

height Height of an uppercase letter (see above); default is 1. Specifying the height and depth sets the scale for the entire text display. Changing the height also changes descent and vertical_spacing, but not depth.

depth Depth of the text, which can be a single number or a vector. For a single number, positive means extrude toward you, out of the screen; negative means extruded away from you, into the screen. For a vector, the text is extruded in the direction of the vector. Default depth is 0.2.

width Width of the displayed text. This is "read-only" and is determined by the text. Also, widths is a list of the widths of all lines of text, so widths[0] is the width of the top line, etc.

axis The axis points along the baseline; changing the axis changes the orientation of text. The axis is normalized to have a length of 1. The default is (1,0,0), with text going toward the right.

descent Height of the descender on lower-case letters such as y (whether or not there is such a letter in the text). This is typically about 0.3 times the height. This is read-only.

vertical_spacing Vertical distance from one baseline to the next in a multiline text. The default is set by the font you use, but you can override this by changing the value.

color, red, green, blue Color of the text.

material Material such as materials.wood.

upper_left, upper_right, lower_right, lower_left The bounding box of the displayed text; all of these are read-only. For example, if you create title = text(text="My Text"), you can place a sphere at the upper left corner with the statement sphere(pos=title.upper_left). While height and descent indicate the general properties of the selected font, upper_left etc. tell you the bounding box of the actual text. For example, if the text is "ABC", lower_left will be at the same height as start because there are no descenders, and if the text is "mno", upper_left will be less than height above the baseline because there are no upper-case letters.

start The left-most location on the baseline. This is read-only. Also, starts is a list of the starts of all lines of text, so starts[0] is the start of the top line, etc.

up Controls the up attribute of the frame; changing up makes the text tip away from the vertical.

spacing Makes space between letters, specified as a fraction of height (default is 0.03).

twosided A text object is a complex object that can take longer to render onto the screen than other objects, due to the many calculations required to generate the triangles and normals required for the display. Like all other objects (except for faces), a text object by default is two-sided (so that you see interior "walls" if you zoom inside the object). One way to get a significant speed-up is to make the object not be two-sided, by setting twosided = False.

The following code will list the True Type fonts on your system that can be used with a text object:

fonts = shapes.findSystemFonts()
for f in fonts:
    print(f)

Extracting extrusion data

The following statement provides the pos, normal, and color information needed for creating a single-sided faces object:

(pos, normal, color) = T.get_faces()

You can convert a text object directly to a faces object, though this has the disadvantage that you lose the ability to change the text attributes dynamically:

T = text(.....)
F = E.create_faces() # produces an equivalent faces object

The conversion routine makes the text object invisible and by default destroys its contents. If you wish to keep the text object for later modification, say E.create(keep=True).

The faces object uses much more memory than the equivalent text object, and it may actually take as long or longer to render. The effect on the speed depends on the details of the text object and the platform you're using.

The create_faces() function uses the get_faces() function but also copies into the faces object the frame, material, and up attributes of the text object, makes the extrusion object invisible, and destroys its contents (unless you specify that keep=True).

See description of Additional Attributes available for all 3D display objects.