Help for MGEOM

PURPOSE
     MGEOM is a VICAR applications program which makes geometric
     changes in pictures.  It can be used for many purposes including
     correcting geometric distortion, increasing picture size, reducing 
     picture size, and rotating a picture.  The ported MGEOM uses a 
     different algorithm than the unported MGEOM and has different
     characteristics.  The following are the principal differences
     with respect to the programs LGEOM and GEOMA (note the difference
     with the claims of the unported MGEOM):

	1. MGEOM is NO LONGER as fast or faster.
	2. MGEOM and GEOMA are more accurate as of April 1996.
           LGEOM should have comparable accuracy soon after.
	3. Preparation of "sharp edges" for mosaicking appears to
           be available using ZNOIN (MGEOM) and NOIZ (LGEOM).
           It appears that LGEOM is better at this.
	5. No limits on size of input/output pictures in MGEOM.
	6. No limits on size of interpolation grid in MGEOM.
	7. MGEOM now has "bad cases" involving excessive rereading of files.

     The unported version of MGEOM had the following requirement:
	1. Maximum allowed rotation is 85 degrees.
     I do not believe this to be the case with the ported version.


CALL
     mgeom INPUT OUTPUT SIZE '(QUALIFIERS) TIEPOINT-GRID
  WHERE:
     INPUT          is the input data set.
     OUTPUT         is the output data set.
     SIZE           is a VICAR size field for the output file
     QUALIFIERS     consist of any of the following keywords:
          NOIN          no interpolation is to be done.
          ZNOIN         no interpolation for points with 0 DN.
     TIEPOINT-GRID      is a collection of parameters as follows:


     The TIEPOINT-GRID is a set of points describing the relation
of the output file to that of the input file using the keywords
NAH, NAV, and TIEPOINT.
   NAH=nah  NAV=nav
     tiepoint=(nl1,ns1,ol1,os1,nl2,ns2,ol2,os2,...
                   ...nlk,nsk,olk,osk)

where the grid is rectangular in the output image space, nah is
the number of grid cells horizontally (across the top in the sample
direction), nav is the number of grid cells vertically in the output
image space, the point pairs (nli,nsi,oli,osi) are line-sample
coordinates in the output (new) and input (old) spaces respectively.
the number of pairs k must equal (nah+1)*(nav+1).  The grid must be
perfectly rectangular in the output image space (the rows and
columns must be perfectly horizontal and vertical respectively).

The input image may either be byte or halfword data.  The data format is taken
from the VICAR label of the input file.  The output image has the same data 
format (byte or halfword) as the input image.  

The HELP for program GEOMA has additional details.

     For those used to the unported version, note that there used
to be an output file parameter, IDS.  I.e. you used to have to
specify an intermediate data set.  This is no longer the case
with MGEOM.  Also, for a non-uniform tie point grid, there used
to be an 'HVARY qualifier.  Non-uniform spacing of tie points is
no longer a special case, so the HVARY parameter is now obsolete.
However, for backwards compatability, you can still specify the
parameter; it will simply be ignored.

OPERATION

MGEOM uses a moderate amount of space in its calculation arrays.  The
program implements a recursive tiling scheme so that it only loads a
fraction of the input file into memory if the entire input file is too
large.  However, this tiling scheme should be transparent
to the user.

PERFORMANCE

Each cell of the tiepoint grid is a separate tile (or more than 1) in this 
algorithm with its own set of disk reads and writes.  For a typical tiepoint
grid, this may result in a large time (elapsed wall-clock time) spent on 
disk I/O.

For example, the following statistics were obtained on an Alpha (coda2) for
the case of a BYTE input image with a size of 1024 lines by 1024 samples and
a tiepoint grid with NAH=9=NAV (smaller than typical).

             CPU TIME     WALL-CLOCK (CONNECT) TIME
LGEOM          1.34s       2.89s
MGEOM          3.45s      22.75s

The number of disk reads and writes is proportional to NAH*NAV.  The defaults
from PICREG are NAH=20=NAV.
Restrictions
------------

Warning:  If "nl" or "ns" exceeds the grid corner tie points, the interpolation
algorithm may become unstable and cause the program to crash.  It is advised 
that the user limit the number of output lines and samples to the grid corner
tie point limits. 
Original Programmer: A. L. Zobrist, 6 Dec. 1979
Complete scratch rewrite: S.V. Hwan, 8 Nov. 1994
Current Cognizant Programmer: B. A. McGuffie