geo_normalize.h File Reference

Include file for extended projection definition normalization api. More...

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

Include dependency graph for geo_normalize.h:

Go to the source code of this file.

Data Structures
struct	GTIFDefn
	Holds a definition of a coordinate system in normalized form. More...
Defines
#define	MAX_GTIF_PROJPARMS   10
#define	MapSys_UTM_North   -9001
#define	MapSys_UTM_South   -9002
#define	MapSys_State_Plane_27   -9003
#define	MapSys_State_Plane_83   -9004
#define	HAVE_GTIFPROJ4
Functions
int CPL_DLL	GTIFGetPCSInfo (int nPCSCode, char **ppszEPSGName, short *pnProjOp, short *pnUOMLengthCode, short *pnGeogCS)
int CPL_DLL	GTIFGetProjTRFInfo (int nProjTRFCode, char **ppszProjTRFName, short *pnProjMethod, double *padfProjParms)
int CPL_DLL	GTIFGetGCSInfo (int nGCSCode, char **ppszName, short *pnDatum, short *pnPM, short *pnUOMAngle)
int CPL_DLL	GTIFGetDatumInfo (int nDatumCode, char **ppszName, short *pnEllipsoid)
int CPL_DLL	GTIFGetEllipsoidInfo (int nEllipsoid, char **ppszName, double *pdfSemiMajor, double *pdfSemiMinor)
int CPL_DLL	GTIFGetPMInfo (int nPM, char **ppszName, double *pdfLongToGreenwich)
double CPL_DLL	GTIFAngleStringToDD (const char *pszAngle, int nUOMAngle)
int CPL_DLL	GTIFGetUOMLengthInfo (int nUOMLengthCode, char **ppszUOMName, double *pdfInMeters)
int CPL_DLL	GTIFGetUOMAngleInfo (int nUOMAngleCode, char **ppszUOMName, double *pdfInDegrees)
double CPL_DLL	GTIFAngleToDD (double dfAngle, int nUOMAngle)
void CPL_DLL	GTIFFreeMemory (char *)
void CPL_DLL	GTIFDeaccessCSV (void)
int CPL_DLL	GTIFGetDefn (GTIF *psGTIF, GTIFDefn *psDefn)
void CPL_DLL	GTIFPrintDefn (GTIFDefn *, FILE *)
void CPL_DLL	GTIFFreeDefn (GTIF *)
void CPL_DLL	SetCSVFilenameHook (const char *(*CSVFileOverride)(const char *))
	Override CSV file search method.
const char CPL_DLL *	GTIFDecToDMS (double, const char *, int)
int CPL_DLL	GTIFMapSysToPCS (int MapSys, int Datum, int nZone)
int CPL_DLL	GTIFMapSysToProj (int MapSys, int nZone)
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.
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.
char CPL_DLL *	GTIFGetProj4Defn (GTIFDefn *)
int CPL_DLL	GTIFProj4ToLatLong (GTIFDefn *, int, double *, double *)
int CPL_DLL	GTIFProj4FromLatLong (GTIFDefn *, int, double *, double *)
int CPL_DLL	GTIFSetFromProj4 (GTIF *gtif, const char *proj4)

---

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()

References GTIFDefn::CTProjection, GTIFDefn::Datum, GTIFDefn::DefnSet, GTIFDefn::Ellipsoid, GTIFDefn::GCS, GTIFDefn::MapSys, GTIFDefn::Model, GTIFDefn::nParms, GTIFDefn::PCS, GTIFDefn::PM, GTIFDefn::PMLongToGreenwich, GTIFDefn::ProjCode, GTIFDefn::Projection, GTIFDefn::ProjParm, GTIFDefn::ProjParmId, GTIFDefn::SemiMajor, GTIFDefn::SemiMinor, GTIFDefn::UOMAngle, GTIFDefn::UOMAngleInDegrees, GTIFDefn::UOMLength, GTIFDefn::UOMLengthInMeters, and GTIFDefn::Zone.

{
    int         i;
    short       nGeogUOMLinear;
    double      dfInvFlattening;
    
/* -------------------------------------------------------------------- */
/*      Initially we default all the information we can.                */
/* -------------------------------------------------------------------- */
    psDefn->DefnSet = 1;
    psDefn->Model = KvUserDefined;
    psDefn->PCS = KvUserDefined;
    psDefn->GCS = KvUserDefined;
    psDefn->UOMLength = KvUserDefined;
    psDefn->UOMLengthInMeters = 1.0;
    psDefn->UOMAngle = KvUserDefined;
    psDefn->UOMAngleInDegrees = 1.0;
    psDefn->Datum = KvUserDefined;
    psDefn->Ellipsoid = KvUserDefined;
    psDefn->SemiMajor = 0.0;
    psDefn->SemiMinor = 0.0;
    psDefn->PM = KvUserDefined;
    psDefn->PMLongToGreenwich = 0.0;

    psDefn->ProjCode = KvUserDefined;
    psDefn->Projection = KvUserDefined;
    psDefn->CTProjection = KvUserDefined;

    psDefn->nParms = 0;
    for( i = 0; i < MAX_GTIF_PROJPARMS; i++ )
    {
        psDefn->ProjParm[i] = 0.0;
        psDefn->ProjParmId[i] = 0;
    }

    psDefn->MapSys = KvUserDefined;
    psDefn->Zone = 0;

/* -------------------------------------------------------------------- */
/*      Do we have any geokeys?                                         */
/* -------------------------------------------------------------------- */
    {
        int     nKeyCount = 0;
        int     anVersion[3];
        GTIFDirectoryInfo( psGTIF, anVersion, &nKeyCount );

        if( nKeyCount == 0 )
        {
            psDefn->DefnSet = 0;
            return FALSE;
        }
    }

/* -------------------------------------------------------------------- */
/*      Try to get the overall model type.                              */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF,GTModelTypeGeoKey,&(psDefn->Model),0,1);

/* -------------------------------------------------------------------- */
/*      Extract the Geog units.                                         */
/* -------------------------------------------------------------------- */
    nGeogUOMLinear = 9001; /* Linear_Meter */
    GTIFKeyGet(psGTIF, GeogLinearUnitsGeoKey, &nGeogUOMLinear, 0, 1 );

/* -------------------------------------------------------------------- */
/*      Try to get a PCS.                                               */
/* -------------------------------------------------------------------- */
    if( GTIFKeyGet(psGTIF,ProjectedCSTypeGeoKey, &(psDefn->PCS),0,1) == 1
        && psDefn->PCS != KvUserDefined )
    {
        /*
         * Translate this into useful information.
         */
        GTIFGetPCSInfo( psDefn->PCS, NULL, &(psDefn->ProjCode),
                        &(psDefn->UOMLength), &(psDefn->GCS) );
    }

/* -------------------------------------------------------------------- */
/*       If we have the PCS code, but didn't find it in the CSV files   */
/*      (likely because we can't find them) we will try some ``jiffy    */
/*      rules'' for UTM and state plane.                                */
/* -------------------------------------------------------------------- */
    if( psDefn->PCS != KvUserDefined && psDefn->ProjCode == KvUserDefined )
    {
        int     nMapSys, nZone;
        int     nGCS = psDefn->GCS;

        nMapSys = GTIFPCSToMapSys( psDefn->PCS, &nGCS, &nZone );
        if( nMapSys != KvUserDefined )
        {
            psDefn->ProjCode = (short) GTIFMapSysToProj( nMapSys, nZone );
            psDefn->GCS = (short) nGCS;
        }
    }

/* -------------------------------------------------------------------- */
/*      If the Proj_ code is specified directly, use that.              */
/* -------------------------------------------------------------------- */
    if( psDefn->ProjCode == KvUserDefined )
        GTIFKeyGet(psGTIF, ProjectionGeoKey, &(psDefn->ProjCode), 0, 1 );
    
    if( psDefn->ProjCode != KvUserDefined )
    {
        /*
         * We have an underlying projection transformation value.  Look
         * this up.  For a PCS of ``WGS 84 / UTM 11'' the transformation
         * would be Transverse Mercator, with a particular set of options.
         * The nProjTRFCode itself would correspond to the name
         * ``UTM zone 11N'', and doesn't include datum info.
         */
        GTIFGetProjTRFInfo( psDefn->ProjCode, NULL, &(psDefn->Projection),
                            psDefn->ProjParm );
        
        /*
         * Set the GeoTIFF identity of the parameters.
         */
        psDefn->CTProjection = (short) 
            EPSGProjMethodToCTProjMethod( psDefn->Projection );

        SetGTParmIds( psDefn->CTProjection, psDefn->ProjParmId, NULL);
        psDefn->nParms = 7;
    }

