AVS Modules						              line probe
NOAA/ERL/Forecast Systems Laboratory


NAME

	line probe - sample a 3D field along a line

SUMMARY

	Name		line probe

	Type		mapper

	Inputs		field, 3D, any-data, any-coordinates
			field, any-data, any-coordinates (optional)
			colormap (optional)
			upstream geom (optional, invisible)

	Outputs		field, float, irregular
			geometry

	Parameters

	    Name		Type		Default		Min Max Choices

	    probe mode		radio		manual		manual, mouse,
								sample file,
								sample field
	    all samples		toggle		off		-
	    probe x		float		0.0		unbounded
	    probe y		float		0.0		unbounded
	    node size		float		0.0		0.0, unbounded
	    probe values	text_block	-		-
	    sample file		browser		$NULL		-
	    sample choices	browser		$NULL		-

DESCRIPTION

	The line probe module can be used to sample a 3D field along one or
	more lines or paths.  The location of the probe may be entered manually,
	indicated by pointing and clicking the mouse, selected from a file of
	sampling locations, or determined by the sampling locations in a second
	field.  If either of the sampling options is used, one sampling location
	may be selected, creating one probe, or all sampling locations may be
	selected, creating multiple probes, one for each sampling location.
	Except for the sample field mode, the probe will be a vertical line
	running through the height of the data volume at a constant X and Y
	position.  By using the sample field mode, the paths of the probes may
	be non-linear, like trajectories.

	If the line probe module has created a single probe, the values found at
	its intersections with each of the fields layers will be listed in a 
	text browser and output as a 1D field.  If multiple probes are created,
	the output field is 2D (one "row" for each probe) but the values are not
	shown in the text browser.  In either case, a polyline geometry object
	is created for the line probe(s) and spheres may be used to show the
	locations of the nodes (sampling points along the probe).  If an
	optional colormap is provided and the field consists of scalars, the
	line probe and its nodes will be colored based on how the values along
	the probe map into this colormap.  If a colormap is not provided or the
	contains vectors, the line probe and its nodes will not be colored.

INPUTS

	Input Field (required, field, 3D, any-data, any-coordinates)
		
	    The input data must be a 3D field of scalar or vector values in 
	    3D space.  Any data type in any grid configuration may be used.

	Input Sample Field (optional, field, any-data, any-coordinates)
		
	    The optional sample field  (computationally 1D, 2D, or 3D) may be
	    used to define the sampling locations of the line probe module.
	    Only the positions of the sample field's data points are used -- the
	    the data values are ignored.  Each computational "row of the sample
	    field defines the path of a single probe.  Consequently, a single
	    line probe module can be used to create any number of probes, each
	    probe following a predefined path which need not be linear -- like
	    trajectory.  This sample field will be used only if the probe mode 
	    is set to sample field.  If the all samples toggle is off, only the
	    first probe path will be used.  If the all samples toggle is on, all
	    of the paths defined by the sample field will be used, each path
	    defining a single probe.

	Input Colormap (optional)

	    If the input data are scalars and an optional colormap is supplied,
	    the line probe geometry object will be colored according to the
	    data values found along the probe and how these values map into this
	    colormap.

	Input Upstream Geom (optional, invisible, upstream geom)

	    To allow operation of the line probe in mouse mode, the Input
	    Upstream Geom port must receive upstream geometry data from the
	    the render geometry module.  Among other things, this data contains
	    the location of the point clicked on by the mouse.  AVS makes this
	    connection automatically when the line probe module is instantiated.

