Help for ZINTERP


PURPOSE

	Interpolate elevation values from random control points
	into a rectangular grid (A "surface" image).


TAE COMMAND LINE FORMAT

	zinterp INP=3DCPTS.INT OUT=SURFACE.IMG NL=250 NS=300  		FORMAT=BYTE LINECOL=1 SAMPCOL=2 ZCOL=3 RADIUS=15.0  		RADEXP=10.0 EXPONENT=2.5 NUMN=5 LOFFSET=250  		SOFFSET=-50 ZOFFSET=1000 LSCALE=1.5 SSCALE=.75  		ZSCALE=.875 TRON=20 TRONMODE=1

EXAMPLES

	zinterp INP=CPTS OUT=SURF NL=150 NS=150 NUMN=10 ZOFFSET=500

	This will create a surface image 150 square. The default
columns in the interface file for the Line, Sample and Z values
of the control points (1,2,3) are employed. The number of nearest
neighbors (NUMN) option is set to 10 which means that for every
pixel in the surface image the 10 closest control points will
influence the determination of the Z value. A value of 500 is added
to the Z value of each control point. Sinze the Z value will exceed
255, the output data set will automatically be set to HALFWORD.

	zinterp INP=CPTS OUT=SURF NL=200 NS=100 RADIUS=25 RADEXP=10

	The same defaults apply to this example with the exception that
the search mode is set to a radial distance from each pixel instead of
nearest neighbor. This distance is set to 25 units away from each pixel.
If not enough points (there is an internal default of 5 points within
radial search mode) are found within the radius, then the radius is
increased by RADEXP (in this case 10) until enough points are found.

	zinterp INP=CPTS OUT=SURF NL=250 NS=250 FORMAT=BYTE  		LINECOL=14 SAMPCOL=10 ZCOL=1 ZSCALE=1.5 TRON=20

	This example will create a surface image 250 square using the
default value of 5 nearest neighbors for each pixel. The columns that
contain the values of the control points are given explicitely: column
14 - line value; column 10 - sample value; and column 1 - the Z value.
All Z values in the control points will have a scale factor of 1.5
applied before usage. The TRON (TRace ON) option will notify the user
after every 20% of the output image is created. If any Z values exceed
255, they will be set to 255 in the output image since the FORMAT was
requested to be BYTE.

OPERATION

	It is recommended that control points not form clusters or be
	positioned in obvious linear allignments (such as gathering
	control points close together along a contour line from
	a topographic map). Typically, 7 nearest neighbors is
	sufficient to interpolate a synthetic surface of reasonable
	quality. More than 7 will only modify the surface slightly
	at the expence of CPU cycles. The control points sould be
	scattered evenly throughout the region of interest.

	The interpolated values are stored in two locations:
	BUF and a local cache. The cache consists of two arrays,
	NHDIST and NHELEV.  If sufficient points are found in the 
	cache, then interpolation uses just these values.  If 
	the cache is too small, then the elevations in BUF are
	sorted to generate the values for interpolation.

	The cache is used to improve performance in the most common
	cases (large numbers of control points and neighborhood sizes
	of fewer than 100 points). Sorting of elevation values by
	by distance takes increasingly more time as the number of
	control points increases.

	If a radial search is used, the maximum size of the cache is a
	function of the desired sample size.  The value for NMAX is set
	to SFACTR * NUMN.

RESTRICTIONS



	Number of control points must be >= sample size
	Number of nearest neighbors should be around 7 (+-3)
	Maximum number of nearest neighbors is 32
	In the collection of control points, caution should
	be excersized to avoid clustering of control points.

REFERENCE

	See SYMAP USER'S REFERENCE MANUAL (Harvard University Laboratory
	for Computer Graphics and Spatial Analysis, 1977) Section III,
	pages 33 through 36 - Discussion and documentation on the use of
	the SEARCH RADIUS, NUMBER of DATA POINTS (nearest neighbors), and
	the INTERPOLATION GRID.

	See Mark S. Monmonier, COMPUTER-ASSISTED CARTOGRAPHY Principles
	and Prospects (Englewood Cliffs, N.J.: Prentice Hall, Inc., 1982)
	Chapter 3 "Raster Symbols and Surface Mapping" Section titled "GRID
	INTERPOLATION" pages 58 - 65.

HISTORY

        31 OCT 1994  AMS  (CRI)  Made portable for UNIX
        21 NOV 1994  AMS  (CRI)  Added initialization of RADIAL for ANDES

VALID DATA RANGES / DEFAULT VALUES

	VARIABLE	    VALID VALUES	    DEFAULTS 
	========	    ============            ========

	NUMN 		    0 through 32		 5
	EXPONENT 	 .001 through 10.0 		2.0
	LOFFSET 	       any			0.0
	SOFFSET 	       any			0.0
	ZOFFSET 	       any			0.0
	LSCALE		.0001 through 999999. 		1.0
	SSCALE		.0001 through 999999.		1.0
	ZSCALE		.0001 through 999999.		1.0
	LINECOL 	   1 through 40			 1
	SAMPCOL 	   1 through 40			 2
	ZCOL 		   1 through 40			 3
	TRON		       >=1			 0 (off)
	TRONMODE	      1 or 2			 1  (%)


PRECISION:
  The precision of values in fullword output images is limited to six
significant digits because "zinterp" converts all numeric values to real
format before performing computations.  The variation in fullword values that
can be expected on different MIPS-supported machines shall not differ by
more than 1 in six significant digits.
"zinterp" now has a very slight difference from the unported version to
improve portability and agreement of results on different machines.  The 
reason for this change is to handle a probably infrequent case where "zinterp"
encounters a tie for the last place in the set of NUMN points from the input
file used in interpolating a "z" value.  In such a case there are two points
(with different "z" values) competing for inclusion in the set of points used
in the interpolation.  These two points will be equidistant from the output
pixel currently being handled by the program.  To prevent this tie from being
broken unpredictably by floating point round-off and thus varying from
machine to machine, "zinterp" uses a simple tiebreaking scheme that ignores
all but the first point in a tie for last.  ("zinterp" processes the control
points in order of ascending line value.  The tiebreaking scheme can be found
in the source code by searching for the phrase "break ties".) Since in this
case the set of NUMN closest points is poorly defined, the difference from the
unported version (see the test pdf, for example,) is justified and has a
magnitude on the order of the difference caused by increasing NUMN by 1.