Formatted Text and Labels

There are a number of different places in SwiftVis where text elements can be placed on plots. These include top level text, axis labels, and plot labels. These all use a class called FormattedString that allows you to do formatting similar to LaTeX along with the ability to evaluate formulas and put their values into the string. This page begins by describing the abilities of the FormattedString and follows that with a discussion of the plot labels that goes beyond just formatted strings.

As much as possible the FormattedString class uses LaTeX formatting so that most people will be able to produce the output they desire without having to look up or memorize new commands. The simplest and most common formatting instructions are subscript and superscript. This are specified with _{...} and ^{...}. The curly braces are required and whatever is inside of them will be sub or super scripted, even if it is complex. If you want something to have both a subscript and a superscript, make sure to put the subscript first. This is a logical ordering as giving an x both a subscript and superscript implies that the value specified by the subscript should be raised to the superscript. Doing them in the opposite order will produce a subscript that trails the end of the superscript.

As with LaTeX, the backslash, "\", is an escape character and significes that what follows it should be treated specially. If you want to put a caret or an underscore in your string you need to precede it with a backslash. Greek characters can be displayed by following the backslash with the name of the character. For example, \tau will display a lowercase tau. To get upper case Greek letters simply capitalize the first letter. Other allowed escape sequences are shown in the table below.

\pm ±
\O Ø
\times ×
\div ÷
\frac{num}{demon} Draws num over denom as a fraction.
\sum_{i}^{f} This shows a summation with the initialization, i, below the sigma and the final value, f, above it. Both parts are optional. This shows a larger symbol than \Sigma. If you want the limits of the sum shown after to symbol instead of above and below, use \Sigma_{i}^{f}.
\lim_{sub} This will display a limit with sub in the subscript. Common usage will probably have sub replaced by a string like "0 \to \infty". Leaving out the backslash before lim will result in the limit being placed like a normal subscript.
\int_{lower}^{upper} This displays an integral with the specified lower and upper bounds. The subscript and superscript are optional though a superscript can only be used if a subscript is present.

If you want to put in characters that are not provided in the list above, you can place any Unicode character into a string by following the backslash with either a number or x followed by a number. If the x is provided then the number should be in hexidecimal, otherwise it is decimal. For example, \x2204 will insert the "does not exist" symbol, ∄. You can use this page for assistance in finding Unicode symbols for mathematical expressions. If there are other LaTeX commands that you would like to see implemented in SwiftVis please contact us so that we can add them. Because typesetting is not the primary usage for SwiftVis this is not an area that will be developed except for specific user requests. Basically we aren't going to try to recreate LaTeX inside of SwiftVis.

Numeric data formulas can also be placed in formatted strings by placing them between dollar signs ($). These function just like data formulas in any other part of SwiftVis. The value that will be displayed will always use the first element of the sources for the plot object. This can be helpful to do things like putting the current time in a plot that is coming through a movie filter. Since v[0] is typically the time in Swift files, the formatted string "Time=$v[0]$" will show the time of the first element going into the plot. This can be combined with any of the above formatting as well. By using selection in groups or offset indexes you can pull information out of elements other than the first one.

You can further control the way that the numbers are printed by including a printf style formatting sequence after the first dollar sign and between % and : characters. Technically the formatting uses the java.util.Formatter class and you can refer to the web page documentation for a full description of how values will be printed. The code always passes in a double so the e, f, g, and a conversions make sense. If the format conversion is a d, o, or x then SwiftVis will convert the double to an int (truncation) and uses that int. If you aren't familiar with the C style of formatting from printf, the above example could be extended so you use a string like "Time=$%6.2f:v[0]$" to say that the number should be displayed with at least 6 characters and you want two of them after the decimal point.

Plot Labels

Adding labels into plots is a common activity. SwiftVis supports the addition of four different types of labels: text, lines, rectangles, elipses. For each type you get to specify different options that are appropriate for that type of label. All of the labels allow you to specify a color to draw in and whether the label should be drawn above or below the plot data. In the case of text you get to specify a formatted string using the formatting that was described above, a font, and a position for the string placement. The position of the string is specified with three selections. The most important allows the user to pick what the string will be plced relative to. By default it is a point in the plot. This is helpful for doing things like putting a label on a point to tell what it represents. Formulas are used to specify the location where it should be drawn. The formula is evaluated using the first element. As with the formulas in the strings, group selections or index offsets can be used to pick values from other elements. In addition to placing the text at a point on the plot, the user can also specify that the text should be drawn in one of 9 different positions at the corners or midpoints of the plot. When these are selected, the formulas for x and y specify offsets in pixels. Keep in mind that constants are perfectly valid formulas.

For a line the user is able to specify the beginning and end points with formulas. The user can also specify the thickness of the line to draw as well as whether the line should have an arrow head on it and how big that arrow head should be. Line labels are most useful for connecting text labels to points when putting the text near the point would be unclear or would clutter the plot.

For the rectangle and the ellipse the user gets to specify the location of the minimum x and y values as well as the width and height. Again, these are specified with formulas. For these labels there are two colors that can be specified: the line and the fill. Setting the fill to transparent will allow only the outline to show up. The thickness of the line for the outline can also be set. One use of a rectangle label is to give the plot a background color other than white. By specifying a rectangle that would cover the entire plot area and having it drawn below below the data, it can effectively change the background color. The ellipse label can be helpful for putting in circles that represent fixed bodies in a simulation when those bodies are not part of the data that is being plotted.