# 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 | thekey,
|  | 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). As a special case a count of -1 can be used to request an existing key be deleted, in which no value is passed.

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 by value rather than as pointers when count is 1, but as pointers if count is larger than 1.

Note that key values aren't actually flushed to the file until 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 based definitions, only matrix and pixelscale/tiepoints formulations are supposed.

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

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.

GTIFWriteKeys() should be called before GTIFFree() is used to deallocate a GeoTIFF access handle.