Help for GTGEN

PURPOSE
     GTGEN is a VICAR applications program which creates a GeoTIFF
     label from parameter input.  This label can be used as a reference
     for numerous VICAR/IBIS operations such as mapping a graphics
     data set or an image.  The label can be examined with the 
     routine GTLIST, including calculated information such as location
     of corner points and pixel size.  The label is coded as a
     part of the state VICAR label.  It can be inserted into an IBIS
     file for graphics or tabular data with routine GTIBIS (not
     available yet).
     
     A special feature of GTGEN is that a three tiepoint set of
     parameters can be converted into a tiepoint-scale or tiepoint-
     transformation-matrix format of GeoTIFF label.  Often, the
     three tiepoints are known or are easier to work with than the
     internal formats of GeoTIFF.  This feature is invoked by the
     keyword TIECNVRT.  If the three tiepoints are not exactly
     rectilinear (which can be proven by using GTLIST on the result)
     and a rectilinear mapping is desired, then the keyword RECTFIT
     can be used to give a best fit (in the least-squares sense)
     that is rectilinear.
     
     If a VICAR file is created with the GEOTIFF parameter but no
     input data sets, then it will be a 1 x 1 image (one pixel)
     that serves mainly as the holder of the GeoTIFF label.  It 
     would also be useful for the 'COVERINP parameter of VICAR
     program GTSIZE or GTWARP.
     
     GTGEN has six modes of operation, so read the help for 
     parameter INP to determine your case.
     
CALL
     gtgen INP OUT '(QUALIFIERS) GEOTIFF
  WHERE:
     INP            is the input data set (may be none, one, or two).
     OUT            is the output data set (may be none, or one).
     QUALIFIERS     consist of any of the following keywords:
          ADD           add the geotiff parameters to an existing label
          TIECNVRT      convert three tiepoint input to tiepoint-scale-
                        model format to indicate that image is mapped
     GEOTIFF        are tag-value pairs that become geotiff parms in
                    the label; each is formatted tag=value.
OR
     gtgen (INP1,INP2) OUT
  WHERE:
     INP1           is a VICAR input data set(s).
     INP2           is a VICAR input data set that has a GeoTIFF
                    label in its state label area.
     OUT            is a VICAR output data set that will be a copy
                    of the first data set with an inserted GeoTIFF
                    label from the second data set.
     
    
OPERATION

For the normal case of creating a label from parameters,
GTGEN processes the input string pairs, turning each into a
GeoTIFF tag-value pair.

The parameter uses only the string format.  Numbers are presented as
strings.  Vectors are presented as a string containing symbols (,,).
etc.  Double quotes must be doubled inside the TAE double quotes
(see example below).  Parenthetical documentation can be added as
part of the strings.

The format is flattened out for VICAR label purposes.  The higher
level descriptors such as GeoKeyDirectoryTag are not used in the
vicar table.  They are restored when an external GeoTIFF label is
created.   The following example is taken from 3.1.1 of the 
GeoTIFF Format Specification REv 1 (see references).

geotiff=("ModelTiePointTag=(0,0,0,350807.4,5316081.3,0.0)", "ModelPixelScaleTag=(100.0,100.0,0.0)", "GTModelTypeGeoKey=1(ModelTypeProjected)", "GTRasterTypeGeoKey=1(RasterPixelIsArea)", "ProjectedCSTypeGeoKey=32660(PCS_WGS84-UTM-zone_60N)", "PCSCitationGeoKey=""UTM Zone 60 N with WGS84""")

For the case of two input files, no parameters are allowed.  The 
program simply places the ascii file key=value pairs into the
VICAR state area.  Multiple occurrences of keys become vectors
in the VICAR state area (since repeats of keys are disallowed).

For the update case of one input, no output data sets... the
geotiff parameter is processed in update mode into the primary
input.  This is the fastest way to process large data sets.

PERFORMANCE

Less than 1 second, except for the case where an output file is
written.  Then the time is mostly copying the output data set.

RESTRICTIONS
------------

Only 100 parameter pairs can be input.  For more, use repeated
calls to GTGEN with the 'ADD parameter after the first call. 

REFERENCES

     Ritter, N., Ruth, M. "GeoTIFF Format Specification, Revision 1.0",
     JPL Cartographic Applications Group.
     
Original Programmer: A. L. Zobrist, 4 Aug. 1999
Current Cognizant Programmer: B. A. McGuffie
Revisions:
  2008-01-11 WLB - switched to USES_ANSI_C AND LIB_CARTO; misc cleanup
  2019-09-05 WLB - IDS-7922 - Initialized variable, cleaned up -Wall warnings

PARAMETERS: