contour field - contour a 2D scalar field
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