Including Text

In a complicated mathlet, you might want to include text labels for certain points, curves, or other objects. We will illustrate the process here by adding text to the mathlet from the introduction. You may wish to review the construction of this mathlet in the first few pages of the article. Since we will only add text primitives to the scene, most of the code from those pages can be reused. Only the last two commands need to be replaced.

With LiveGraphics3D you can label the whole plot and individual axes, and you can put text labels at arbitrary three-dimensional points in your scene. For example, in order to label the blue and green sections with labels x = const. and y = const., respectively, we only need to insert two Text primitives. The arguments of each Text primitive specify the text to be displayed, a three-dimensional point determining the position of the label, and (optionally) a two-dimensional vector specifying the horizontal and vertical alignment with respect to the projected three-dimensional position. The default value for this 2D vector is {0,0}, specifying that the text is centered horizontally and vertically. For the first label we use {1,1} to align the right and top edges of the text with the projected three-dimensional point, while the left and top edges of the second label are aligned at its three-dimensional location by specifying {-1,1}.

(* all but the last two commands are the same as in the earlier example *)

labels = {Text["x = const.", {x, -2, 0}, {1,1}],
    Text["y = const.", {3, y, 0}, {-1,1}]};

example = Graphics3D[
    {mesh, point, xSection, ySection, tanplane, labels},
    Boxed -> False, Lighting -> False]
WriteLiveForm["meshPlaneText1.lg3d", example]

Resulting applet:

Note that the labels move with the cross sections as you drag the red point because the variables x and y appear in the specification of their position. However, this was only the first step. There are actually many ways to format text in LiveGraphics3D. First of all, we can change the font and its size by wrapping the labels in a formatting function named StyleForm. Here is an alternative assignment for labels, which modifies the font and its size:

labels = {Text[StyleForm["x = const.", FontFamily -> "Times",
    FontSize -> 20],
    {x, -2, 0}, {1,1}],
    Text[StyleForm["y = const.", FontFamily -> "Times",
    FontSize -> 20],
    {3, y, 0}, {-1,1}]};

Most systems support the fonts "Times", "Courier", and "Helvetica"; however, not all special characters are supported in all fonts nor by all systems. In our experience, "Times" usually offers the largest set of special characters. These characters can be entered with their hexadecimal unicode; for example, "\:03b1" represents a lower-case Greek alpha. Many special characters, in particular Greek characters, may be entered by names such as "\[Alpha]" for the lower-case alpha or "\[CapitalAlpha]" for the upper-case alpha. A list of all named characters recognized by LiveGraphics3D is available in the reference guide for Mathematica 3.0 (Wolfram, 1996).

In order to modify the style of parts of a text label, you can use StringForm. The first argument of StringForm is a formatting string, which contains placeholders (`1`, `2`, etc.) for the following arguments. Here is an example, which also shows how to specify symbols in italics and in bold letters:

labels = {Text[StyleForm[StringForm["`1` = const.",
    StyleForm["x", FontSlant -> "Italic"]],
    FontFamily -> "Times", FontSize -> 20],
    {x, -2, 0}, {1,1}],
    Text[StyleForm[StringForm["`1` = const.",
    StyleForm["y", FontWeight -> "Bold"]],
    FontFamily -> "Times", FontSize -> 20],
    {3, y, 0}, {-1,1}]};

Resulting applet:

Apart from static labels, we can also include the value of any variable in a text label. For example, we can replace the string "const." by the actual value of x and y. The next example shows two slight variations: The label for x emphasizes the difference between the text label x specified with "x" and the value of x specified with x:

labels = {Text[StyleForm[StringForm["`1` = `2`", "x", x],
    FontFamily -> "Times", FontSize -> 20],
    {x, -2, 0}, {1,1}],
    Text[StyleForm[StringForm["y = `1`", y],
    FontFamily -> "Times", FontSize -> 20],
    {3, y, 0}, {-1,1}]};

Resulting applet:

As you drag the red point in this example, the new numeric values of x and y will be displayed by the two text primitives.

To display a changing numeric value in LiveGraphics3D, the text label must refer to a specific variable. For technical reasons, it is not possible to include arbitrary mathematical expressions within a label; a primitive such as Text[x+y, {0,0,0}] will result in an error. This is not a serious limitation, however, since we can always define a dependent variable for any mathematical expression and then include the name of this dependent variable in a text label instead of the expression.

For example, let us display the values of x and y with only two decimal digits. The most straightforward way to accomplish this is to display Round[100*x]/100 and Round[100*y]/100 instead of x and y, respectively. Since we cannot put these expressions into a Text primitive, we have to define new dependent variables, say xDisplay and yDisplay. Thus, the complete <APPLET> tag becomes:

<applet archive="live.jar" code="Live.class" width="500" height="500">
<param name="INPUT_FILE" value="meshPlaneText4.lg3d"/>
<param name="INDEPENDENT_VARIABLES" value="{x -> 1, y -> 0}" />
<param name="DEPENDENT_VARIABLES" value="{
    x -> If[x < -1, -1, x],
    x -> If[x >  3,  3, x],
    y -> If[y < -2, -2, y],
    y -> If[y >  1,  1, y],
    z -> 2y*Exp[-x^2-y^2],
    xDisplay -> Round[100 * x] / 100,
    yDisplay -> Round[100 * y] / 100}" />
</applet>

Note the two new variables xDisplay and yDisplay in the list for dependent variables. These variables also have to appear in the definition of labels. There's one additional change in the following code. You might have noticed above that the labels tend to jump around as the lengths of the displayed numbers change. This is very distracting, and can be avoided by using two text primitives for each label. In the following definition, the string "x =" is displayed just below and to the left of the point {x, -2.5, 0}, while the value of xDisplay is shown just below and to the right of that point. A similar strategy is used for the other label.

labels = {
    Text[StyleForm["x = ", FontFamily -> "Times", FontSize -> 20],
    {x, -2.5, 0}, {1, 1}],
    Text[StyleForm[xDisplay, FontFamily -> "Times", FontSize -> 20],
    {x, -2.5, 0}, {-1, 1}],
    Text[StyleForm[["y = ", FontFamily -> "Times", FontSize -> 20],
    {3.5, y, 0}, {1, 1}],
    Text[StyleForm[yDisplay, FontFamily -> "Times", FontSize -> 20],
    {3.5, y, 0}, {-1, 1}]
};

Resulting applet:

As mentioned earlier, Text primitives are not the only way to include labels in LiveGraphics3D. Two other possibilities, namely labels for axes and the whole plot, will be discussed in the next section.