------------------------------------------------------------- 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 is an array of 3 integers, giving the GeoTIFF Version, followed by the major and minor revisions. The 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 if currently defined in the file, and returns in the size of individual key values, and the . 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 and returning 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 , either for human interpretation or for input to another program. If is NULL the data is written to the standard output. The GTIFImport() routine performs the inverse; given a metadata file specified by (or stdin if 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 are string literals, case-sensitive, and any entry followed by "*" or "*" indicates multiple entries): = + + = + Geotiff_Information: + = + End_Of_Geotiff. + = + + = + = Version: + + + = = Revision: + + + + + = = = + * + = + Tagged_Information: + = + End_Of_Tags. + = + * = + + + + = "(" + + + + ")" = = = + * + = + * + = + Keyed_Information: + = + End_Of_Keys. + = + = + + + + = "(" + + + + ")" = ( | | ) = ( | ) = + + = All symbolic tag names defined in GeoTIFF spec. = All symbolic key names defined in GeoTIFF spec. = All symbolic value names defined in GeoTIFF spec. = (Short | Ascii | Double) And for the pedantic: = ( | )* = = = ( |e) = ( |+|-) = (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 " option is used the GeoTIFF information from the file 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 -------------------------------------------------------------