---

geotiff.h File Reference

#include "geo_config.h"
#include "geokeys.h"

Go to the source code of this file.

Functions
GTIF CPL_DLL*	GTIFNew (void *tif)
void CPL_DLL	GTIFFree (GTIF *gtif)
int CPL_DLL	GTIFWriteKeys (GTIF *gtif)
int CPL_DLL	GTIFKeyGet (GTIF *gtif, geokey_t key, void *val, int index, int count)
int CPL_DLL	GTIFKeySet (GTIF *gtif, geokey_t keyID, tagtype_t type, int count,...)
int CPL_DLL	GTIFImageToPCS ( GTIF *gtif, double *x, double *y )
int CPL_DLL	GTIFPCSToImage ( GTIF *gtif, double *x, double *y )

---

Detailed Description

Primary libgeotiff include file.

This is the defacto registry for valid GEOTIFF GeoKeys and their associated symbolic values. This is also the only file of the GeoTIFF library which needs to be included in client source code.

---

Function Documentation

void CPL_DLL GTIFFree ( GTIF * gtif )

This function deallocates an existing GeoTIFF access handle previously created with GTIFNew(). If the handle was used to write GeoTIFF keys to the TIFF file, the GTIFWriteKeys() function should be used to flush results to the file before calling GTIFFree(). GTIFFree() should be called before XTIFFClose() is called on the corresponding TIFF file handle.

int CPL_DLL GTIFImageToPCS ( GTIF * gtif, double * x, double * y )

Translate a pixel/line coordinate to projection coordinates. At this time this function does not support image to PCS translations for tiepoints-only definitions, only pixelscale and transformation matrix formulations. Parameters: gtif   The handle from GTIFNew() indicating the target file. x   A pointer to the double containing the pixel offset on input, and into which the easting/longitude will be put on completion. y   A pointer to the double containing the line offset on input, and into which the northing/latitude will be put on completion. Returns: TRUE if the transformation succeeds, or FALSE if it fails. It may fail if the file doesn't have properly setup transformation information, or it is in a form unsupported by this function.

int CPL_DLL GTIFKeyGet ( GTIF * gtif, geokey_t key, void * val, int index, int count )

This function reads the value of a single GeoKey from a GeoTIFF file. Parameters: gtif   The geotiff information handle from GTIFNew(). thekey   The geokey_t name (such as ProjectedCSTypeGeoKey). This must come from the list of legal geokey_t values (an enumeration) listed below. val   The val argument is a pointer to the variable into which the value should be read. The type of the variable varies depending on the geokey_t given. While there is no ready mapping of geokey_t values onto types, in general code values are of type short, citations are strings, and everything else is of type double. Note that pointer's to int should never be passed to GTIFKeyGet() for integer values as they will be shorts, and the int's may not be properly initialized (and will be grossly wrong on MSB systems). index   Indicates how far into the list of values for this geokey to offset. Should normally be zero. count   Indicates how many values to read. At this time all keys except for strings have only one value, so index should be zero, and count should be one. Returns: The GTIFKeyGet() function returns the number of values read. Normally this would be one if successful or zero if the key doesn't exist for this file. From geokeys.inc we see the following geokey_t values are possible: -- 6.2.1 GeoTIFF Configuration Keys -- ValuePair( GTModelTypeGeoKey, 1024) -- Section 6.3.1.1 Codes -- ValuePair( GTRasterTypeGeoKey, 1025) -- Section 6.3.1.2 Codes -- ValuePair( GTCitationGeoKey, 1026) -- documentation -- -- 6.2.2 Geographic CS Parameter Keys -- ValuePair( GeographicTypeGeoKey, 2048) -- Section 6.3.2.1 Codes -- ValuePair( GeogCitationGeoKey, 2049) -- documentation -- ValuePair( GeogGeodeticDatumGeoKey, 2050) -- Section 6.3.2.2 Codes -- ValuePair( GeogPrimeMeridianGeoKey, 2051) -- Section 6.3.2.4 codes -- ValuePair( GeogLinearUnitsGeoKey, 2052) -- Section 6.3.1.3 Codes -- ValuePair( GeogLinearUnitSizeGeoKey, 2053) -- meters -- ValuePair( GeogAngularUnitsGeoKey, 2054) -- Section 6.3.1.4 Codes -- ValuePair( GeogAngularUnitSizeGeoKey, 2055) -- radians -- ValuePair( GeogEllipsoidGeoKey, 2056) -- Section 6.3.2.3 Codes -- ValuePair( GeogSemiMajorAxisGeoKey, 2057) -- GeogLinearUnits -- ValuePair( GeogSemiMinorAxisGeoKey, 2058) -- GeogLinearUnits -- ValuePair( GeogInvFlatteningGeoKey, 2059) -- ratio -- ValuePair( GeogAzimuthUnitsGeoKey, 2060) -- Section 6.3.1.4 Codes -- ValuePair( GeogPrimeMeridianLongGeoKey, 2061) -- GeoAngularUnit -- -- 6.2.3 Projected CS Parameter Keys -- -- Several keys have been renamed,-- -- and the deprecated names aliased for backward compatibility -- ValuePair( ProjectedCSTypeGeoKey, 3072) -- Section 6.3.3.1 codes -- ValuePair( PCSCitationGeoKey, 3073) -- documentation -- ValuePair( ProjectionGeoKey, 3074) -- Section 6.3.3.2 codes -- ValuePair( ProjCoordTransGeoKey, 3075) -- Section 6.3.3.3 codes -- ValuePair( ProjLinearUnitsGeoKey, 3076) -- Section 6.3.1.3 codes -- ValuePair( ProjLinearUnitSizeGeoKey, 3077) -- meters -- ValuePair( ProjStdParallel1GeoKey, 3078) -- GeogAngularUnit -- ValuePair( ProjStdParallelGeoKey,ProjStdParallel1GeoKey) -- ** alias ** -- ValuePair( ProjStdParallel2GeoKey, 3079) -- GeogAngularUnit -- ValuePair( ProjNatOriginLongGeoKey, 3080) -- GeogAngularUnit -- ValuePair( ProjOriginLongGeoKey,ProjNatOriginLongGeoKey) -- ** alias ** -- ValuePair( ProjNatOriginLatGeoKey, 3081) -- GeogAngularUnit -- ValuePair( ProjOriginLatGeoKey,ProjNatOriginLatGeoKey) -- ** alias ** -- ValuePair( ProjFalseEastingGeoKey, 3082) -- ProjLinearUnits -- ValuePair( ProjFalseNorthingGeoKey, 3083) -- ProjLinearUnits -- ValuePair( ProjFalseOriginLongGeoKey, 3084) -- GeogAngularUnit -- ValuePair( ProjFalseOriginLatGeoKey, 3085) -- GeogAngularUnit -- ValuePair( ProjFalseOriginEastingGeoKey, 3086) -- ProjLinearUnits -- ValuePair( ProjFalseOriginNorthingGeoKey, 3087) -- ProjLinearUnits -- ValuePair( ProjCenterLongGeoKey, 3088) -- GeogAngularUnit -- ValuePair( ProjCenterLatGeoKey, 3089) -- GeogAngularUnit -- ValuePair( ProjCenterEastingGeoKey, 3090) -- ProjLinearUnits -- ValuePair( ProjCenterNorthingGeoKey, 3091) -- ProjLinearUnits -- ValuePair( ProjScaleAtNatOriginGeoKey, 3092) -- ratio -- ValuePair( ProjScaleAtOriginGeoKey,ProjScaleAtNatOriginGeoKey) -- ** alias ** -- ValuePair( ProjScaleAtCenterGeoKey, 3093) -- ratio -- ValuePair( ProjAzimuthAngleGeoKey, 3094) -- GeogAzimuthUnit -- ValuePair( ProjStraightVertPoleLongGeoKey, 3095) -- GeogAngularUnit -- 6.2.4 Vertical CS Keys ValuePair( VerticalCSTypeGeoKey, 4096) -- Section 6.3.4.1 codes -- ValuePair( VerticalCitationGeoKey, 4097) -- documentation -- ValuePair( VerticalDatumGeoKey, 4098) -- Section 6.3.4.2 codes -- ValuePair( VerticalUnitsGeoKey, 4099) -- Section 6.3.1 (.x) codes --

