Labels
Learn more about labels in ILNumerics:
Labels are used to render text and other unicode characters on the screen. Currently, all labels render the text as screen objects. This means, the label output is always oriented towards the observer. Rotating the scene may cause the text to be hidden by other objects in the scene. However, it will never orient the text away from the observer.
Labels are able to render any unicode character in any font currently installed on the system. Next to common configuration options, like font, color, size, angle and anchor adjustment, a number of extended configuration options exist. The text property of any label can be used to embed simple TeX expressions for controlling the style, special characters, size and color – down to individual characters level if needed.
Fonts
The Label.Font property allows the definition of arbitrary fonts for the whole label text. This sets the base font – regardless if the text expression of the label switches fonts by TeX commands.
New label objects are initially set to the static property Label.DefaultFont. If not changed by the user, this will be set to "Helvetica" with the size of SystemFonts.MessageBoxFont. Altering Label.DefaultFont will effect all new instances of Label! Configured early enough, this is a simple way to switch all labels to another default font.
Color
The Label.Color property sets the color for the label text. Default is: Color.Black.
Size
Defines the size in point.
Position
The position of the anchor point for the label. The position is defined as 3-tupel in the coordinate system for the current scene graph node. This allows the definition of label positions in natural coordinates of the current model / scene (See: Label Example).
In the label example, all labels are added to the Screen node of the scene. This node maps coordinates in the range [0…1] to the screen width / height. Therefore, the position coordinate values for the labels are given in the range [0…1].
Anchor
The Anchor property defines the relation of the Position to the whole label bounding box. The bounding box always starts in the upper left corner of the unrotated label text (0, 0) and ranges to the lower right corner (1, 1):
In order to align a label to the left, one would use an anchor with the X coordinate of 0. Aligning to the right corresponds to an X coordinate of 1. Y = 0 -> top aligned, Y = 1 -> bottom aligned. An anchor of (0.5, 0.5) centers the label at the position point.
Arbitrary values are allowed for Anchor.X and Anchor.Y. It is allowed to define anchor points outside of the [0…1] range. By defining the point (-0.9,0.5) the label would always keep a distance to the Position point which is almost as large as the current label width.
Rotation
The rotation value rotates the label around the anchor point. Positive values turn the label in clockwise direction. The value is defined in radians.
In the picture, the anchor point was set to (1, 1). Hence, the label rotates around the lower right corner.
A value of 2*Pi corresponds to a full turn. The results of a full turn and no rotation are equal.
TeX Expressions
A label is capable of handling extensive text formatting. Therefore, special markups are allowed for the Text property. That way, one may configure the render output on a character by character base. Arbitrary parts of each label's text may get a different font (-name, -size and -style) assigned to as well as different colors.
For mathematical output it is important to have the option of drawing superscript and subscript indices, referencing special symbols like Greek letters, relational symbols and the like.
By default, all expressions given to the Text property are parsed for special control sequences. If a known sequence is found, it will control the next part of the expression until the end of the string or until a new sequence is again changing the current state. All control sequences must start with a backslash. If a sequence is not known, it is ignored. Some sequences require a parameter. Those parameters directly follow the control sequence and must be enclosed in curly brackets '{..}'.
Font Formatting
The following sequences control the appearance of font outputs:
|
Control Sequence |
Description |
|---|---|
| \bf | Bold font |
| \it | Italics |
| \rm | Regular font, removes any active bold or italic font style setting |
| \fontsize{10} |
Size of the font (points). The size can be defined by absolute value or ... |
| \fontsize{-2} | relative values. A '+' or a '-' suffix marks the relative mode |
| \fontname{Courier} | Name of the font. If the font specified could not be found in the system, the current font is not changed. |
| \color{blue} |
Color for the font. Valid parameters are: 1. Names of colors from the Color.KnownColor enumeration, or 2. a color definition in HTML style (e.g. '#FF56E0') |
| \reset | Resets font style, -name or -size changes to the settings configured to the label |
| \alpha, \beta, \theta, \Theta, \Phi ... | Greek letters, most lower case, some Uppercase letters are available |
Sub- and superscripts
The underscore '_' is used to create subscripts. Like well-known from TEX, this is only valid for the next character. To extend the subscript mode to more characters, the characters must get enclosed in curly brackets.
The same rules apply for superscripts, which are specified by '^'.
Special Characters
All characters defined for the current font can be used for output. For characters that are required more frequently, abbreviations (control sequences) exist to enable simplified definitions. All sequences generate regular Unicode characters. Therefore they might be entered via keyboard or via Unicode sequences.
Keep in mind: The chars defined here will only specify the char to be rendered out of the currently selected font! Make sure that the font really provides these characters; otherwise it won't show up!
Label Example
The following example demonstrates most of the features of ILNumerics labels.