---

geo_normalize.h File Reference

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

Go to the source code of this file.

Compounds
struct	GTIFDefn
Functions
int CPL_DLL	GTIFGetDefn ( GTIF *psGTIF, GTIFDefn * psDefn )
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: Convert all angular values to decimal degrees. Convert all linear values to meters. Return the linear units and conversion to meters for the tiepoints and scale (though the tiepoints and scale remain in their native units). 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.

---