int CPL_DLL GTIFKeySet ( GTIF * gtif, geokey_t keyID, tagtype_t type, int count, ... )

This function writes a geokey_t value to a GeoTIFF file. Parameters: gtif   The geotiff information handle from GTIFNew(). keyID   The geokey_t name (such as ProjectedCSTypeGeoKey). This must come from the list of legal geokey_t values (an enumeration) listed below. val   The val argument is a pointer to the variable into which the value should be read. The type of the variable varies depending on the geokey_t given. While there is no ready mapping of geokey_t values onto types, in general code values are of type short, citations are strings, and everything else is of type double. Note that pointer's to int should never be passed to GTIFKeyGet() for integer values as they will be shorts, and the int's may not be properly initialized (and will be grossly wrong on MSB systems). index   Indicates how far into the list of values for this geokey to offset. Should normally be zero. count   Indicates how many values to read. At this time all keys except for strings have only one value, so index should be zero, and count should be one. The key indicates the key name to be written to the file and should from the geokey_t enumeration (eg. ProjectedCSTypeGeoKey). The full list of possible geokey_t values can be found in geokeys.inc, or in the online documentation for GTIFKeyGet(). The type should be one of TYPE_SHORT, TYPE_ASCII, or TYPE_DOUBLE and will indicate the type of value being passed at the end of the argument list (the key value). The count should be one except for strings when it should be the length of the string (or zero to for this to be computed internally). The actual value is passed at the end of the argument list, and should be a short, a double, or a char * value. Note that short and double values are passed as is, not as pointers. Note that key values aren't actually flushed to the file untill GTIFWriteKeys() is called. Till then the new values are just kept with the GTIF structure. Example: GTIFKeySet(gtif, GTRasterTypeGeoKey, TYPE_SHORT, 1, RasterPixelIsArea); GTIFKeySet(gtif, GTCitationGeoKey, TYPE_ASCII, 0, "UTM 11 North / NAD27" );

GTIF CPL_DLL* GTIFNew ( void * tif )

Given an open TIFF file, look for GTIF keys and values and return GTIF structure. This function creates a GeoTIFF information interpretation handle (GTIF *) based on a passed in TIFF handle originally from XTIFFOpen(). Even though the argument (tif) is shown as type void *, it is really normally of type TIFF *. The returned GTIF handle can be used to read or write GeoTIFF tags using the various GTIF functions. The handle should be destroyed using GTIFFree() before the file is closed with TIFFClose(). If the file accessed has no GeoTIFF keys, an valid (but empty) GTIF is still returned. GTIFNew() is used both for existing files being read, and for new TIFF files that will have GeoTIFF tags written to them.

int CPL_DLL GTIFPCSToImage ( GTIF * gtif, double * x, double * y )

Translate a projection coordinate to pixel/line coordinates. At this time this function does not support PCS to image translations for tiepoints-only, or transformation matrix based definitions, only pixelscale and tiepoints formulations. Parameters: gtif   The handle from GTIFNew() indicating the target file. x   A pointer to the double containing the pixel offset on input, and into which the easting/longitude will be put on completion. y   A pointer to the double containing the line offset on input, and into which the northing/latitude will be put on completion. Returns: TRUE if the transformation succeeds, or FALSE if it fails. It may fail if the file doesn't have properly setup transformation information, or it is in a form unsupported by this function.

int CPL_DLL GTIFWriteKeys ( GTIF * gtif )

This function flushes all the GeoTIFF keys that have been set with the GTIFKeySet() function into the associated TIFF file. Parameters: gt   The GeoTIFF handle returned by GTIFNew. GTIFKeySet() should be called before GTIFFree() is used to deallocate a GeoTIFF access handle.

---