OGR
OGR Projections Tutorial

Introduction

The OGRSpatialReference, and OGRCoordinateTransformation classes provide services to represent coordinate systems (projections and datums) and to transform between them. These services are loosely modeled on the OpenGIS Coordinate Transformations specification, and use the same Well Known Text format for describing coordinate systems.

Some background on OpenGIS coordinate systems and services can be found in the Simple Features for COM, and Spatial Reference Systems Abstract Model documents available from the Open Geospatial Consortium. The GeoTIFF Projections Transform List may also be of assistance in understanding formulations of projections in WKT. The EPSG Geodesy web page is also a useful resource.

You may also consult the OGC WKT Coordinate System Issues page.

Defining a Geographic Coordinate System

Coordinate systems are encapsulated in the OGRSpatialReference class. There are a number of ways of initializing an OGRSpatialReference object to a valid coordinate system. There are two primary kinds of coordinate systems. The first is geographic (positions are measured in long/lat) and the second is projected (such as UTM - positions are measured in meters or feet).

A Geographic coordinate system contains information on the datum (which implies an spheroid described by a semi-major axis, and inverse flattening), prime meridian (normally Greenwich), and an angular units type which is normally degrees. The following code initializes a geographic coordinate system on supplying all this information along with a user visible name for the geographic coordinate system.

oSRS.SetGeogCS( "My geographic coordinate system",
"WGS_1984",
"My WGS84 Spheroid",
"Greenwich", 0.0,
"degree", SRS_UA_DEGREE_CONV );

Of these values, the names "My geographic coordinate system", "My WGS84 Spheroid", "Greenwich" and "degree" are not keys, but are used for display to the user. However, the datum name "WGS_1984" is used as a key to identify the datum, and there are rules on what values can be used. NOTE: Prepare writeup somewhere on valid datums!

The OGRSpatialReference has built in support for a few well known coordinate systems, which include "NAD27", "NAD83", "WGS72" and "WGS84" which can be defined in a single call to SetWellKnownGeogCS().

oSRS.SetWellKnownGeogCS( "WGS84" );

Furthermore, any geographic coordinate system in the EPSG database can be set by its GCS code number if the EPSG database is available.

oSRS.SetWellKnownGeogCS( "EPSG:4326" );

For serialization, and transmission of projection definitions to other packages, the OpenGIS Well Known Text format for coordinate systems is used. An OGRSpatialReference can be initialized from well known text, or converted back into well known text.

char *pszWKT = NULL;
oSRS.SetWellKnownGeogCS( "WGS84" );
oSRS.exportToWkt( &pszWKT );
printf( "%s\n", pszWKT );

gives something like:

GEOGCS["WGS 84",DATUM["WGS_1984",SPHEROID["WGS 84",6378137,298.257223563,
AUTHORITY["EPSG",7030]],TOWGS84[0,0,0,0,0,0,0],AUTHORITY["EPSG",6326]],
PRIMEM["Greenwich",0,AUTHORITY["EPSG",8901]],UNIT["DMSH",0.0174532925199433,
AUTHORITY["EPSG",9108]],AXIS["Lat",NORTH],AXIS["Long",EAST],AUTHORITY["EPSG",
4326]]

or in more readable form:

GEOGCS["WGS 84",
    DATUM["WGS_1984",
        SPHEROID["WGS 84",6378137,298.257223563,
            AUTHORITY["EPSG",7030]],
        TOWGS84[0,0,0,0,0,0,0],
        AUTHORITY["EPSG",6326]],
    PRIMEM["Greenwich",0,AUTHORITY["EPSG",8901]],
    UNIT["DMSH",0.0174532925199433,AUTHORITY["EPSG",9108]],
    AXIS["Lat",NORTH],
    AXIS["Long",EAST],
    AUTHORITY["EPSG",4326]]

The OGRSpatialReference::importFromWkt() method can be used to set an OGRSpatialReference from a WKT coordinate system definition.

Defining a Projected Coordinate System

A projected coordinate system (such as UTM, Lambert Conformal Conic, etc) requires and underlying geographic coordinate system as well as a definition for the projection transform used to translate between linear positions (in meters or feet) and angular long/lat positions. The following code defines a UTM zone 17 projected coordinate system with an underlying geographic coordinate system (datum) of WGS84.

oSRS.SetProjCS( "UTM 17 (WGS84) in northern hemisphere." );
oSRS.SetWellKnownGeogCS( "WGS84" );
oSRS.SetUTM( 17, TRUE );

