AVS Modules contour field NOAA/ERL/Forecast Systems Laboratory NAME contour field - contour a 2D scalar field SUMMARY Name contour field Type mapper Inputs field 2D scalar, any-data, any-coordinates colormap (optional) Outputs geometry Parameters Name Type Default Min Max Choices safety toggle off - automatic toggle on - manual toggle off - contour interval float 0.0 0.0, unbounded contour minimum float 0.0 unbounded contour maximum float 0.0 unbounded label interval float 0.0 0.0, unbounded label density float 0.0 0.0, unbounded label offset float 0.0 0.0, unbounded label value factor float 1.0 0.0, unbounded label precision float 1.0 0.0, unbounded label height float 0.0 0.0, unbounded label font integer 1 0, 20 label declutter toggle on - labels colored toggle on - triangular grid toggle on - z scale factor float 1.0 unbounded contour data file browser $NULL - DESCRIPTION The contour field module generates contour lines from a 2D field. These contour lines are output as a geometry object with one or more polylines in 3D space and will nest neatly with a mesh surface made from the same field. The contours may be at uniform intervals or at arbitrary levels. If an optional colormap is attached, the contour lines will be colored according to how the values of the contour lines are mapped in the colormap, otherwise, the contour lines are not colored. The contour lines may be optionally labelled. The interval between labelled contour lines may be uniform or, if arbitrary contour levels have been specified, only specified levels will be labelled. A separate geometry object for these labels is output. This allows the properties of the labels to be entirely different from those of the contour lines. However, the labels can be colored by value only if the contour lines are colored by value. Labels will be disabled if any of the following conditions exist: label density <= 0.0 label value factor = 0.0 label height <= 0.0 label font <= 0 If uniform contour intervals have been selected, labels will be disabled if the label interval is zero. Labels may not appear if the label interval is not an integer multiple of the contour interval. Also, with uniform or arbitrary contour intervals, labels may not appear if the label density parameter is set to too high a value. In automatic mode, contour field tries its best to determine from the field appropriate values for contour interval, contour minimum, contour maximum, label interval, label density, label offset, label value factor, and label precision. The 2D fields to be contoured are usually horizontally oriented -- their computational X and Y axes are mapped to be coincident with or parallel to their physical X and Y axes. However, there are many circumstances (like vertical cross-sections) where the computational X or Y axis may be mapped to the physical Z axis. Contour field works equally well with these vertical fields. For the purposes of this discussion, "horizontal" should be taken to mean "parallel to the computational XY plane" and "vertical" should be taken to mean "perpendicular to the computational XY plane". INPUTS Input Field (required, field 2D scalar, any-data, any-coordinates) The input data must be a 2D field of scalar values in 2D or 3D space. Any data type in any grid configuration may be used. Input Colormap (optional) If an optional colormap is supplied, contour lines will be colored according to their values and how those values map into this colormap. If the parameter labels colored is set, labels will be colored the same as their respective contour lines. PARAMETERS safety When set, safety serves as a local "disable flow executive" -- contour field 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 contour field to respond to each one individually. When safety is off, contour field will respond to each parameter or input change as it occurs. automatic manual If the automatic toggle is on, contour field will do its best to determine appropriate values for the following parameters by using the following rules: contour interval (Data max - data min) / 10.0 contour minimum Data minimum contour maximum Data maximum label interval Same as contour interval label density 1/3 the RMS of the fields extents label offset A magic value that increases with the relief of the surface label value factor 1.0 label precision Sufficient to show at least one digit of difference between the data maximum and minimum The widgets for these parameters are updated with the determined values. Each of these parameters has its own manual toggle. If the manual toggle for a parameter is on, its value will not be determined automatically. Instead, the value indicated by the widget will be used. This value may have been determined by a previous pass through contour field or it may be entered manually. If the automatic toggle is off, manual mode is assumed for all of these parameters, regardless of the state of the manual toggles. contour interval contour minimum contour maximum These parameters control the levels of data values that get contoured. If the contour interval is zero, a single contour will be generated at the contour minimum if the minimum is less than the maximum. Otherwise, if the contour maximum and minimum are equal, the entire range of data values will be contoured with ten intervals. This feature is convenient for contouring fields whose range of values is unknown. If contour line labelling is enabled, this feature will label EVERY contour line, ignoring the non-zero label interval. If the contour interval is not zero and the contour minimum is less than the contour maximum, the first contour will be at the contour minimum and successive contours will be generated at intervals of the contour interval until the last level that is less than or equal to the contour maximum has been contoured. If the contour interval is not zero and the contour minimum is equal to the contour maximum, the field data is scanned to find the minimum and maximum values which are integer multiples of the contour interval. Contours are then generated within this range and at intervals of the contour interval. If the contour minimum is greater than the contour maximum, regardless of the contour interval, arbitrary contours are created at the levels specified in the contour data file (q.v.). These contouring rules are summarized in the following table: int == 0 int != 0 ----------------+-----------------------+------------------- | | min < max | min only | min thru max | | ----------------+-----------------------+------------------- | | min = max | data min thru max | data min thru max | with 10 intervals | ----------------+-----------------------+------------------- | | min > max | from data file | from data file | | ----------------+-----------------------+------------------- label interval The interval separating contour lines that will be labelled. This value should be an integer multiple of the contour interval, otherwise contour labelling may be erratic or non-existent. If this value is zero, labels will be disabled. This parameter is ignored if contouring data is read from a contour data file (q.v.). label density The distance between labels on the same contour line is controlled by the label density parameter. The units of measure of this density are the same as that of the horizontal coordinate system of the data field. A value of half or a third of the field "width" is usually a reasonable number to start with. If this value is zero, labels will be disabled. label offset On an uneven surface, the labels may be wholly or partially hidden when they penetrate the higher terrain surrounding them. By offsetting the labels from the surface, their legibility will be increased. This parameter is the offset of the labels from the surface of the data field and its units of measure are the same as that of the vertical coordinate system of the data field. If this value is not zero, the labels will be connected to their respective contour lines by "pins" (disjoint line segements). label value factor The values displayed by the contour labels are multiplied by this factor to get the actual data value. The label value factor in no way affects the data or contour values -- only the label values are affected. If this value is zero, labels will be disabled. label precision This parameter controls the precision of the values displayed as the contour labels. 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 value to the nearest tenth; 0.01, to the nearest hundredth; etc. label height The height of the contour label characters is given in window- relative terms. The display window is two units high and wide, so a label height of 1.0 would produce labels that were half as tall as the window (very large!). Much smaller values (like 0.05 or so) should be used. If this value is zero, labels will be disabled. label font Contour field uses the AVS labelling capabilities to generate contour labels. These capabilities vary from platform to plat- form, and therefore, so do the labelling capabilities of contour field. This parameter identifies the character font to be used. The number of fonts on a platform depends on the number of type face styles that are available and whether or not they are avail- able in bold or italic styles. If this value is zero, labels will be disabled. label declutter Some platforms have the ability to mask out the background area around labels. In a congested area, it may be very difficult to read all of the labels. Invoking this masking, or decluttering, ability may improve the legibility of some of the labels in these cluttered areas. labels colored If an optional colormap has beed supplied, the contour lines will be colored according to how the values of the contour lines are mapped into the colormap. If labels colored is set, the labels will likewise be colored, otherwise the labels will not be colored. The property editor of the geometry view may be used to color the contour lines (as a group) and the labels (as a second group). The label pins have the same colors as their labels. triangular grid When field to mesh (or similar modules) generates a mesh surface from a field, the grid cells are divided into triangles. If the contours generated by contour field are to fit such a surface well, a similar triangular interpolation scheme must be used. The triangular grid toggle provides this capability. If it is set, a triangular grid is used, otherwise a bilinear scheme is used. The bilinear scheme will work well if the surface is fairly flat, or there is no surface at all to match. The bilinear scheme is also slightly faster and may produce smoother contours. z scale factor The third dimension of the coordinate system (usually the Z dimension) may be scaled to synchronize with a similar capability found in other modules (like field to mesh). A value of zero simply flattens all of the contours, nesting them on to a single plane. contour data file If the contour minimum is greater than the contour maximum, a file browser widget appears. This widget is used to specify the name of an ASCII file that contains the contouring and labelling data. Each record, or line, of this file contains the value of a data level to be contoured. These levels must be in ascending order. If the contoured level is to be labelled, its value is followed by white space and then a non-blank character, all on the same line. This features allows the contouring of totally arbitrary or non-linearly related levels. The following example illustrates how to specifiy contour levels that are powers of 2: 2 4 8 * 16 32 64 * Note that only the contours for 8 and 64 will be labelled. OUTPUTS Output Geometry An object named "contour lines" consisting of one or more polyline objects is created for the contour lines. If labels are produced, a second object named "contour labels" is created as a child of "contour lines". If the labels have been offset from the surface of the field, a third object, named "contour label pins", is created as a child of "contour labels". This third object consists of disjoint lines that connect the labels with their contour lines. EXAMPLE This example produces a mesh from a field as well as contours of the field data. The contour lines fit the surface of the mesh. READ FIELD | +---------+----------+ | | CONTOUR FIELD FIELD TO MESH | | +---------+----------+ | RENDER GEOMETRY | DISPLAY PIXMAP LIMITATIONS If the data is of dubious repute and there is the remotest chance that it might contain humongous spikes or pits, the option using a specified interval and the data minimum and maximum should not be used. Doing so will burn up a lot of time and memory making a lot of itty bitty contours of the spikes and pits. 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 contour field