Help for LGEOM

PURPOSE:
     LGEOM is a VICAR applications program which makes geometric
     changes in pictures.  It can be used for correcting geometric
     distortion, increasing picture size, and reducing picture
     size.  LGEOM should be used instead of MGEOM if any output
     line is rotated more than 85 degrees from its input position.
     It uses an intermediate data set which is created and deleted
     automatically, unless the entire input picture fits in memory.
     In this case, LGEOM operates in a one-pass mode.  Memory is 
     dynamically allocated with STACKA.
EXECUTION:

     lgeom (INPUT,PDS) OUTPUT SIZE QUALIFIERS TIEPOINTS
WHERE
     INPUT          is the input data set.
     PDS            is an optional parameter and tiepoints dataset 
                      created by program MAP.  (Except for in MAP2,
                      LGEOM is almost always run with the PARMS parameter
                      as the means of entering the TIEPOINT, NAH, and NAV
                      parameters.)
     OUTPUT         is the output data set.
     SIZE           is a VICAR size field for the output set
     QUALIFIERS     consist of any of the following parameters
	  IDSNAM	indicates an alternative name for the
			itermediate data set (IDS)
	  IDSNS		indicates an alternative line size for IDS
          NOIN          indicates no interpolation is to be done
	  NOIZ		indicates no interpolation with zero DN values.
     TIEPOINTS      is a collection of parameters as follows:
	  NAH		The number of (tiepoint) rectangles in the horizontal
			direction (Number of areas horizontal)
	  NAV		The number of rectangles vertically.
	  TIEPOINT	A set of points mapping the rectangles in the
			output picture to quadrilaterals in the input
			picture.  For details, see help under the
			TIEPOINT parameter.
           or
                        PDS, but in the new VAX format).  
                        LGEOM is almost always run with the PARMS parameter
                        as the means of entering the TIEPOINT, NAH, and NAV
                        parameters.

Tiepoint rectangles need not be defined for the entire picture.
If an area of the picture is not within a defined rectangle, it is geomed 
using parameters from the nearest defined rectangle. Thus, in order to have 
a portion of the input picture reproduced exactly in the output, it is 
necessary to define a rectangle with zero displacement around the area.

If the output picture does not fill the area reserved for it by the
SIZE parameter, the pixels in the unfilled area are given the value zero. 
If the size field is defaulted, the output picture will be the same size as 
the input picture.

The default mode for LGEOM is four-point bi-linear interpolation;
i.e. the output pixels will be a function of the DN values of the four
points in the input picture closest to the fractional line and sample
calculated by the specified transformation.

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 size field parameters refer to samples, 
even for halfword data.  For example, the following
will enlarge a 100 line by 100 sample (200 bytes) halfword data set A to 216 
lines by 150 samples (300 bytes).
	lgeom A B SIZE=(1,1,216,150) NAH=1 NAV=1  	 TIEPOINT=(1,1,1,1, 1,100,1,150, 100,1,216,1, 100,100,216,150)

The keyword NOIN can be used to specify no interpolation. In this
case the DN value of the point closest to the fractional line and sample
is used. This method (sometimes referred to as "nearest neighbor") is
somewhat faster, but is not as accurate as the four point interpolation.

The keyword NOIZ can be used to specify no interpolation with DN values of
zero.  This is used when zero represents missing data and you do not want
to interpolate at the boundary of good data and missing data.

LGEOM may accept parameters from disk as a second input file. 
This is the method used in the MAP2 procedure.  The format
of this disk data set is a single record consisting of NP+1 words, where
NP is the number of words of actual parameters and the first word contains
NP. This is an optional data set.

The common usages of LGEOM are within procedures such as MAP2 and MAPTRANS,
or following such programs as PICREG, RG, TIECONM, or TIEPARM.  TIEPARM, for
example, could be used to convert tiepoints in an IBIS interface file into
a VICAR PARMS file that could be entered as the PARMS parameter in the
LGEOM command line.
EXAMPLE

tieconm OUT=TIEPARMS 'LGEOM NAH=40 NAV=40            MINL=1.,MINS=1.,MAXL=3000.,MAXS=3000.           TIEPOIN=(1,1,1,1, 1,3000,1,10, 3000,1,10,1, 3000.29,3000,10,10) 
lgeom LGTEST LGENLARG SIZE=(1,1,3000,3000) PARMS=TIEPARMS

     In this example,  the tiepoints are used to set up a 3000
     x  3000 grid for use by LGEOM.   The tiepoints given to TIECONM
     can  be scattered  over  the  image  in  any  fashion   whereas 
     LGEOM requires a regular grid.
LIMITATIONS:

  A. When a second input dataset is used to enter the rectangles (MAP),
     a maximum of 400 rectangles can be used.  When the TIEPOINT or PARMS
     parameter is used, the number of rectangles is unlimited.  However,
     the TAE maximum count of 32767 limits the number of rectangles to 8192.

  B. The maximum number of samples per line in the output file is 32767.

  C. Since STACKA is used to allocate memory, the maximum picture size
     is unlimited.  When very large pictures are used, the page file quota
     must be large enough to accomodate a buffer used to map the blocks
     in the Intermediate Data Set.  The number of bytes in this buffer is
     6 times the estimated number of blocks in the Intermediate Data Set.
     (The RATIO parameter can be used to change the estimated number of
     blocks.)

  D. The output tiepoint coordinates must be whole numbers.  Users rarely
     need to know of this restriction since the TIEPOINT parameter is
     usually generated by another VICAR program.  Users only need to be
     concerned about this if they are actually entering specific values
     for the TIEPOINT parameter for the LGEOM command line.

RECORD SIZE OF INTERMEDIATE DATA SET FOR LGEOM (IDSNS):

The optimum size of the intermediate data set (IDS) for LGEOM is a
function of the number of rectangles, input and output sizes, and the
available buffer space.

In general, the IDS record length should decrease as the number of pixels
in the output file increases.  The number of lines needed for IDS is 
calculated inside the program.

 TIMING: 
  The following CPU times for LGEOM was obtained on a 
VAX 8650 (MIPL2) in May 1993
			                                                CPU Time
gen LGA1 NL=1000 NS=1000 IVAL=0 
!
! Now do 1.2 times enlargement of a BYTE image IN 1 PASS
lgeom LGA1 LGA2 SIZE=(1,1,1200,1200) NAH=1 NAV=1 'PRINT    TIEPOIN=(1,1,1,1, 1,1200,1,1000, 1200,1,1000,1, 1200,1200,1000,1000) 
!  				5-93  SP  CPU TIME ON MIPL2 (VAX8650)    28.53s

For more information, see the file timelgeom.pdf in lgeom.com.
WRITTEN BY: Howard J Frieden		22 December 1970

COGNIZANT PROGRAMMER: Howard J Frieden	 9 November 1990

PORTED TO UNIX: Steve Pohorsky

 REVISION HISTORY

  93-5-26   SP   Made portable for UNIX.  Gave control over progress messages 
                 to PRINT parameter.  Added PMEM parameter for UNIX.

PARAMETERS: