-------------------------------------------------------------
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.
------------------------
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
-------------------------------------------------------------