Contents

• User's Guide
• Attribute Reference
• The annotation Command
• Differences From Maya's annotationShape Node
• Support & Copyright Information
• Downloads

User's Guide

The annotation node displays non-rendered text which faces the camera in every view. This makes it useful for providing labels and annotations in a model without having those annotations appear in the rendered output.

An annotation node may be created in one of two ways: by using the special annotation command, which is described later, or by using Maya's standard createNode command. For example:

    createNode -name "label" annotation;
    // Result: label

When initially created, there is no text associated with the node, so it is not visible within Maya's modelling windows. However, if you turn on one of the standard manipulation tools -- Move, Rotate or Scale -- you will see the appropriate manipulator appear at the annotation node's current location.

Text is added to the node by setting its text attribute, either through the Attribute Editor or using the setAttr command:

    setAttr -type "string" label.text "Sphere of influence";

A common use for annotation nodes is to label objects within your scene by constraining the annotation node to the object. Unfortunately, this places the annotation node's text right at the object's position, which may result in the object obscuring the text, or vice-versa, as in the example below.

You could correct this by grouping the annotation node, constraining the group node to the object, then moving the annotation node itself away from the center of the object. However, the annotation node provides a simpler approach with its horizontalOffset and verticalOffset attributes, which allow you to offset the node's text from its pivot point by the specified number of pixel positions. For example:

    setAttr label.horizontalOffset 100;
    setAttr label.verticalOffset 50;

If you have offset text in a cluttered scene, it may not be obvious which object the annotation node refers to. In this case, it can be useful to turn on its detailLine attribute, which causes the annotation node to draw a detail line from the offset text to the annotation node's pivot.

    setAttr label.detailLine true;

Note that in the image above the detail line is drawn to the centre of the text. This can be modified by changing the node's horizontalAlignment and verticalAlignment attributes. These control the alignment of the text with respect to its pivot, and thereby its alignment with respect to the detail line as well.

    setAttr -type "string" label.horizontalAlignment "left";
    setAttr -type "string" label.verticalAlignment "bottom";

Maya normally clips text such that if the first character of the text string is clipped by the edge of the window, then the entire string is clipped as well. The annotation node has this same behaviour by default, but you can override it by setting the node's perCharacterClipping attribute to true, in which case the unclipped characters within the string will still be displayed. The image below shows two annotation nodes whose text are being clipped by the left edge of the window. The lower one has per-character-clipping turned on while the upper one does not.

Per-character-clipping is more computationally intensive than the default clipping method. Normally, the additional overhead will not be noticeable, however if you have a large number of annotation nodes with per-character-clipping turned on, you may notice some degradation in playback speed, especially if many of the text strings are being clipped.

On Linux, the annotation node displays its text in the "fixed" typeface. However you can change this to any font available to the X Windowing System by setting the node's font attribute to a string containing either an X Logical Font Descriptor or a system-defined font alias. For example:

    setAttr -type "string" label.font "*-times-bold-r-*-*-*-240-*-*-*-*-*-*";

Normally, an X Logical Font Descriptor will begin with a hyphen. However, due to a bug in the setAttr command, you must remove this leading hyphen, otherwise Maya will interpret it as a command flag.

As an alternative to setting the font name by hand, you can connect a Gooroos Software font node to the annotation node's font attribute and then use the font node's attributes to determine the font used by the annotation node.

On Windows, the annotation node displays its text in the system's default "GUI font". There is no human-readable format for font descriptions on Windows so there is no way of directly specifying the font to be used by the annotation node. However, you can still connect a Gooroos Software font node to the annotation node and use the font node's attributes to determine the font used by the annotation node.

The image below shows the results of connecting an annotation node to a font node which is providing a large Times New Roman font.

The annotation node will display its text in whatever colour is currently assigned to the layer in which it resides. So to change the colour of the text you need merely change the colour of the layer.

Maya's default layer does not allow you to change its colour. In this case you can still change the annotation node's colour by setting its overrideEnabled attribute to true, and its overrideColor attribute to the appropriate colour value from Maya's palette. Note that these two attributes are not specific to the annotation node but are generic node attributes. They may be found in the Attribute Editor under the Drawing Overrides sub-section of the Display section.

    setAttr label.overrideEnabled true;
    setAttr label.overrideColor 13;  // Colour value for red

This will only work with annotations residing in Maya's default layer, and if you subsequently move the annotation node to another layer, it will revert to using that layer's colour.

Attribute Reference

An annotation node's special attributes are found in the Attribute Editor under the Annotation heading.