Calling SetProjCS() sets a user name for the projected coordinate system and establishes that the system is projected. The SetWellKnownGeogCS() associates a geographic coordinate system, and the SetUTM() call sets detailed projection transformation parameters. At this time the above order is important in order to create a valid definition, but in the future the object will automatically reorder the internal representation as needed to remain valid. For now be careful of the order of steps defining an OGRSpatialReference!

The above definition would give a WKT version that looks something like the following. Note that the UTM 17 was expanded into the details transverse mercator definition of the UTM zone.

PROJCS["UTM 17 (WGS84) in northern hemisphere.",
    GEOGCS["WGS 84",
        DATUM["WGS_1984",
            SPHEROID["WGS 84",6378137,298.257223563,
                AUTHORITY["EPSG",7030]],
            TOWGS84[0,0,0,0,0,0,0],
            AUTHORITY["EPSG",6326]],
        PRIMEM["Greenwich",0,AUTHORITY["EPSG",8901]],
        UNIT["DMSH",0.0174532925199433,AUTHORITY["EPSG",9108]],
        AXIS["Lat",NORTH],
        AXIS["Long",EAST],
        AUTHORITY["EPSG",4326]],
    PROJECTION["Transverse_Mercator"],
    PARAMETER["latitude_of_origin",0],
    PARAMETER["central_meridian",-81],
    PARAMETER["scale_factor",0.9996],
    PARAMETER["false_easting",500000],
    PARAMETER["false_northing",0]]

There are methods for many projection methods including SetTM() (Transverse Mercator), SetLCC() (Lambert Conformal Conic), and SetMercator().

Querying Coordinate System

Once an OGRSpatialReference has been established, various information about it can be queried. It can be established if it is a projected or geographic coordinate system using the OGRSpatialReference::IsProjected() and OGRSpatialReference::IsGeographic() methods. The OGRSpatialReference::GetSemiMajor(), OGRSpatialReference::GetSemiMinor() and OGRSpatialReference::GetInvFlattening() methods can be used to get information about the spheroid. The OGRSpatialReference::GetAttrValue() method can be used to get the PROJCS, GEOGCS, DATUM, SPHEROID, and PROJECTION names strings. The OGRSpatialReference::GetProjParm() method can be used to get the projection parameters. The OGRSpatialReference::GetLinearUnits() method can be used to fetch the linear units type, and translation to meters.

The following code (from ogr_srs_proj4.cpp) demonstrates use of GetAttrValue() to get the projection, and GetProjParm() to get projection parameters. The GetAttrValue() method searches for the first "value" node associated with the named entry in the WKT text representation. The #define'ed constants for projection parameters (such as SRS_PP_CENTRAL_MERIDIAN) should be used when fetching projection parameter with GetProjParm(). The code for the Set methods of the various projections in ogrspatialreference.cpp can be consulted to find which parameters apply to which projections.

const char *pszProjection = poSRS->GetAttrValue("PROJECTION");
if( pszProjection == NULL )
{
if( poSRS->IsGeographic() )
sprintf( szProj4+strlen(szProj4), "+proj=longlat " );
else
sprintf( szProj4+strlen(szProj4), "unknown " );
}
else if( EQUAL(pszProjection,SRS_PT_CYLINDRICAL_EQUAL_AREA) )
{
sprintf( szProj4+strlen(szProj4),
"+proj=cea +lon_0=%.9f +lat_ts=%.9f +x_0=%.3f +y_0=%.3f ",
}
...

Coordinate Transformation

The OGRCoordinateTransformation class is used for translating positions between different coordinate systems. New transformation objects are created using OGRCreateCoordinateTransformation(), and then the OGRCoordinateTransformation::Transform() method can be used to convert points between coordinate systems.

OGRSpatialReference oSourceSRS, oTargetSRS;
double x, y;
oSourceSRS.importFromEPSG( atoi(papszArgv[i+1]) );
oTargetSRS.importFromEPSG( atoi(papszArgv[i+2]) );
&oTargetSRS );
x = atof( papszArgv[i+3] );
y = atof( papszArgv[i+4] );
if( poCT == NULL || !poCT->Transform( 1, &x, &y ) )
printf( "Transformation failed.\n" );
else
printf( "(%f,%f) -> (%f,%f)\n",
atof( papszArgv[i+3] ),
atof( papszArgv[i+4] ),
x, y );

There are a couple of points at which transformations can fail. First, OGRCreateCoordinateTransformation() may fail, generally because the internals recognise that no transformation between the indicated systems can be established. This might be due to use of a projection not supported by the internal PROJ.4 library, differing datums for which no relationship is known, or one of the coordinate systems being inadequately defined. If OGRCreateCoordinateTransformation() fails it will return a NULL.

