# listgeo - Dump GeoTIFF Metadata

    Usage: listgeo [-tfw] [-no_norm] [-proj4] [-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.

The -tfw flag may be passed to force generation of an ESRI style .tfw file as well as the metadata file. The ESRI world file is always given the same basename as the input file, with the extension .tfw. If one exists already it will be overwritten.

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

The -proj4 flag forces listgeo to report the PROJ.4 projection string it uses for reprojecting corners to lat/long.

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

Following the formal metadata report, there is an optional (use -no_norm to suppress) report on the normalized projection parameters for the file. This is an attempt to lookup PCS and GCS definitions to get detailed datum, ellipsoid, and projection definitions for the file. In general it requires access to the EPSG CSV files to work properly. The GEOTIFF_CSV environment variable can be used to point to directory containing the EPSG CSV files (normally distributed with libgeotiff, or this executable). If GEOTIFF_CSV is not defined listgeo will look for a csv subdirectory, or the /usr/local/shared/epsg_csv directory. The -t commandline switch can also be used to indicate where the CSV files are located.

Following the normalized projection information listgeo will report the positions of the four corner coordinates, and if possible their lat/long equivalents. The corner coordinates are reported for tiepoint+scale and transformation matrix formulations of GeoTIFF files, but not for multiple tiepoint formulations. The lat/long coordinates are only available if listgeo is compiled with PROJ.4, if the projection definition can be normalized, and if it is a projection supported by the listgeo PROJ.4 binding.

Example (default output of listgeo):

    Geotiff_Information:
       Version: 1
       Key_Revision: 1.0
       Tagged_Information:
          ModelTiepointTag (2,3):
             0                0                0
             440720           3751320          0
          ModelPixelScaleTag (1,3):
             60               60               0
          End_Of_Tags.
       Keyed_Information:
          GTModelTypeGeoKey (Short,1): ModelTypeProjected
          GTRasterTypeGeoKey (Short,1): RasterPixelIsArea
          GTCitationGeoKey (Ascii,17): "UTM    11 S E000"
          GeogLinearUnitsGeoKey (Short,1): Linear_Meter
          GeogAngularUnitsGeoKey (Short,1): Angular_Degree
          ProjectedCSTypeGeoKey (Short,1): PCS_NAD27_UTM_zone_11N
          End_Of_Keys.
       End_Of_Geotiff.

    PCS = 26711 (NAD27 / UTM zone 11N)
    Projection = 16011 (UTM zone 11N)
    Projection Method: CT_TransverseMercator
       ProjNatOriginLatGeoKey: 0.000000 (  0d 0' 0.00"N)
       ProjNatOriginLongGeoKey: -117.000000 (117d 0' 0.00"W)
       ProjScaleAtNatOriginGeoKey: 0.999600
       ProjFalseEastingGeoKey: 500000.000000
       ProjFalseNorthingGeoKey: 0.000000
    GCS: 4267/NAD27
    Datum: 6267/North American Datum 1927
    Ellipsoid: 7008/Clarke 1866 (6378206.40,6356583.80)
    Prime Meridian: 8901/Greenwich (0.000000/  0d 0' 0.00"E)
    Projection Linear Units: 9001/metre (1.000000m)

    Corner Coordinates:
    Upper Left    ( 440720.000,3751320.000)  (117d38'28.21"W, 33d54' 8.47"N)
    Lower Left    ( 440720.000,3720600.000)  (117d38'20.79"W, 33d37'31.04"N)
    Upper Right   ( 471440.000,3751320.000)  (117d18'32.07"W, 33d54'13.08"N)
    Lower Right   ( 471440.000,3720600.000)  (117d18'28.50"W, 33d37'35.61"N)
    Center        ( 456080.000,3735960.000)  (117d28'27.39"W, 33d45'52.46"N)

## See Also:

1. geotiffcp - Copy TIFF installing GeoTIFF metadata.

2. http://www.remotesensing.org/geotiff/geotiff.html - GeoTIFF/libgeotiff Home Page