PARAMETERS

	probe mode

	    The probe mode parameter is used to select the method by which the
	    user intends to position the line probe.  In manual mode, the user
	    enters the desired position through the probe x and probe y param-
	    eters.  Mouse mode allows the user to position the probe by pointing
	    the mouse cursor at the desired point and then clicking.  Sample
	    file mode allows the user to select a location from the list of
	    sample locations in the sample file (q.v.).  If the all samples
	    toggle is off, only the one sample location will be used.  If the
	    all samples toggle is on, all of the sample locations in the file
	    will be used, creating one probe for each location.  If the sample
	    field mode is selected, the locations of the data points of the
	    input sample field will become the line probe sampling locations.
	    If the all samples toggle is off, only the first computational "row"
	    will be used, creating only one probe.  If the all samples toggle is
	    on, all of the sample fields "rows" will be used, creating one probe
	    for each "row".  In all modes but the sample field mode, the line
	    probes will be vertical (orthogonal to the computational "K" layers
	    of the data field).  The sample field may be used to define probes
	    that are neither linear nor vertical.

	probe x
	probe y

	    These parameters are used to indicate the horizontal position of
	    the probe.  In manual mode, the user types in the desired location
	    through these parameters.  In all other modes, these parameters are
	    updated with the current location of the probe.  When one of the
	    sample modes is used and all samples is on, the probe x and probe y
	    parameters are meaningless and are shown as zeroes.  In sample field
	    mode, since a probe may define a non-linear, non-vertical, these
	    parameters will reflect the horizontal location of the first point
	    only.

	node size

	    The node size parameter controls the radius of the spheres created
	    at each of the points along the line probe.  A node size value of
	    0.0 disables this feature.

	probe values

	    The probe values parameter is an output-only text browser and lists
	    the values along the probe.  If multiple probes are created (one of
	    the sample modes has been selected and all samples is on) the probe
	    values will not be shown and the text browser will be blank.

	sample file
	sample choices

	    If the sample file mode has been selected, the file specified as the
	    sample file is read and its contents are displayed as the sample
	    choices.  If the all samples toggle is off, the user may then select
	    one of the sample choices and a single probe is positioned at the
	    selected location.  If the all samples toggle is on, all of the
	    choices will be used and a probe will be created at each of their
	    locations.

	    The sample file is an ASCII file, each record (line) of which
	    contains an X and Y coordinate pair, indicating the position of a
	    sample point.  The X and Y values should be separated by white
	    space.  The X value may be preceded by an optional non-numerical
	    label that may be used to identify the sample point to the user.

OUTPUTS

	Output Field (float, irregular)

	    The values found along the line probe are output as a 1D field if
	    a single probe has been created.  If multiple probes have been 
	    created, the output will be a 2D field, with one "row" of the field
	    for each probe.  The grid configuration is always irregular and the
	    data type is always float, regardless of the grid configuration and
	    data type of the input field.  The vector length of the output field
	    is the same as that of the input field.

	Output Geometry

	    A geometry object that contains one polyline for each of the probes
	    is created.  Its name is "line_probe".  If the node size is greater
	    than 0.0, a second object containing spheres at each point along
	    the probe(s) is also created.  This second object is named "line_-
	    probe_nodes" and is a child of "line_probe".  Both of these objects
	    will be colored if the optional colormap is provided.

EXAMPLE

	This first example uses a single line probe to sample a 3D field through
	a point identified on a slice of the field.

		 READ FIELD
		      |
		      |
		      |
		      |        GENERATE COLORMAP
		      |                |
		      +--------------------+
		      |                |   |
	      ORTHOGONAL SLICER        |   |
		      |             LINE PROBE
                FIELD TO MESH              |
		      |                    |
		      +--------------------+
		      |
		RENDER GEOMETRY
		      |
		DISPLAY PIXMAP


	This second example is similar to the first except that it uses a
	second line probe in a second 3D field, collocated with the first,
	to control the position of the first probe.  In this way, two fields
	may easily be probed at the same locations.

		 READ FIELD                           READ FIELD
		      |                                   |
		      |                                   |
		      |        GENERATE COLORMAP      LINE PROBE
		      |                |                  |
		      +------------------------+          |
		      |                |   +-- | ---------+
		      |                |   |   |
	      ORTHOGONAL SLICER        |   |   |
		      |               LINE PROBE
                FIELD TO MESH                  |
		      |                        |
		      +------------------------+
		      |
		RENDER GEOMETRY
		      |
		DISPLAY PIXMAP

LIMITATIONS

	The presence of spheres as the probe nodes may cause the render geometry
	module some difficulty rendering polyline or label objects.  If either
	of these types of objects are to be used in a scene, it may be best to
	disable the probe nodes by using a node size of zero.

	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						              line probe