-------------------------------------------------------------

          Manual for Libgeotiff Library and Utilities

-------------------------------------------------------------

Documentation Author: Niles Ritter
Last Modified: 31 Jul 95
  
See: http://www.remotesensing.org/geotiff/api/index.html 
  for up to date API documentation
  
-------------------------------------------------------------
Contents:

  1. The LibGeoTIFF library
  
     1.1 Preliminaries
     1.2 Calling Sequences
	 1.3 Examples

  2. The LibGeoTIFF Utilities
  
     2.1 listgeo   - dump a GeoTIFF metadata file
	 2.2 geotifcp  - install GeoTIFF from metadata

-------------------------------------------------------------
1. The LibGeoTIFF library

-------------------------------------------------------------
1.1 Preliminaries

-------------------
1.1.1 Compliance:

    ANSI-C:  The GeoTIFF library is fully ANSI compliant and
	   should compile under any ANSI compiler. It is not guaranteed
	   to compile under K&R compilers.
	
	C++:   All headers have the appropriate C++ bindings permitting
	   the correct linkage to C++ routines.
	   
-------------------
1.1.2 Interfaces:

	xtiffio.h: the primary interface header file for all TIFF
				routines, using the extended GeoTIFF tags.
				
	geotiffio.h: the primary interface header file for all GTIF 
				 routines, keys and code values.

	geotiff.h:  an interface header file for all GTIF 
				 routines, if code values are not required.

	geokeys.h:   defines all valid GEOTIFF GeoKeys.
	
-------------------
1.1.3 Defined macros:

  All of the tag, key and key-value symbolic names in the GeoTIFF spec are
  supported and defined by the inclusion of "geotiffio.h". In addition,
  the following useful values are defined:
  
	GvCurrentVersion:  The current GeoTIFF Directory version. Should always be 1.
	GvCurrentRevision: The current GeoTIFF Key Revision.
	GvCurrentMinorRev: The current GeoTIFF Key-Value (minor) Revision.
	
	KvUndefined:      The universal Key value for "undefined" items.
	KvUserDefined:    The universal Key value for "user-defined" items.

	
-------------------
1.1.4 Defined Types:  

	TIFF             the type of a TIFF file descriptor (if LIBTIFF is used).
	GTIF             the type of a GeoTIFF file descriptor.
	GTIFPrintMethod  the type of a print method passed to GTIFPrint().
	GTIFReadMethod   the type of a read method passed to GTIFImport().
	geokey_t         the type of a GeoTIFF key variable.
	tagtype_t        the type of a TIFF tag variable, such as TYPE_DOUBLE.


-------------------
1.1.5 Key and Code Databases:

	All geokeys are defined and named in the database file
	"geokeys.inc", which in turn is included in "geokeys.h"
	and several other files. The symbolic enumerated names are identical
	to those used in the Appendix of the GeoTIFF spec.
	
	The geokey code values are stored in the other database files
	having the ".inc" suffix, which in turn are all referenced by
	the file "geovalues.h". The ones with names beginning with
	"epsg_" are codes registered in the EPSG/POSC tables, while
	those beginning with "geo_" are specific to GeoTIFF.
	

-------------------------------------------------------------
1.2 Calling Sequences

-------------------
1.2.1 TIFF-level interface


1.2.1.1  GTIFNew  -- Set up a new GeoTIFF file Descriptor
	GTIF*     GTIFNew(void *tif);

GTIFNew() takes an existing TIFF file descriptor and creates
a GTIF GeoTIFF file-I/O object for reading and writing
GeoTIFF keys and values. The TIFF file must currently be open,
though it may be either read or write mode.


1.2.1.2 GTIFFree
	void      GTIFFree(GTIF *gtif);

Destroys the GeoTIFF file descriptor following reading or writing
the keys.


1.2.1.3 GTIFWriteKeys
	int       GTIFWriteKeys(GTIF *gtif);

This routine must be called for a new GeoTIFF file after all of 
the desired Keys are defined and set with GTIFSetKey(). This does
not explicitly write anything out to the file, but it does call
the TIFF-level routines to install the TIFF tag values, which
in turn are written to the file when the TIFF file descriptor
is closed. A GeoTIFF file cannot be opened for updating; only
pure read or write is supported.


1.2.1.4 GTIFDirectoryInfo
	void      GTIFDirectoryInfo(GTIF *gtif, int *versions, int *keycount);

Returns header information about the GeoTIFF file directory. The <versions>
is an array of 3 integers, giving the GeoTIFF Version, followed by
the major and minor revisions. The <keycount> argument returns the number
of keys currently defined in this file. 

