Name labeler
Type mapper
Inputs field, any-data, any-coordinates (optional)
colormap (optional)
upstream transform (optional, invisible)
Outputs geometry
Parameters
Name Type Default Min Max Choices
safety toggle on -
label offsets string $NULL -
label font integer 1 0, 20
label height float 0.0 0.0, unbounded
label precision float 1.0 0.0, unbounded
label value factor float 1.0 0.0, unbounded
alignment radio cent left, cent,
right
background toggle off -
drop-shadow toggle off -
stroke toggle off -
title toggle on -
show pins toggle on -
freeze aspect toggle off -
uniform color string $NULL -
value translation browser $NULL -
file
title string string $NULL -
title file browser $NULL -
Input Field (optional, field, any-data, any-coordinates)
The input data field may contain data of any dimensionality or
vector length in any data type and grid configuration. Values
are converted into floats. The use of a data field is required
only if data labels are to be created. If any titles are also
provided, the input field will be ignored.
Input Colormap (optional)
If a colormap is supplied, scalar data labels may be individually
colored by their values. Vector data labels are not colored by
their values. All types of labels may be colored uniformly, either
through a single value that maps into a colormap or through three
values (for red, green, and blue) that require no colormap. See
the section about the uniform color parameter for a discussion of
color specifications.
Transform Info (optional, invisible, upstream transform)
In order for the freeze aspect option to work, the labeler module
must receive transformation data from the render geometry module.
AVS automatically makes this connection when the labeler module is
instantiated.
safety
When set, safety serves as a local "disable flow executive" --
the labeler module will not respond to parameter or input changes
until safety is turned on. This allows the user to set several
parameters without having to wait for the labeler module to respond
to each one individually. When safety is off, the labeler module
responds to each parameter or input change as it occurs.
label offsets
The label offset parameter is a string that contains as many as
three numerical values separated by blanks. These values are read
as X, Y, and Z offset values in that order. Any trailing values
that are unspecified are assumed to be zero. For data labels and
object labels, these offsets are in the data's physical space
coordinate units and indicate the displacement from each reference
point to its respective label. If the resultant offset is not zero
and the show pins parameter is on, these labels will be connected
to their reference points by "pins" (disjoint line segments).
For non-object title labels, if the title toggle is off, the offset
values are treated the same as they are for object and data labels.
Otherwise, with the title toggle on, the offsets are in display
window coordinate units -- the point (-1.0, -1.0, -1.0) is at the
back at the lower left corner of the window; point (1.0, 1.0, 1.0)
is at the front at the upper right.
label font
The label font parameter specifies the character font of the labels
to be created. The labeler module uses the labeling capabilities
available through AVS. Since these capabilities vary from platform
to platform, so do the labeling capabilities of labeler. The number
of fonts on a platform depends on the number of type face styles
that are available and whether or not they are available in bold
or italic styles.
label height
The height of the label characters is given in display window coor-
dinate units. A label height of 1.0 will produce labels that are
half as tall as the window (very large!). Much smaller values (like
0.05 or so) are much more appropriate. Different platforms may have
different limits on label heights. A label height of zero produces
no labels.
label precision
The displayed precision of data labels is controled by the label
precision parameter. If the label precision is zero, one, or
greater than one, the displayed precision will be units. A label
precision value of 0.1 will display values to the nearest tenth;
0.01, to the nearest hundredth; etc. If title labels are being
created, the label precision parameter is ignored.
label value factor
Data values are divided by the label value factor to produce the
values displayed by their data labels. The values displayed as the
data labels should be multiplied by the label value factor to get
the actual data values. A label value factor of zero is treated as
though it were 1.0. If title labels are being created, the label
value factor parameter is ignored.
alignment
For each label, a reference point is calculated. In the case of
a data label, this point is the data point plus any offsets. In
the case of a title label, the reference point coordinates are the
values of the label offsets. The alignment parameter specifies
whether the reference point is to the left, center, or right of the
label. The labeler module tries to vertically center the reference
points for left and right alignments and horizontally center the
references points for center alignments but this effort is not
always successful on all platforms.
background
drop-shadow
stroke
These three parameters control additional label attributes. Not
all of these parameters are available on all platforms. The
background attribute will mask out an area around each label in an
attempt to improve label legibility. The drop-shadow attribute
tries to improve label legibility by drawing a one-pixel wide black
edge to the right and bottom of the label. The stroke attribute
invokes stroke, rather than bitmapped, characters.
title
If the title toggle is on, the offsets will be used to position
the title labels within the display window. The result is labels
that are fixed in the display window. If the title toggle is off,
the offsets will be used to position the title labels within the
data physical space. This results in labels that are attached to
the "top" object and will move with that object as it is moved.
With data labels, the title toggle is ignored.
show pins
Data and object labels that are offset from their reference points
may be connected to their reference points by "pins" (disjoint
line segments). These pins are enabled by the show pins parameter.
Since non-object title labels are not allowed to have pins, the
show pins parameter is ignored when these labels are created.
freeze aspect
As a scene is transformed (rotated and shifted), data and object
labels and their pins may be transformed so that they are awkwardly
positioned and thereby less legible and less effective. Once a
suitable orientation for these labels and their pins has been found,
it can be maintained by setting the freeze aspect toggle to on.
Once frozen, the aspect (or orientation with respect to the viewer)
of the labels and pins will remain constant as the scene is trans-
formed. For reliable results, immediately after setting the freeze
aspect toggle to on, the user should click the middle or right mouse
button without moving the mouse. This null transformation is neces-
sary to inform the labeler module of the current orientation of the
scene. Then, as the scene is transformed and the mouse buttons are
released, the labels will snap back to a position that maintains
their frozen aspect.
The freeze aspect toggle has no effect on non-object title labels
since they are always fixed in the display window.
uniform color
If the uniform color string is null or contains no values, labels
will have their otherwise "usual" colors. If the uniform color
string contains a single value and a colormap is supplied, all of
the labels (data or title) will be colored according to how this
value maps into the colormap. If the uniform color string contains
three values, these values are interpreted as red, green, and blue
values, ranging from 0.0 to 1.0, and all of the labels will be
colored using these values. When using this RGB method, a colormap
is not used.
value translation file
Data values are normally translated into strings that show their
values. However, there may be occasions when it is desirable to
have the values translated into arbitrary character strings. This
can be accomplished through the use of a value translation file. A
value translation file is an ASCII file and its format is fairly
loose. Each record must contain three parameters -- the minimum
and maximum of a value class and the string for that class. Each of
these parameters must be separated from the others by white space
(blanks or tabs). White space around the value string will be
ignored unless the entire string is delimited with double quotes
('"').
In the following example, "None" is used for all values of exactly
0.0; "Very Low" for values from 0.1 up to 0.2; "Low" for 0.2 through
0.5; "Moderate" for 0.51 up to 0.6; "High" for 0.6 up to 0.8; "Very
High" for 0.8 up to 0.9; and " Extremely High " for values from
0.9 through 1.0.
0.0 0.0 None
0.1 0.2 Very Low
0.2 0.5 Low
0.51 0.6 "Moderate"
0.6 0.8 High
0.8 0.9 Very High
0.9 1.0 " Extremely High "
The value translation file is ignored when title labels are created.
title string
title file
The title string parameter is used to enter a single line of text
to be used as a title label. The attributes of this label are those
specified through the other parameters. Multiple title labels may
be entered through a title file. A title file is an ASCII file
each record of which contains data for a single label. The format
of these records is:
text
or
"text" x y z font height align back drop stroke color
or
"text" x y z font height align back drop stroke r g b
The above terms are defined as:
value type corresponding parameter
text string text string
x y z float label offsets. All 3 must be given.
font integer label font
height float label height.
align integer alignment: -1 = left, 0 = center, 1 = right
back integer background: 0 = off, 1 = on.
drop integer drop-shadow: 0 = off, 1 = on.
stroke integer stroke: 0 = off, 1 = on.
color float uniform color. One value, for use with a
colormap.
r g b float uniform color. Three values ranging from
0.0 to 1.0, for red, green, and blue.
The label text needs to be enclosed in double quotes ('"') if it
includes leading or trailing blanks or if it is followed by label
attributes. All of the values need to be separated by white space.
If any attribute values are specified, they must all be specified,
with the exception of the color value(s). Color value(s) can be
specified only if the other attribute values have been specified.
A color specified in the title file will replace the color specified
through the uniform color and will become the default color for
subsequent titles that do not specifiy a color.
Ordinarily, the setting of the title parameter determines whether
these strings will become fixed title labels or object title labels.
However, a string may be explicitly identified as an object title
label by indicating its offsets, enclosed within parentheses and
following the X, Y, and Z values. In this case, the X, Y, and Z
values become the reference point in the data physical space and
the values within the parentheses become the offsets from that
reference point to the label. Explicit offsets are specfied by
including three values within the parentheses. If only an asterisk
("*") is included within the parentheses, the offsets will be those
specified by the label offsets parameter. In either case, these
offsets become the defaults for all subsequent labels in the file
until a new set of offsets is specified. This, effectively, sets
the title toggle to on for the current and all subsequent labels.
It can not be reset to off. For reliable results, object title
labels and non-object title labels should not be mixed in the same
title file.
If the record for a label contains only the label text and does not
contain any attribute values, the previously set attribute values
will be used. The initial attribute values are those specified
through the other labeler parameters. Labels whose positions
(offsets) are not specified will appear immediately below (-Y
direction) and aligned the same as the previous label.
A title string may be used in conjunction with a title file. In
this case, the title string appears first and has the attributes
specified by the other labeler parameters. If a title string or a
title file is used, the input field is ignored and no data labels
will appear.