/* -------------------------------------------------------------------- */
/*      Try to get a GCS.  If found, it will override any implied by    */
/*      the PCS.                                                        */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF, GeographicTypeGeoKey, &(psDefn->GCS), 0, 1 );
    if( psDefn->GCS < 1 || psDefn->GCS >= KvUserDefined )
        psDefn->GCS = KvUserDefined;

/* -------------------------------------------------------------------- */
/*      Derive the datum, and prime meridian from the GCS.              */
/* -------------------------------------------------------------------- */
    if( psDefn->GCS != KvUserDefined )
    {
        GTIFGetGCSInfo( psDefn->GCS, NULL, &(psDefn->Datum), &(psDefn->PM),
                        &(psDefn->UOMAngle) );
    }
    
/* -------------------------------------------------------------------- */
/*      Handle the GCS angular units.  GeogAngularUnitsGeoKey           */
/*      overrides the GCS or PCS setting.                               */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF, GeogAngularUnitsGeoKey, &(psDefn->UOMAngle), 0, 1 );
    if( psDefn->UOMAngle != KvUserDefined )
    {
        GTIFGetUOMAngleInfo( psDefn->UOMAngle, NULL,
                             &(psDefn->UOMAngleInDegrees) );
    }

/* -------------------------------------------------------------------- */
/*      Check for a datum setting, and then use the datum to derive     */
/*      an ellipsoid.                                                   */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF, GeogGeodeticDatumGeoKey, &(psDefn->Datum), 0, 1 );

    if( psDefn->Datum != KvUserDefined )
    {
        GTIFGetDatumInfo( psDefn->Datum, NULL, &(psDefn->Ellipsoid) );
    }

/* -------------------------------------------------------------------- */
/*      Check for an explicit ellipsoid.  Use the ellipsoid to          */
/*      derive the ellipsoid characteristics, if possible.              */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF, GeogEllipsoidGeoKey, &(psDefn->Ellipsoid), 0, 1 );

    if( psDefn->Ellipsoid != KvUserDefined )
    {
        GTIFGetEllipsoidInfo( psDefn->Ellipsoid, NULL,
                              &(psDefn->SemiMajor), &(psDefn->SemiMinor) );
    }

/* -------------------------------------------------------------------- */
/*      Check for overridden ellipsoid parameters.  It would be nice    */
/*      to warn if they conflict with provided information, but for     */
/*      now we just override.                                           */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF, GeogSemiMajorAxisGeoKey, &(psDefn->SemiMajor), 0, 1 );
    GTIFKeyGet(psGTIF, GeogSemiMinorAxisGeoKey, &(psDefn->SemiMinor), 0, 1 );
    
    if( GTIFKeyGet(psGTIF, GeogInvFlatteningGeoKey, &dfInvFlattening, 
                   0, 1 ) == 1 )
    {
        if( dfInvFlattening != 0.0 )
            psDefn->SemiMinor = 
                psDefn->SemiMajor * (1 - 1.0/dfInvFlattening);
        else
            psDefn->SemiMinor = psDefn->SemiMajor;
    }
    
/* -------------------------------------------------------------------- */
/*      Get the prime meridian info.                                    */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF, GeogPrimeMeridianGeoKey, &(psDefn->PM), 0, 1 );

    if( psDefn->PM != KvUserDefined )
    {
        GTIFGetPMInfo( psDefn->PM, NULL, &(psDefn->PMLongToGreenwich) );
    }
    else
    {
        GTIFKeyGet(psGTIF, GeogPrimeMeridianLongGeoKey,
                   &(psDefn->PMLongToGreenwich), 0, 1 );

        psDefn->PMLongToGreenwich =
            GTIFAngleToDD( psDefn->PMLongToGreenwich,
                           psDefn->UOMAngle );
    }