-------------------
1.2.2 GeoKey Access 


1.2.2.1 GTIFKeyInfo
	int       GTIFKeyInfo(GTIF *gtif, geokey_t key, int *size, tagtype_t* type);

Returns the number of values defined for key <key> if currently defined in the file, and 
returns in <size> the size of individual key values, and the <type>. If the
key is not defined, 0 is returned. You may pass in NULL pointers to any parameters
you do not need (such as the type).


1.2.2.1 GTIFKeyGet
	int       GTIFKeyGet(GTIF *gtif, geokey_t key, void *val, int index, int count);

Accesses the key value(s). If there are multiple values (such as ASCII), they
may be accessed individually, starting at <index> and returning <count> values.
The total number of values accessed is returned. Note: unline TIFFGetField() 
memory is not allocated for multiple-value arrays such as ASCII. To get the
length of an array call GTIFKeyInfo first, which returns the size and count
of the data.  If the values are key-codes they should be declared of type
"geocode_t", which is unsigned SHORT.


1.2.2.1 GTIFKeySet
	int       GTIFKeySet(GTIF *gtif, geokey_t keyID, tagtype_t type, int count,...);

Defines and sets the specified key values. Note that this does not install the
tag-level information in the file; to do that you must call GTIFWriteKeys().
For single-valued non-ASCII keys (which are most of them), you must pass the
values in by value not reference. You must use the correct type for the
values: doubles for floating point, strings for ASCII, and "geocode_t" for
SHORT codes (the symbolic names may be used in most cases).


1.2.3 Metadata Import-Export utilities 

	void      GTIFPrint(GTIF *gtif, GTIFPrintMethod print, void *fd);
	int       GTIFImport(GTIF *gtif, GTIFReadMethod scan, void *fd);
	
	char*     GTIFKeyName(geokey_t key);
	char*     GTIFValueName(geokey_t key,int value);
	char*     GTIFTypeName(tagtype_t type);
	char*     GTIFTagName(int tag);
	int       GTIFKeyCode(char * key);
	int       GTIFValueCode(geokey_t key,char *value);
	int       GTIFTypeCode(char *type);
	int       GTIFTagCode(char *tag);

The GTIFPrint() routine dumps a GeoTIFF metadata stream out to
a specified file <fd>, either for human interpretation or for
input to another program. If <fd> is NULL the data is written
to the standard output.  

The GTIFImport() routine performs the inverse; given a metadata file
specified by <fd> (or stdin if <fd> is NULL) install the corresponding
tags and keys into the current GeoTIFF file. Note that the 
import routine only calls GTIFKeySet(), and so it is up to the
client program to call GTIFWriteKey() in order to explicitly
write the keys out to the file.

The GTIFxxxName() routines all take a numeric code, key or tag and
return a pointer to a static string name associated with the value.
In the case of Key-Values, the key must be explicitly defined in
order to establish the scope of the name-search. A string is always
returned; however, if the code is not recognized the string is
of the format "Unknown-%d", where %d is the input code value.

The GTIFxxxCode() routines perform the reverse operation; given
an ASCII string name it tries to find the corresponding code,
key or tag numerical value, in a case-sensitive manner. If the
string is not recognized the value -1 is return (no valid codes
are negative). For consistency, any strings of the form "Unknown-%d"
where %d is a decimal integer will return the specified integer. 

Note: be careful when assigning variables to GTIFxxxCode; for example,
the geokey_t type is unsigned, and so if -1 is returned, this will
result in a value of 65535. To be safe, always use signed integers
for the assignment, and pass them on to an unsigned type after
checking that the value is positive.


-------------------------------------------------------------
1.3 Examples


A typical use of LIBGEOTIFF for creating a GeoTIFF file is

	#include "xtiffio.h"  /* for TIFF */
	#include "geotiffio.h" /* for GeoTIFF */
	void main()
	{
		TIFF *tif=(TIFF*)0;  /* TIFF-level descriptor */
		GTIF *gtif=(GTIF*)0; /* GeoKey-level descriptor */
		
		/* Open TIFF descriptor to write GeoTIFF tags */
		tif=XTIFFOpen(fname,"w");  
		if (!tif) goto failure;
		
		/* Open GTIF Key parser */
		gtif = GTIFNew(tif);
		if (!gtif) goto failure;
		
		/* Set up standar TIFF file */
		TIFFSetField(tif,TIFFTAG_IMAGEWIDTH,    WIDTH);
		/* set other TIFF tags and write out image ... */
				
		/* Set GeoTIFF information */
		GTIFKeySet(gtif, GTModelTypeGeoKey, TYPE_SHORT, 1, ModelGeographic);
		/* set other GeoTIFF keys ... */
		
		/* Store the keys into the TIFF Tags */
		GTIFWriteKeys(gtif);
		
		/* get rid of the key parser */
		GTIFFree(gtif);
		
		/* save and close the TIFF file descriptor */
		XTIFFClose(tif);
		
		exit (0);
	failure:
		exit (-1);
	}

