NAME:    probe path - interactive point sample of 3D field with path history

Author:  Ian Curington, Stardent Computer Ltd., Guildford, UK
         0438-505388

Type:    mapper

Inputs:  field 3D any-type any-data
         colormap (optional)
         upstream transform (optional, invisible, autoconnect)
         upstream geometry  (optional, invisible, autoconnect)

Outputs: geometry
         upstream transform (optional, invisible, autoconnect)
         field 1D scalar float (data from sampled path)

Parameters    Name            Type          Default
              Path Accumulate boolean       off
              Pick Geometry   boolean       off

DESCRIPTION

     The probe path module displays the numeric data values in a field at a
     location in space. It works for fields that have been rendered as an
     AVS geometry.  It works for uniform, rectilinear, and irregular
     coordinates, and for any data type.  It works for both scalar and
     vector fields.

     probe path can accumulate the 3D path where the cursor has been,
     showing a coloured line in 3D space of the probe history.
     Three other coloured lines are also shown, where the path is
     "projected" in 2D onto the axis planes. The sampled data
     is also stored along the path, and passed out in the 1D field
     structure. This is typically sent to other filter modules, or
     the graph viewer.

     This probe path module is a variation of the standard "probe"
     module. It is different in that:

         - no sample input
         - trilinear only
         - field output with sampled data value
         - path accumulation
         - position and value in text block, not geometry window
         - axis projection of path

     There are two major ways to use the probe:

	 With the Pick Geometry option off, the "probe" object in the
	 Geometry Viewer acts like any other object.  To find a data value
	 at a particular location in space, you make "probe" the current
	 object and move it to that location.  The movement can be direct
	 manipulation using the usual Geometry Viewer mouse-button commands
	 (e.g.,	right button moves object left and right); or, if that is
	 too awkward and imprecise, you	can use	the Geometry Viewer's
	 "Transformation Selection" panel and have the "probe" object jump
	 to any	absolute or relative point in space. As	the probe travels,
	 it continuously reports its location and the data value beneath it.

	 With the Pick Geometry	option on, data	sampling is more a "point
	 the mouse cursor and click" technique.	Select "probe" as the
	 current object	in the Geometry	Viewer,	point at the object surface
	 you want to sample with the mouse cursor, then	press the left
	 mouse button.	The probe object snaps to the surface beneath the
	 cursor	and reports the	data value.

     The Geometry Viewer tells the probe module	what vertex the	mouse
     cursor was	over when the button was pressed, and probe reports the
     original data value at that vertex in a text-block parameter space.

     When reporting data values	for vector fields, probe lists the values
     of	all the	vector elements. If the	probe is being colored with the
     data values., the color shown is SQRT(vec0**2 + vec1**2 + vec2**2
     ...).

INPUTS

     Data Field	(required; field 3D any-type any-data)
	  The input field is 3D, scalar	or vector, uniform or rectilinear
	  or irregular,	of any data type.

     Colormap (optional)
	  If an	AVS colormap is	supplied to the	center input port, the
	  color	of the probe object in the Geometry Viewer will	change
	  according to the data	value it is pointing at.  I.e.,	if it is
	  pointing at a	"low" value with the default colormap from generate
	  colormap, the	probe object will be blue; it it is pointing at	a
	  "high" value,	it will	be red.

     Upstream Transform (optional, invisible, autoconnect)
	  When the probe and render geometry modules coexist in	a network,
	  they communicate through a normally-invisible	data port.  "Probe"
	  shows	up as an object	in the Geometry	Viewer.	 When you select
	  the probe object and move it,	render geometry	informs	the probe
	  module what the probe's new location is, and the probe module
	  recalculates the location and	data it	is displaying accordingly.
	  This module connection occurs	automatically.	The effect is to
	  give you direct mouse	manipulation control over the probe
	  module's "probe" object.

     Upstream Geometry (optional, invisible, autoconnect)
	  Used by the Pick Geometry's "point cursor and	click" technique,
	  this normally	invisible port is what the render geometry module
	  uses to inform probe of the geometry vertex selected so it can
	  display the data value for it.  The module connection	occurs
	  automatically.

PARAMETERS

     Pick Geometry
	  A boolean switch that	controls whether one moves the "probe"
	  object like any Geometry Viewer object by selecting it as the
	  current object and translating it with mouse button commands or
	  the Transformation Selections	panel (the default, off); or
	  whether one selects data by pointing to an object's verticies
	  with the mouse cursor	and pressing the left mouse button.

RELATED	MODULES
     probes