AVS Modules labeler NOAA/ERL/Forecast Systems Laboratory NAME labeler - create labels from strings or field data SUMMARY 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 - DESCRIPTION The labeler module may be used to create label objects from field data or from arbitrary text. Fields from which data labels are derived may contain data of any vector length and of any dimensionality. Scalar values may be translated into arbitrary character strings by using a value translation file. Title labels may be created from a single string entered through the module control panel or may be created from the text and attributes contained in an ASCII title file. Title labels may be fixed in the display window or attached to points in the object space. Title labels of this latter type are referred to as "object" labels. Object labels may be specified only through a title file. Object labels and data labels may be offset from their reference points. "Pins" may be used to connect these labels to their reference points. Labels may be colored individually, colored uniformly, or uncolored. Each instance of a labeler module will create either data labels or title labels (including object labels), but not both. INPUTS 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. PARAMETERS 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. OUTPUTS Output Geometry A label object named "labeler_labels" is created and contains all of the data or title labels. If data or object labels have been created and the show pins parameter is on, a second object named "labeler_label_pins" is created as a child of "labeler_labels". EXAMPLE This first example slices a 3D field and places data labels at each of the grid points in the 2D slice. READ FIELD | GENERATE COLORMAP | | | +---------+ | | ORTHOGONAL SLICER | | | | | | | +-------------+ | | | LABELER | | | +-------+ | RENDER GEOMETRY | DISPLAY PIXMAP This second example uses labeler simply to label the display with the name of the field file read by read field. Note that the read field Read Field Browser parameter and the labeler text string parameter need to be made visible with the Module Editor. FILE BROWSER | | +--------+ | | | READ FIELD | | | GENERATE COLORMAP | | | | | ORTHOGONAL SLICER | | | | LABELER | | +---------------+ | RENDER GEOMETRY | DISPLAY PIXMAP LIMITATIONS Since the labeler module uses the labeling capabilities available through AVS and these capabilities vary from platform to platform, the labeler module performance and capabilities will also vary from platform to platform. This module has been used with uniform and "nice" irregular fields. It has not been tested with anything really weird. AUTHOR Phil McDonald, NOAA/ERL/Forecast Systems Laboratory NOAA/ERL/Forecast Systems Laboratory AVS Modules labeler