Long Name (Short Name)	Type	Default Value	Description
text (t)	string	(empty)	The text to be displayed by the node.
horizontalAlignment (ha)	string	"centre"	How the text should be horizontally aligned with the node's pivot. Valid values are "left", "right" and "centre".
verticalAlignment (va)	string	"middle"	How the text should be vertically aligned with the node's pivot. Valid values are "top", "bottom" and "middle".
detailLine (dl)	bool	false	If true, then a line is drawn from the text to the node's pivot. This only makes sense when a horizontal and/or vertical offset has been specified.
perCharacterClipping (pc)	bool	false	If true, then if the initial portion of the text is clipped, the unclipped characters will still be displayed. By default, if the initial portion of the text is clipped then none of the text is displayed.
horizontalOffset (ho)	short	0	Shifts the text right, relative to the node's pivot, by the specified number of screen pixels. If the value is negative, then the text is shifted left.
verticalOffset (vo)	short	0	Shifts the text up, relative to the node's pivot, by the specified number of screen pixels. If the value is negative, then the text is shifted down.
font (f)	string (Linux) long (Windows)	(empty) 0	Specifies the font in which the text is to be displayed. On Linux, this is a string containing either an X Logical Font Descriptor or the name of a system-defined font alias. If the attribute is empty or contains an invalid font name, then the system's "fixed" font will be used. On Windows, this is an HFONT handle to a loaded font. If zero or invalid, then the system's default GUI font is used. Since an HFONT handle is a dynamic, binary value, the Attribute Editor does not display this attribute under Windows.

The annotation Command

In addition to the annotation node itself, the plugin also provides a annotation command for use in MEL scripts or from Maya's command line. This command simplifies the task of creating and naming an annotation node, assigning it text, setting its various attributes, and connecting it to a font node.

The syntax of the annotation command is as follows:

    annotation [flags] [text]

where text is an optional string containing the text to be displayed by the created annotation node.

The flags accepted by the annotation command are shown below. For the most part they are used to set the various attribute values of the created annotation node. For more details on the meanings of those attributes, see the Attribute Reference.

-n/-name	STRING	Specifies the name to be given to the annotation node's transform. The annotation node itself will be given the same name with "Shape" appended to it. Default: "annotation"
-ha/-horizontalAlignment	STRING	Sets the annotation node's horizontalAlignment attribute. Must be one of "left", "centre" or "right". Default: "centre"
-va/-verticalAlignment	STRING	Sets the annotation node's verticalAlignment attribute. Must be one of "top", "middle" or "bottom". Default: "middle"
-ho/-horizontalOffset	INTEGER	Sets the annotation node's horizontalOffset attribute. Default: 0
-vo/-verticalOffset	INTEGER	Sets the annotation node's verticalOffset attribute. Default: 0
-pc/-perCharacterClipping	BOOLEAN	Sets the annotation node's perCharacterClipping attribute. Default: true
-dl/-detailLine	BOOLEAN	Sets the annotation node's detailLine attribute. Default: false
-cf/-createFontNode	BOOLEAN	If true, the command will create a font node and connect it to the annotation node's font attribute. If the font plugin is not loaded, the command will load it. Default: false
-fn/-fontNode	STRING	If the -createFontNode flag is true, then this flag specifies the name to be given to the created font node. If the -createFontNode flag is false, then this flag specifies the name of an existing font node which is to be connected to the annotation node's font attribute. Default: empty

The return value from the annotation command is an array of strings. The first element of the array contains the name of the annotation node's transform node while the second element of the array contains the name of the annotation node itself. If the -createFontNode flag is true, then there will be a third element in the array containing the name of the created font node.

The following example shows the annotation command being used to create an annotation node with the text "Key light" which has per-character clipping turned off and is connected to an existing font node called "romanFont":

    annotation -pc off -fn "romanFont" "Key light";
    // Result: annotation annotationShape

Differences From Maya's annotationShape Node

In version 4.5, Maya introduced the annotationShape node which provides features similar to Gooroos Software's annotation node. There are, however, a few differences which may impact your decision as to which one you should use:

Gooroos annotation Node	Maya annotationShape node
On Linux, it can display its text in any font available on the system. On Windows, it can do so when coupled with a Gooroos Software font node.	Always displays its text using Maya's default font.
Both ends of the detail line move with the annotation. You can group or constrain the annotation node to another node, so that the detail line will follow it around, but then the annotative text will also follow it.	Can be bound directly to another object so that one end of the detail line moves with that object while the other moves with the annotation.
Positions the text in screen space. So if you group an annotation with a sphere and offset the text up and to the right of the sphere, it will always appear up and to the right of the sphere, no matter how the view changes.	Positions the text in world space. So if you bind it to a sphere, the position of the text relative to the sphere will change as you pan and tumble the view.
Allows you to set the vertical and horizontal alignment of the text relative to the origin of the detail line, so that you can avoid having the detail line cut through the text.	Always aligns its text such that its baseline is centered over the origin of the detail line. This can result in the detail line cutting through the text in certain orientations.
Displays its detail line as a plain, unadorned line.	Displays its detail line with an arrowhead at the non-text end.

Support & Copyright Information

The annotation node and its associated materials, which are collectively referred to as "this product", are copyright Gooroos Software, 1999-2004.

Gooroos Software provides this product as-is and assumes no liability for its use. You may freely redistribute it, but only in complete and unmodified form.

If you have any questions or problems with this product, please send email to support@gooroos.com. Because this product is made freely available, we cannot guarantee you a response, but we will try to get back to you as time permits.

For more information on Gooroos Software and our other products, please visit our web-site at www.gooroos.com.

Downloads

Installation Instructions