/* -------------------------------------------------------------------- */
/*      Have the projection units of measure been overridden?  We       */
/*      should likely be doing something about angular units too,       */
/*      but these are very rarely not decimal degrees for actual        */
/*      file coordinates.                                               */
/* -------------------------------------------------------------------- */
    GTIFKeyGet(psGTIF,ProjLinearUnitsGeoKey,&(psDefn->UOMLength),0,1);

    if( psDefn->UOMLength != KvUserDefined )
    {
        GTIFGetUOMLengthInfo( psDefn->UOMLength, NULL,
                              &(psDefn->UOMLengthInMeters) );
    }

/* -------------------------------------------------------------------- */
/*      Handle a variety of user defined transform types.               */
/* -------------------------------------------------------------------- */
    if( GTIFKeyGet(psGTIF,ProjCoordTransGeoKey,
                   &(psDefn->CTProjection),0,1) == 1)
    {
        GTIFFetchProjParms( psGTIF, psDefn );
    }

/* -------------------------------------------------------------------- */
/*      Try to set the zoned map system information.                    */
/* -------------------------------------------------------------------- */
    psDefn->MapSys = GTIFProjToMapSys( psDefn->ProjCode, &(psDefn->Zone) );

/* -------------------------------------------------------------------- */
/*      If this is UTM, and we were unable to extract the projection    */
/*      parameters from the CSV file, just set them directly now,       */
/*      since it's pretty easy, and a common case.                      */
/* -------------------------------------------------------------------- */
    if( (psDefn->MapSys == MapSys_UTM_North
         || psDefn->MapSys == MapSys_UTM_South)
        && psDefn->CTProjection == KvUserDefined )
    {
        psDefn->CTProjection = CT_TransverseMercator;
        psDefn->nParms = 7;
        psDefn->ProjParmId[0] = ProjNatOriginLatGeoKey;
        psDefn->ProjParm[0] = 0.0;
            
        psDefn->ProjParmId[1] = ProjNatOriginLongGeoKey;
        psDefn->ProjParm[1] = psDefn->Zone*6 - 183.0;
        
        psDefn->ProjParmId[4] = ProjScaleAtNatOriginGeoKey;
        psDefn->ProjParm[4] = 0.9996;
        
        psDefn->ProjParmId[5] = ProjFalseEastingGeoKey;
        psDefn->ProjParm[5] = 500000.0;
        
        psDefn->ProjParmId[6] = ProjFalseNorthingGeoKey;

        if( psDefn->MapSys == MapSys_UTM_North )
            psDefn->ProjParm[6] = 0.0;
        else
            psDefn->ProjParm[6] = 10000000.0;
    }

    return TRUE;
}

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         Datum = KvUserDefined, Proj = KvUserDefined;
    int         nZone = KvUserDefined, i;