While a typical use of the code for reading tags is:

	#include "xtiffio.h"  /* for TIFF */
	#include "geotiffio.h" /* for GeoTIFF */
	enum {VERSION=0,MAJOR,MINOR};
	void main()
	{
		TIFF *tif=(TIFF*)0;  /* TIFF-level descriptor */
		GTIF *gtif=(GTIF*)0; /* GeoKey-level descriptor */
		int versions[3];
		int cit_length;
		geocode_t model;    /* all key-codes are of this type */
		char *citation;
		
		/* Open TIFF descriptor to read GeoTIFF tags */
		tif=XTIFFOpen(fname,"r");  
		if (!tif) goto failure;
		
		/* Open GTIF Key parser; keys will be read at this time. */
		gtif = GTIFNew(tif);
		if (!gtif) goto failure;

		/* Get the GeoTIFF directory info */
		GTIFDirectoryInfo(gtif,versions,0);
		if (versions[MAJOR] > 1)
		{
			printf("this file is too new for me\n"); goto failure;
		}
		if (!GTIFKeyGet(gtif, GTModelTypeGeoKey, &model, 0, 1))
		{
			printf("Yikes! no Model Type\n") goto failure;
		}
		
		/* ASCII keys are variable-length; compute size */
		cit_length = GTIFKeyInfo(gtif,GTCitationGeoKey,&size,&type);
		if (cit_length > 0)
		{
			citation = malloc(size*cit_length);
			if (!citation) goto failure;
			GTIFKeyGet(gtif, GTCitationGeoKey, citation, 0, cit_length);
			printf("Citation:%s\n",citation);
		}

		/* Get some TIFF info on this image */
		TIFFGetField(tif,TIFFTAG_IMAGEWIDTH,    &width);
		
		/* get rid of the key parser */
		GTIFFree(gtif);
		
		/* close the TIFF file descriptor */
		XTIFFClose(tif);
		
		exit (0);
	failure:
		exit (-1);
	}



-------------------------------------------------------------
2. The LibGeoTIFF Utilities

-------------------------------------------------------------
2.1 listgeo   - dump a GeoTIFF metadata file

Syntax:   listgeo [-tfw] [-no_norm] [-t tabledir] inputfile

The program listgeo takes a GeoTIFF file as input and dumps to
the standard output a GeoTIFF "metadata" file, which is human
readable, and may also be used as input to other programs which
use the "GTIFImport" routine, such as geotifcp, below.

The -tfw flag may be passed to force generation of an ESRI style .tfw
file as well as the metadata file.  

The -no_norm flag will supress reporting of normalized parameters, and
reporting of corner points. 

The "-t tabledir" flag overrides the programs concept of how to file the
EPSG CSV files, causing it to look in directory "tabledir". 

------------------------
GeoTIFF Metadata Format:

For the formalist junkies, we will define a GeoTIFF metadata format
in an unambiguous fashion, and follow that by a concrete example.

The metadata format is defined as follows (all strings not placed
between <braces> are string literals, case-sensitive, and any entry
followed by "*" or "*<number>" indicates multiple entries):