The OGRCoordinateTransformation::Transform() method itself can also fail. This may be as a delayed result of one of the above problems, or as a result of an operation being numerically undefined for one or more of the passed in points. The Transform() function will return TRUE on success, or FALSE if any of the points fail to transform. The point array is left in an indeterminate state on error.

Though not shown above, the coordinate transformation service can take 3D points, and will adjust elevations for elevation differences in spheroids, and datums. At some point in the future shifts between different vertical datums may also be applied. If no Z is passed, it is assume that the point is on the geoid.

The following example shows how to conveniently create a lat/long coordinate system using the same geographic coordinate system as a projected coordinate system, and using that to transform between projected coordinates and lat/long.

OGRSpatialReference oUTM, *poLatLong;
oUTM.SetProjCS("UTM 17 / WGS84");
oUTM.SetWellKnownGeogCS( "WGS84" );
oUTM.SetUTM( 17 );
poLatLong = oUTM.CloneGeogCS();
poTransform = OGRCreateCoordinateTransformation( &oUTM, poLatLong );
if( poTransform == NULL )
{
...
}
...
if( !poTransform->Transform( nPoints, x, y, z ) )
...

Alternate Interfaces

A C interface to the coordinate system services is defined in ogr_srs_api.h, and Python bindings are available via the osr.py module. Methods are close analogs of the C++ methods but C and Python bindings are missing for some C++ methods.

C Bindings

typedef void *OGRSpatialReferenceH;
OGRErr OSRSetAttrValue( OGRSpatialReferenceH hSRS, const char * pszNodePath,
const char * pszNewNodeValue );
const char * pszName, int iChild);
OGRErr OSRSetProjCS( OGRSpatialReferenceH hSRS, const char * pszName );
const char * pszName );
const char * pszGeogName,
const char * pszDatumName,
const char * pszEllipsoidName,
double dfSemiMajor, double dfInvFlattening,
const char * pszPMName ,
double dfPMOffset ,
const char * pszUnits,
double dfConvertToRadians );
const char * pszTargetKey,
const char * pszAuthority,
int nCode );
OGRErr OSRSetProjParm( OGRSpatialReferenceH, const char *, double );
const char * pszParmName,
double dfDefault,
OGRErr * );
OGRErr OSRSetUTM( OGRSpatialReferenceH hSRS, int nZone, int bNorth );
int OSRGetUTMZone( OGRSpatialReferenceH hSRS, int *pbNorth );
OGRSpatialReferenceH hTargetSRS );
int nCount, double *x, double *y, double *z );

Python Bindings

class osr.SpatialReference
def __init__(self,obj=None):
def ImportFromWkt( self, wkt ):
def ExportToWkt(self):
def ImportFromEPSG(self,code):
def IsGeographic(self):
def IsProjected(self):
def GetAttrValue(self, name, child = 0):
def SetAttrValue(self, name, value):
def SetWellKnownGeogCS(self, name):
def SetProjCS(self, name = "unnamed" ):
def IsSameGeogCS(self, other):
def IsSame(self, other):
def SetLinearUnits(self, units_name, to_meters ):
def SetUTM(self, zone, is_north = 1):
class CoordinateTransformation:
def __init__(self,source,target):
def TransformPoint(self, x, y, z = 0):
def TransformPoints(self, points):

Internal Implementation

The OGRCoordinateTransformation service is implemented on top of the PROJ.4 library originally written by Gerald Evenden of the USGS.