/* -------------------------------------------------------------------- */
/*      UTM with various datums.  Note there are lots of PCS UTM        */
/*      codes not done yet which use strange datums.                    */
/* -------------------------------------------------------------------- */
    if( PCSCode >= PCS_NAD27_UTM_zone_3N && PCSCode <= PCS_NAD27_UTM_zone_22N )
    {
        Datum = GCS_NAD27;
        Proj = MapSys_UTM_North;
        nZone = PCSCode - PCS_NAD27_UTM_zone_3N + 3;
    }
    else if( PCSCode >= PCS_NAD83_UTM_zone_3N 
             && PCSCode <= PCS_NAD83_UTM_zone_23N )
    {
        Datum = GCS_NAD83;
        Proj = MapSys_UTM_North;
        nZone = PCSCode - PCS_NAD83_UTM_zone_3N + 3;
    }

    else if( PCSCode >= PCS_WGS72_UTM_zone_1N
             && PCSCode <= PCS_WGS72_UTM_zone_60N )
    {
        Datum = GCS_WGS_72;
        Proj = MapSys_UTM_North;
        nZone = PCSCode - PCS_WGS72_UTM_zone_1N + 1;
    }
    else if( PCSCode >= PCS_WGS72_UTM_zone_1S
             && PCSCode <= PCS_WGS72_UTM_zone_60S )
    {
        Datum = GCS_WGS_72;
        Proj = MapSys_UTM_South;
        nZone = PCSCode - PCS_WGS72_UTM_zone_1S + 1;
    }

    else if( PCSCode >= PCS_WGS72BE_UTM_zone_1N
             && PCSCode <= PCS_WGS72BE_UTM_zone_60N )
    {
        Datum = GCS_WGS_72BE;
        Proj = MapSys_UTM_North;
        nZone = PCSCode - PCS_WGS72BE_UTM_zone_1N + 1;
    }
    else if( PCSCode >= PCS_WGS72BE_UTM_zone_1S
             && PCSCode <= PCS_WGS72BE_UTM_zone_60S )
    {
        Datum = GCS_WGS_72BE;
        Proj = MapSys_UTM_South;
        nZone = PCSCode - PCS_WGS72BE_UTM_zone_1S + 1;
    }

    else if( PCSCode >= PCS_WGS84_UTM_zone_1N
             && PCSCode <= PCS_WGS84_UTM_zone_60N )
    {
        Datum = GCS_WGS_84;
        Proj = MapSys_UTM_North;
        nZone = PCSCode - PCS_WGS84_UTM_zone_1N + 1;
    }
    else if( PCSCode >= PCS_WGS84_UTM_zone_1S
             && PCSCode <= PCS_WGS84_UTM_zone_60S )
    {
        Datum = GCS_WGS_84;
        Proj = MapSys_UTM_South;
        nZone = PCSCode - PCS_WGS84_UTM_zone_1S + 1;
    }
    else if( PCSCode >= PCS_SAD69_UTM_zone_18N 
             && PCSCode <= PCS_SAD69_UTM_zone_22N )
    {
        Datum = KvUserDefined;
        Proj = MapSys_UTM_North;
        nZone = PCSCode - PCS_SAD69_UTM_zone_18N + 18;
    }
    else if( PCSCode >= PCS_SAD69_UTM_zone_17S
             && PCSCode <= PCS_SAD69_UTM_zone_25S )
    {
        Datum = KvUserDefined;
        Proj = MapSys_UTM_South;
        nZone = PCSCode - PCS_SAD69_UTM_zone_17S + 17;
    }

/* -------------------------------------------------------------------- */
/*      State Plane zones, first we translate any PCS_ codes to         */
/*      a Proj_ code that we can get a handle on.                       */
/* -------------------------------------------------------------------- */
    for( i = 0; StatePlaneTable[i] != KvUserDefined; i += 2 )
    {
        if( StatePlaneTable[i] == PCSCode )
            PCSCode = StatePlaneTable[i+1];
    }

    if( PCSCode <= 15900 && PCSCode >= 10000 )
    {
        if( (PCSCode % 100) >= 30 )
        {
            Proj = MapSys_State_Plane_83;
            Datum = GCS_NAD83;
        }
        else
        {
            Proj = MapSys_State_Plane_27;
            Datum = GCS_NAD27;
        }
        
        nZone = PCSCode - 10000;
        if( Datum == GCS_NAD83 )
            nZone -= 30;
    }

    if( pDatum != NULL )
        *pDatum = Datum;

    if( pZone != NULL )
        *pZone = nZone;

    return( Proj );
}

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.

{
    int         nZone = KvUserDefined;
    int         MapSys = KvUserDefined;

/* -------------------------------------------------------------------- */
/*      Handle UTM.                                                     */
/* -------------------------------------------------------------------- */
    if( ProjCode >= Proj_UTM_zone_1N && ProjCode <= Proj_UTM_zone_60N )
    {
        MapSys = MapSys_UTM_North;
        nZone = ProjCode - Proj_UTM_zone_1N + 1;
    }
    else if( ProjCode >= Proj_UTM_zone_1S && ProjCode <= Proj_UTM_zone_60S )
    {
        MapSys = MapSys_UTM_South;
        nZone = ProjCode - Proj_UTM_zone_1S + 1;
    }

/* -------------------------------------------------------------------- */
/*      Handle State Plane.  I think there are some anomolies in        */
/*      here, so this is a bit risky.                                   */
/* -------------------------------------------------------------------- */
    else if( ProjCode >= 10101 && ProjCode <= 15299 )
    {
        if( ProjCode % 100 >= 30 )
        {
            MapSys = MapSys_State_Plane_83;
            nZone = ProjCode - 10000 - 30;
        }
        else
        {
            MapSys = MapSys_State_Plane_27;
            nZone = ProjCode - 10000;
        }
    }
    
    if( pZone != NULL )
        *pZone = nZone;

    return( MapSys );
}

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 );
}

{
    pfnCSVFilenameHook = pfnNewHook;
}