Help for PIXMAP

PURPOSE

     PIXMAP converts map coordinates to/from vicar pixel coord-
     inates in an IBIS file using a GeoTIFF label to define the
     conversion.  NOTE THAT THE PIXEL COORDINATES WILL BE IN 
     THE VICAR COORDINATE SYSTEM, NOT IN THE GeoTIFF COORDINATE
     SYSTEM.  This allows the pixel coordinates to be used for
     any VICAR operation such as GEOM.
     
     The GeoTIFF label relates the pixel coordinate to the map
     coordinate, but it regards the upper left corner of the 
     image as (0.0,0.0) or (-0.5,-0.5) depending on the type
     of image ("area" or "post").  The PIXMAP program will
     automatically change that in the IBIS file to VICAR pixel
     referencing which regards the upper left corner as (0.5,0.5).
     
     The bottom line is that users will always work with VICAR
     coordinates except when initially setting up the GeoTIFF
     label.
     
     The user only has to name the IBIS file, the file or VICAR
     image containing the GeoTIFF label, the columns involved,
     and the direction of the mapping ('MAPTOPIX or 'PIXTOMAP
     keywords).  None of the keywords are defaulted except that
     only one of the directional keywords is used.
     
TAE COMMAND LINE FORMAT

     pixmap INP=(A,B) MAPCOLS=(E,N) PIXCOLS=(L,S) DIRKEYWORD
     
     where

     A           is an IBIS file 
     B		 is a VICAR image with a GeoTIFF label or a
                      standalone ascii GeoTIFF label
     MAPCOLS     are the IBIS file columns (integers) contain-
                      ing the map coordinates in the same order
                      as the GeoTIFF label (should be East
                      coordinate, then north coordinate)
     PIXCOLS     are the IBIS file columns (integers) contain-
                      ing the pixel coordinates in the order
                      line, sample (backwards from GeoTIFF)
     DIRKEYWORD  is one of the two keywords that tell the 
                      program which way to map
OPERATION
   The GeoTIFF label is accessed and a six coordinate mapping
   is calculated from the point-scale or matrix representation
   of the GeoTIFF mapping.  The inverse mapping is calculated
   for the case of coordinate to pixel conversion.
   
   The transformation is adjusted to convert from/to VICAR pixel
   coordinates as opposed to GeoTIFF pixel coordinates.
   
   The transformation is then applied to the input columns of
   the IBIS file, putting the result in the output columns.
   
   All transformations are calculated in double precision, even
   if the IBIS file is single precision.
   

TIMING

     Should be able to map millions if IBIS records in less than
     a minute.
     
RESTRICTIONS

   The maximum number of coordinate points is limited by IBIS table
   size (currently about 10 million?).  Internal to the program,
   dynamic memory allocation is used.


WRITTEN BY:            A. L. Zobrist, 27 August 1999

COGNIZANT PROGRAMMER:  B. A. McGuffie

REVISIONS: 
Thu Jan  3 2008 wlb switched to USES_ANSI_C AND LIB_CARTO; misc cleanup