AVS Modules						             wire bender
NOAA/ERL/Forecast Systems Laboratory


NAME

	wire bender - bend 2D or 3D line vectors to conform to the surface
	              of a 2D field

SUMMARY

	Name		wire bender

	Type		mapper

	Inputs		geometry (optional)
			field 2D scalar, any-data, any-coordinates (optional)

	Outputs		geometry

	Parameters

	    Name		Type		Default		Min Max Choices

	    clip		toggle		on
	    regrid		toggle		on
	    vector file name	browser		$NULL
	    z scale factor	float		1.0		unbounded

DESCRIPTION

	The wire bender module bends line vectors to conform with a surface
	defined by a 2D field.  The source of the input vectors may be either
	a geometry object or an ASCII vector file.  If no field is specified,
	the input vectors are passed through unmodified, retaining their
	original 2D or 3D shapes.

INPUTS

	Input Geometry (optional)

	    The input for wire bender may be objects composed of disjoint line
	    segments or polylines.  This line object may exist in 2D or 3D
	    space but should have been generated from a 2D field.  Using 3D
	    objects like those that define polyhedra will cause unpredictable
	    results.  However, objects like those generated by hedgehog, show
	    flow, and contour field will work quite well.  The input geometry
	    object will be used only if no vector file name has been specified.

	Input Field (optional, field 2D scalar, any-data, any-coordinates)
		
	    The input field must be a 2D field of scalar values in 2D or 3D
	    space.  Any data type in any grid configuration may be used.  Wire
	    bender assumes that the surface to which the wires must conform
	    is the surface of this field that would come from a module such as
	    field to mesh.  If this field is omitted, the input vectors will
	    be passed through wire bender unmodified, retaining their original
	    2D or 3D shape.

PARAMETERS

	clip

	    The input line vectors will be clipped to the limits of the input
	    field if the clip parameter is set.  If no field is input, the clip
	    parameter has no effect.

	regrid

	    In order for the line vectors to conform as closely as possible to
	    a surface generated from a field, the vectors need to be broken
	    into smaller segments at the points where they cross the grid lines
	    of the surface grid.  This regridding is accomplished by setting
	    the regrid parameter to on.  If the line vectors are to be used 
	    in conjunction with a flat surface or the lines have been generated
	    with this grid in mind (as is the case with the lines from contour
	    field), regridding is not necessary.  If no field is input, the
	    the regrid parameter has no effect.

	vector file name

	    The line vectors to be bent may come through the input geometry
	    port or from the ASCII file whose name is specified by the vector
	    file name.  Each record (or text line) of the vector file contains
	    data for a single point along the vectors being defined.  The
	    format of these records is:

		IFIRST    X    Y    [Z]

	    where IFIRST is an intger whose value is 1 to indicate that the
	    point is the first point of a line or 0 to indicate that the point
	    is a continuation of a line.  Following IFIRST are the floating-
	    point values of the X and Y coordinates for 2D vectors or X, Y, and
	    Z for 3D vectors.  These coordinate values should be in grid unit
	    values.  That is, for a field whose dimensions are NX by NY, the
	    X values range from 0 to NX-1; Y values from 0 to NY-1.  If a
	    valid vector file name is specified, any input geometry is ignored.

	z scale factor

	    The third dimension of the coordinate system (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 line vectors onto the Z = 0 plane.

OUTPUTS

	Output Geometry

	    If the source of the vectors is a vector file, an object named
	    "wires" will be created.  Otherwise, if an input geometry is the
	    source of the vectors, the name of the output geometry object will
	    be the same as that of the input object.

EXAMPLES

	This first example bends the vectors in the specified file to conform
	with the surface generated by field to mesh.

		           READ FIELD
		                |
		      +---------+----------+
		      |                    |
		FIELD TO MESH         WIRE BENDER
		      |                    |
		      +---------+----------+
		                |
                         RENDER GEOMETRY
                                |
                          DISPLAY PIXMAP

	This second example bends the contour lines of one field to conform
	with the surface of a second field.

		           READ FIELD            READ FIELD
		                |                     |
		      +---------+----------+    CONTOUR FIELD
		      |                    |          |
		      |                    |   +------+
		      |                    |   |
		FIELD TO MESH         WIRE BENDER
		      |                    |
		      +---------+----------+
		                |
                         RENDER GEOMETRY
                                |
                          DISPLAY PIXMAP

LIMITATIONS

	Although the coordinates of the vector points may follow any grid type
	(uniform, rectilinear, or irregular), their values should follow the
	style of uniform coordinates.  That is, for a field whose dimensions
	are NX by NY, the X values range from 0 to NX-1 and the Y values range
	from 0 to NY-1.

	Input geometries (with the exception of those from contour field)
	should contain only polytriangle objects composed of polylines or
	disjoint lines and none of these lines should be vertical.

	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						             wire bender