SRS_PP_CENTRAL_MERIDIAN
#define SRS_PP_CENTRAL_MERIDIAN
Definition: ogr_srs_api.h:269
SRS_UA_DEGREE_CONV
#define SRS_UA_DEGREE_CONV
Definition: ogr_srs_api.h:446
OSRSetUTM
OGRErr OSRSetUTM(OGRSpatialReferenceH hSRS, int nZone, int bNorth)
Set UTM projection definition.
Definition: ogrspatialreference.cpp:5879
OSRGetInvFlattening
double OSRGetInvFlattening(OGRSpatialReferenceH, OGRErr *)
Get spheroid inverse flattening.
Definition: ogrspatialreference.cpp:3130
OSRExportToWkt
OGRErr CPL_STDCALL OSRExportToWkt(OGRSpatialReferenceH, char **)
Convert this SRS into WKT format.
Definition: ogrspatialreference.cpp:753
OGRCoordinateTransformation::Transform
virtual int Transform(int nCount, double *x, double *y, double *z=nullptr)=0
OGRSpatialReference::SetWellKnownGeogCS
OGRErr SetWellKnownGeogCS(const char *)
Set a GeogCS based on well known name.
Definition: ogrspatialreference.cpp:1954
OSRSetProjParm
OGRErr OSRSetProjParm(OGRSpatialReferenceH, const char *, double)
Set a projection parameter value.
Definition: ogrspatialreference.cpp:3760
OGRSpatialReference::GetAttrValue
const char * GetAttrValue(const char *, int=0) const
Fetch indicated attribute of named node.
Definition: ogrspatialreference.cpp:545
OGRSpatialReference
Definition: ogr_spatialref.h:145
OGRCreateCoordinateTransformation
OGRCoordinateTransformation * OGRCreateCoordinateTransformation(OGRSpatialReference *poSource, OGRSpatialReference *poTarget)
Definition: ogrct.cpp:493
OSRSetAuthority
OGRErr OSRSetAuthority(OGRSpatialReferenceH hSRS, const char *pszTargetKey, const char *pszAuthority, int nCode)
Set the authority for a node.
Definition: ogrspatialreference.cpp:6146
OSRSetLinearUnits
OGRErr OSRSetLinearUnits(OGRSpatialReferenceH, const char *, double)
Set the linear units for the projection.
Definition: ogrspatialreference.cpp:1320
EQUAL
#define EQUAL(a, b)
Definition: cpl_port.h:559
OGRSpatialReference::SetProjCS
OGRErr SetProjCS(const char *)
Set the user visible PROJCS name.
Definition: ogrspatialreference.cpp:3581
OSRDereference
int OSRDereference(OGRSpatialReferenceH)
Decrements the reference count by one.
Definition: ogrspatialreference.cpp:368
OSRSetAttrValue
OGRErr CPL_STDCALL OSRSetAttrValue(OGRSpatialReferenceH hSRS, const char *pszNodePath, const char *pszNewNodeValue)
Set attribute value in spatial reference.
Definition: ogrspatialreference.cpp:983
OGRSpatialReferenceH
void * OGRSpatialReferenceH
Definition: ogr_api.h:74
OSRReference
int OSRReference(OGRSpatialReferenceH)
Increments the reference count by one.
Definition: ogrspatialreference.cpp:328
OSRSetProjCS
OGRErr OSRSetProjCS(OGRSpatialReferenceH hSRS, const char *pszName)
Set the user visible PROJCS name.
Definition: ogrspatialreference.cpp:3619
OGRCoordinateTransformationH
void * OGRCoordinateTransformationH
Definition: ogr_api.h:76
OCTDestroyCoordinateTransformation
void CPL_STDCALL OCTDestroyCoordinateTransformation(OGRCoordinateTransformationH)
OGRCoordinateTransformation destructor.
Definition: ogrct.cpp:438
OGRSpatialReference::SetGeogCS
OGRErr SetGeogCS(const char *pszGeogName, const char *pszDatumName, const char *pszEllipsoidName, double dfSemiMajor, double dfInvFlattening, const char *pszPMName=nullptr, double dfPMOffset=0.0, const char *pszUnits=nullptr, double dfConvertToRadians=0.0)
Set geographic coordinate system.
Definition: ogrspatialreference.cpp:1769
SRS_PP_STANDARD_PARALLEL_1
#define SRS_PP_STANDARD_PARALLEL_1
Definition: ogr_srs_api.h:273
OSRGetProjParm
double OSRGetProjParm(OGRSpatialReferenceH hSRS, const char *pszParmName, double dfDefault, OGRErr *)
Fetch a projection parameter value.
Definition: ogrspatialreference.cpp:3891
OSRGetSemiMinor
double OSRGetSemiMinor(OGRSpatialReferenceH, OGRErr *)
Get spheroid semi minor axis.
Definition: ogrspatialreference.cpp:3227
OSRSetGeogCS
OGRErr OSRSetGeogCS(OGRSpatialReferenceH hSRS, const char *pszGeogName, const char *pszDatumName, const char *pszEllipsoidName, double dfSemiMajor, double dfInvFlattening, const char *pszPMName, double dfPMOffset, const char *pszUnits, double dfConvertToRadians)
Set geographic coordinate system.
Definition: ogrspatialreference.cpp:1909
OSRGetLinearUnits
double OSRGetLinearUnits(OGRSpatialReferenceH, char **)
Fetch linear projection units.
Definition: ogrspatialreference.cpp:1503
OGRSpatialReference::importFromEPSG
OGRErr importFromEPSG(int)
Initialize SRS based on EPSG GCS or PCS code.
Definition: ogr_fromepsg.cpp:2137
OSRIsGeographic
int OSRIsGeographic(OGRSpatialReferenceH)
Check if geographic coordinate system.
Definition: ogrspatialreference.cpp:6566
OSRNewSpatialReference
OGRSpatialReferenceH CPL_STDCALL OSRNewSpatialReference(const char *)
Constructor.
Definition: ogrspatialreference.cpp:151
OSRDestroySpatialReference
void CPL_STDCALL OSRDestroySpatialReference(OGRSpatialReferenceH)
OGRSpatialReference destructor.
Definition: ogrspatialreference.cpp:242
OGRCoordinateTransformation
Definition: ogr_spatialref.h:673
OGRSpatialReference::CloneGeogCS
OGRSpatialReference * CloneGeogCS() const
Make a duplicate of the GEOGCS node of this OGRSpatialReference object.
Definition: ogrspatialreference.cpp:6669
OSRIsSame
int OSRIsSame(OGRSpatialReferenceH, OGRSpatialReferenceH)
Do these two spatial references describe the same system ?
Definition: ogrspatialreference.cpp:7261
OGRErr
int OGRErr
Definition: ogr_core.h:290
SRS_WGS84_SEMIMAJOR
#define SRS_WGS84_SEMIMAJOR
Definition: ogr_srs_api.h:463
OSRSetWellKnownGeogCS
OGRErr OSRSetWellKnownGeogCS(OGRSpatialReferenceH hSRS, const char *pszName)
Set a GeogCS based on well known name.
Definition: ogrspatialreference.cpp:2053
OCTTransform
int CPL_STDCALL OCTTransform(OGRCoordinateTransformationH hCT, int nCount, double *x, double *y, double *z)
Definition: ogrct.cpp:1046
SRS_PP_FALSE_EASTING
#define SRS_PP_FALSE_EASTING
Definition: ogr_srs_api.h:287
SRS_PT_CYLINDRICAL_EQUAL_AREA
#define SRS_PT_CYLINDRICAL_EQUAL_AREA
Definition: ogr_srs_api.h:107
OSRIsSameGeogCS
int OSRIsSameGeogCS(OGRSpatialReferenceH, OGRSpatialReferenceH)
Do the GeogCS'es match?
Definition: ogrspatialreference.cpp:6900
SRS_WGS84_INVFLATTENING
#define SRS_WGS84_INVFLATTENING
Definition: ogr_srs_api.h:465
OCTNewCoordinateTransformation
OGRCoordinateTransformationH CPL_STDCALL OCTNewCoordinateTransformation(OGRSpatialReferenceH hSourceSRS, OGRSpatialReferenceH hTargetSRS)
Definition: ogrct.cpp:542
OSRGetUTMZone
int OSRGetUTMZone(OGRSpatialReferenceH hSRS, int *pbNorth)
Get utm zone information.
Definition: ogrspatialreference.cpp:5957
OGRSpatialReference::exportToWkt
OGRErr exportToWkt(char **) const
Convert this SRS into WKT format.
Definition: ogrspatialreference.cpp:728
OSRImportFromWkt
OGRErr OSRImportFromWkt(OGRSpatialReferenceH, char **)
Import from WKT string.
Definition: ogrspatialreference.cpp:888
SRS_PP_FALSE_NORTHING
#define SRS_PP_FALSE_NORTHING
Definition: ogr_srs_api.h:289
OSRGetSemiMajor
double OSRGetSemiMajor(OGRSpatialReferenceH, OGRErr *)
Get spheroid semi major axis.
Definition: ogrspatialreference.cpp:3079
OGRSpatialReference::GetProjParm
double GetProjParm(const char *, double=0.0, OGRErr *=nullptr) const
Fetch a projection parameter value.
Definition: ogrspatialreference.cpp:3851
OGRSpatialReference::IsGeographic
int IsGeographic() const
Check if geographic coordinate system.
Definition: ogrspatialreference.cpp:6542
OSRImportFromEPSG
OGRErr CPL_STDCALL OSRImportFromEPSG(OGRSpatialReferenceH, int)
Initialize SRS based on EPSG GCS or PCS code.
Definition: ogr_fromepsg.cpp:2168
OSRIsProjected
int OSRIsProjected(OGRSpatialReferenceH)
Check if projected coordinate system.
Definition: ogrspatialreference.cpp:6476
OSRGetAttrValue
const char *CPL_STDCALL OSRGetAttrValue(OGRSpatialReferenceH hSRS, const char *pszName, int iChild)
Fetch indicated attribute of named node.
Definition: ogrspatialreference.cpp:568
OGRSpatialReference::SetUTM
OGRErr SetUTM(int nZone, int bNorth=TRUE)
Set UTM projection definition.
Definition: ogrspatialreference.cpp:5832

Generated for GDAL by doxygen 1.8.17.