<Geotiff_Metadata> = <Geotiff_Header> + <GeoTIFF_Body> + <GeoTIFF_Trailer>

   <Geotiff_Header> = <White_Space> + Geotiff_Information: + <Return>
   <GeoTIFF_Trailer> = <White_Space> + End_Of_Geotiff. + <Return>
   <GeoTIFF_Body> = <GeoTIFF_Info> + <GeoTIFF_Tags> + <GeoTIFF_Keys>
      <GeoTIFF_Info> = <GeoTIFF_Version> + <GeoTIFF_Revision>
         <GeoTIFF_Version> = Version: + <Single_Space> + <Version> + <Return>
            <Version> = <Integer>
         <GeoTIFF_Revision> = Revision: + 
               <Single_Space> + <Major_Rev> + <Period> + <Minor_Rev> + <Return>
               <Major_Rev> = <Integer>
               <Minor_Rev> = <Integer>
      <GeoTIFF_Tags> =  <Tag_Header> + <Tag_Entry>* + <Tag_Trailer>
         <Tag_Header> = <White_Space> + Tagged_Information: + <Return>
         <Tag_Trailer> = <White_Space> + End_Of_Tags. + <Return>
         <Tag_Entry> = <Tag_Entry_Header> + <Tag_Entry_Row>*
            <Tag_Entry_Header> = <White_Space> + 
                     <Tag_Name> + <Tag_Dimension> + <Colon> + <Return>
               <Tag_Dimension>  = "(" + <NRows> + <Comma> + <NCols> + ")"
		 	      <NRows> = <Integer>
		 	      <NCols> = <Integer>
            <Tag_Entry_Row> = <White_Space> + <Double_Float>*<NCols> + <Return>
      <GeoTIFF_Keys> =  <Key_Header> + <Key_Entry>* + <Key_Trailer>
         <Key_Header> = <White_Space> + Keyed_Information: + <Return>
         <Key_Trailer> = <White_Space> + End_Of_Keys. + <Return>
         <Key_Entry> = <Key_Entry_Header> + <Key_Entry_Value>
            <Key_Entry_Header> = <White_Space> + 
                     <Key_Name> + <Key_Dimension> + <Colon> + <Return>
              <Key_Dimension> = "(" + <Key_Format> + <Comma> + <Key_Count> + ")"
            <Key_Entry_Value> = (<Key_Value> | <Numeric_Value> | <Ascii_Value>)
               <Numeric_Value> = (<Integer> | <Double_Float>)
               <Ascii_Value> = <Double_Quote> + <String> + <Double_Quote>

   <Tag_Name> = All symbolic tag names defined in GeoTIFF spec.
   <Key_Name> = All symbolic key names defined in GeoTIFF spec.
   <Key_Value> = All symbolic value names defined in GeoTIFF spec.
   <Key_Format> = (Short | Ascii | Double)
   
And for the pedantic:
   <White_Space> = (<Single_Space> | <Tab>)*
   <Double_Float> = <Mantissa><Exponent>
   <Mantissa> = <Sign><Integer><Period><Integer>
   <Exponent> = ( |e<Sign><Integer>)
   <Sign> = ( |+|-)
   <Integer> = (0|1|2|3|4|5|6|7|8|9)*
   ...


Example (default output of listgeo):

Geotiff_Information:
   Version: 1
   Key_Revision: 0.2
   Tagged_Information:
      ModelTiepointTag (2,3):
         0                  0                  0
       130                 32                  0
      ModelPixelScaleTag (1,3):
         1                  1                  0
      End_Of_Tags.
   Keyed_Information:
      GTModelTypeGeoKey (Short,1): ModelTypeGeographic
      GTRasterTypeGeoKey (Short,1): RasterPixelIsArea
      GTCitationGeoKey (Ascii,16): "Just An Example"
      GeographicTypeGeoKey (Short,1): User-Defined
      GeogCitationGeoKey (Ascii,24): "Everest Ellipsoid Used."
      GeogGeodeticDatumGeoKey (Short,1): User-Defined
      GeogLinearUnitsGeoKey (Short,1): Linear_Meter
      GeogAngularUnitsGeoKey (Short,1): Angular_Degree
      GeogEllipsoidGeoKey (Short,1): Ellipse_Everest_1830_1967_Definition
      GeogSemiMajorAxisGeoKey (Double,1): 6377298.556
      GeogInvFlatteningGeoKey (Double,1): 300.8017
      End_Of_Keys.
   End_Of_Geotiff.
   
   
-------------------------------------------------------------
2.2 geotifcp  - Copy a TIFF file and install GeoTIFF info from metadata.

Syntax:   geotifcp [options] [-e esri_worldfile] [-g metadata] input output

The program geotifcp is identical in function to the LIBTIFF program
"tiffcp", with the additional feature that if the "-g <metadata>"
option is used the GeoTIFF information from the file <metadata> 
will be installed into the output file.  The "-e worldfile" option will 
override the tiepoint and scale information from the metadata file based
on the contents of the ESRI worldfile. 

If the "-g" option is not used, the opposite effect occurs: all 
GeoTIFF information is filtered out of the input file before being
written to the new output file.

"geotifcp" inherits all the other file-transformation capabilities
of the tiffcp program; for help on the additional parameters give
the command:

  %  geotifcp -h

-------------------------------------------------------------
