# geo_normalize.h File Reference

`#include <stdio.h>`
`#include "geotiff.h"`

Go to the source code of this file.

## Classes

struct | GTIFDefn

## Functions

int CPL_DLL | GTIFGetDefn (GTIF *psGTIF, GTIFDefn *psDefn)
void CPL_DLL | SetCSVFilenameHook (const char *(*CSVFileOverride)(const char *))
int CPL_DLL | GTIFPCSToMapSys (int PCSCode, int *pDatum, int *pZone)
int CPL_DLL | GTIFProjToMapSys (int ProjCode, int *pZone)

## Detailed Description

Include file for extended projection definition normalization api.

## Function Documentation

int CPL_DLL GTIFGetDefn | ( | GTIF * | psGTIF,
|  | GTIFDefn * | psDefn |
| ) |  |  |

Parameters:

  | psGTIF | GeoTIFF information handle as returned by GTIFNew.
  | psDefn | Pointer to an existing GTIFDefn structure. This structure does not need to have been pre-initialized at all.

Returns:
  TRUE if the function has been successful, otherwise FALSE.

This function reads the coordinate system definition from a GeoTIFF file, and normalizes it into a set of component information using definitions from CSV (Comma Seperated Value ASCII) files derived from EPSG tables. This function is intended to simplify correct support for reading files with defined PCS (Projected Coordinate System) codes that wouldn't otherwise be directly known by application software by reducing it to the underlying projection method, parameters, datum, ellipsoid, prime meridian and units.

The application should pass a pointer to an existing uninitialized GTIFDefn structure, and GTIFGetDefn() will fill it in. The fuction currently always returns TRUE but in the future will return FALSE if CSV files are not found. In any event, all geokeys actually found in the file will be copied into the GTIFDefn. However, if the CSV files aren't found codes implied by other codes will not be set properly.

GTIFGetDefn() will not generally work if the EPSG derived CSV files cannot be found. By default a modest attempt will be made to find them, but in general it is necessary for the calling application to override the logic to find them. This can be done by calling the SetCSVFilenameHook() function to override the search method based on application knowledge of where they are found.

The normalization methodology operates by fetching tags from the GeoTIFF file, and then setting all other tags implied by them in the structure. The implied relationships are worked out by reading definitions from the various EPSG derived CSV tables.

For instance, if a PCS (ProjectedCSTypeGeoKey) is found in the GeoTIFF file this code is used to lookup a record in the `horiz_cs.csv` CSV file. For example given the PCS 26746 we can find the name (NAD27 / California zone VI), the GCS 4257 (NAD27), and the ProjectionCode 10406 (California CS27 zone VI). The GCS, and ProjectionCode can in turn be looked up in other tables until all the details of units, ellipsoid, prime meridian, datum, projection (LambertConfConic_2SP) and projection parameters are established. A full listgeo dump of a file for this result might look like the following, all based on a single PCS value:

    % listgeo -norm ~/data/geotiff/pci_eg/spaf27.tif
    Geotiff_Information:
       Version: 1
       Key_Revision: 1.0
       Tagged_Information:
          ModelTiepointTag (2,3):
             0                0                0
             1577139.71       634349.176       0
          ModelPixelScaleTag (1,3):
             195.509321       198.32184        0
          End_Of_Tags.
       Keyed_Information:
          GTModelTypeGeoKey (Short,1): ModelTypeProjected
          GTRasterTypeGeoKey (Short,1): RasterPixelIsArea
          ProjectedCSTypeGeoKey (Short,1): PCS_NAD27_California_VI
          End_Of_Keys.
       End_Of_Geotiff.

    PCS = 26746 (NAD27 / California zone VI)
    Projection = 10406 (California CS27 zone VI)
    Projection Method: CT_LambertConfConic_2SP
       ProjStdParallel1GeoKey: 33.883333
       ProjStdParallel2GeoKey: 32.766667
       ProjFalseOriginLatGeoKey: 32.166667
       ProjFalseOriginLongGeoKey: -116.233333
       ProjFalseEastingGeoKey: 609601.219202
       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)
    Projection Linear Units: 9003/US survey foot (0.304801m)

Note that GTIFGetDefn() does not inspect or return the tiepoints and scale. This must be handled seperately as it normally would. It is intended to simplify capture and normalization of the coordinate system definition. Note that GTIFGetDefn() also does the following things:

1. Convert all angular values to decimal degrees.
2. Convert all linear values to meters.
3. Return the linear units and conversion to meters for the tiepoints and scale (though the tiepoints and scale remain in their native units).
4. When reading projection parameters a variety of differences between different GeoTIFF generators are handled, and a normalized set of parameters for each projection are always returned.

Code fields in the GTIFDefn are filled with KvUserDefined if there is not value to assign. The parameter lists for each of the underlying projection transform methods can be found at the Projections page. Note that nParms will be set based on the maximum parameter used. Some of the parameters may not be used in which case the GTIFDefn::ProjParmId[] will be zero. This is done to retain correspondence to the EPSG parameter numbering scheme.

The geotiff_proj4.c module distributed with libgeotiff can be used as an example of code that converts a GTIFDefn into another projection system.

See also:
  GTIFKeySet(), SetCSVFilenameHook()

int CPL_DLL GTIFPCSToMapSys | ( | int | PCSCode,
|  | int * | pDatum,
|  | int * | pZone |
| ) |  |  |

Translate a PCS_ code into a UTM or State Plane map system, a datum, and a zone if possible.

Parameters:

  | PCSCode | The projection code (PCS_*) as would be stored in the ProjectedCSTypeGeoKey of a GeoTIFF file.
  | pDatum | Pointer to an integer into which the datum code (GCS_*) is put if the function succeeds.
  | pZone | Pointer to an integer into which the zone will be placed if the function is successful.

Returns:
  Returns either MapSys_UTM_North, MapSys_UTM_South, MapSys_State_Plane_83, MapSys_State_Plane_27 or KvUserDefined. KvUserDefined indicates that the function failed to recognise the projection as UTM or State Plane.

The zone value is only set if the return code is other than KvUserDefined. For utm map system the returned zone will be between 1 and 60. For State Plane, the USGS state plane zone number is returned. For instance, Alabama East is zone 101.

The datum (really this is the GCS) is set to a GCS_ value such as GCS_NAD27.

This function is useful to recognise (most) UTM and State Plane coordinate systems, even if CSV files aren't available to translate them automatically. It is used as a fallback mechanism by GTIFGetDefn() for normalization when CSV files aren't found.

int CPL_DLL GTIFProjToMapSys | ( | int | ProjCode,
|  | int * | pZone |
| ) |  |  |

Translate a Proj_ code into a UTM or State Plane map system, and a zone if possible.

Parameters:

  | ProjCode | The projection code (Proj_*) as would be stored in the ProjectionGeoKey of a GeoTIFF file.
  | pZone | Pointer to an integer into which the zone will be placed if the function is successful.

Returns:
  Returns either MapSys_UTM_North, MapSys_UTM_South, MapSys_State_Plane_27, MapSys_State_Plane_83 or KvUserDefined. KvUserDefined indicates that the function failed to recognise the projection as UTM or State Plane.

The zone value is only set if the return code is other than KvUserDefined. For utm map system the returned zone will be between 1 and 60. For State Plane, the USGS state plane zone number is returned. For instance, Alabama East is zone 101.

This function is useful to recognise UTM and State Plane coordinate systems, and to extract zone numbers so the projections can be represented as UTM rather than as the underlying projection method such Transverse Mercator for instance.

void CPL_DLL SetCSVFilenameHook | ( | const char *(*)(const char *) | pfnNewHook | ) |

Override CSV file search method.

Parameters:

  | CSVFileOverride | The pointer to a function which will return the full path for a given filename.

This function allows an application to override how the GTIFGetDefn() and related function find the CSV (Comma Separated Value) values required. The pfnHook argument should be a pointer to a function that will take in a CSV filename and return a full path to the file. The returned string should be to an internal static buffer so that the caller doesn't have to free the result.

Example:

The listgeo utility uses the following override function if the user specified a CSV file directory with the -t commandline switch (argument put into CSVDirName).

        ...

        SetCSVFilenameHook( CSVFileOverride );

        ...

    static const char *CSVFileOverride( const char * pszInput )

    {
        static char         szPath[1024];

    ifdef WIN32
        sprintf( szPath, "%s\\%s", CSVDirName, pszInput );
    else
        sprintf( szPath, "%s/%s", CSVDirName, pszInput );
    endif

        return( szPath );
    }