OGR API Tutorial

This document is intended to document using the OGR C++ classes to read and write data from a file. It is strongly advised that the read first review the OGR Architecture document describing the key classes and their roles in OGR.

It also includes code snippets for the corresponding functions in C and Python.

Reading From OGR

For purposes of demonstrating reading with OGR, we will construct a small utility for dumping point layers from an OGR data source to stdout in comma-delimited format.

Initially it is necessary to register all the format drivers that are desired. This is normally accomplished by calling 

GDALAllRegister() which registers all format drivers built into GDAL/OGR.

In C++ :

#include "ogrsf_frmts.h" int main() { GDALAllRegister();

In C :

#include "gdal.h" int main() { GDALAllRegister();

Next we need to open the input OGR datasource. Datasources can be files, RDBMSes, directories full of files, or even remote web services depending on the driver being used. However, the datasource name is always a single string. In this case we are hardcoded to open a particular shapefile. The second argument (GDAL_OF_VECTOR) tells the OGROpen() method that we want a vector driver to be use and that don't require update access. On failure NULL is returned, and we report an error.

In C++ :

GDALDataset *poDS; poDS = ( GDALDataset*) GDALOpenEx( "point.shp", GDAL_OF_VECTOR, NULL, NULL, NULL ); if( poDS == NULL ) { printf( "Open failed.\n" ); exit( 1 ); }

In C :

GDALDatasetH hDS; hDS = GDALOpenEx( "point.shp", GDAL_OF_VECTOR, NULL, NULL, NULL ); if( hDS == NULL ) { printf( "Open failed.\n" ); exit( 1 ); }

A GDALDataset can potentially have many layers associated with it. The number of layers available can be queried with GDALDataset::GetLayerCount() and individual layers fetched by index using GDALDataset::GetLayer(). However, we will just fetch the layer by name.

In C++ :

OGRLayer *poLayer; poLayer = poDS-> GetLayerByName( "point" );

In C :

OGRLayerH hLayer; hLayer = GDALDatasetGetLayerByName( hDS, "point" );

Now we want to start reading features from the layer. Before we start we could assign an attribute or spatial filter to the layer to restrict the set of feature we get back, but for now we are interested in getting all features.

While it isn't strictly necessary in this circumstance since we are starting fresh with the layer, it is often wise to call OGRLayer::ResetReading() to ensure we are starting at the beginning of the layer. We iterate through all the features in the layer usingOGRLayer::GetNextFeature(). It will return NULL when we run out of features.

In C++ :

OGRFeature *poFeature; poLayer-> ResetReading(); while( (poFeature = poLayer-> GetNextFeature()) != NULL ) {

In C :

OGRFeatureH hFeature; OGR_L_ResetReading(hLayer); while( (hFeature = OGR_L_GetNextFeature(hLayer)) != NULL ) {

In order to dump all the attribute fields of the feature, it is helpful to get the OGRFeatureDefn. This is an object, associated with the layer, containing the definitions of all the fields. We loop over all the fields, and fetch and report the attributes based on their type.

In C++ :

OGRFeatureDefn *poFDefn = poLayer-> GetLayerDefn(); int iField; for( iField = 0; iField < poFDefn-> GetFieldCount(); iField++ ) { OGRFieldDefn *poFieldDefn = poFDefn-> GetFieldDefn( iField ); if( poFieldDefn-> GetType() == OFTInteger ) printf( "%d,", poFeature-> GetFieldAsInteger( iField ) ); else if( poFieldDefn-> GetType() == OFTInteger64 ) printf( CPL_FRMT_GIB ",", poFeature-> GetFieldAsInteger64( iField ) ); else if( poFieldDefn-> GetType() == OFTReal ) printf( "%.3f,", poFeature-> GetFieldAsDouble(iField) ); else if( poFieldDefn-> GetType() == OFTString ) printf( "%s,", poFeature-> GetFieldAsString(iField) ); else printf( "%s,", poFeature-> GetFieldAsString(iField) ); }

In C :

OGRFeatureDefnH hFDefn = OGR_L_GetLayerDefn(hLayer); int iField; for( iField = 0; iField < OGR_FD_GetFieldCount(hFDefn); iField++ ) { OGRFieldDefnH hFieldDefn = OGR_FD_GetFieldDefn( hFDefn, iField ); if( OGR_Fld_GetType(hFieldDefn) == OFTInteger ) printf( "%d,", OGR_F_GetFieldAsInteger( hFeature, iField ) ); else if( OGR_Fld_GetType(hFieldDefn) == OFTInteger64 ) printf( CPL_FRMT_GIB ",", OGR_F_GetFieldAsInteger64( hFeature, iField ) ); else if( OGR_Fld_GetType(hFieldDefn) == OFTReal ) printf( "%.3f,", OGR_F_GetFieldAsDouble( hFeature, iField) ); else if( OGR_Fld_GetType(hFieldDefn) == OFTString ) printf( "%s,", OGR_F_GetFieldAsString( hFeature, iField) ); else printf( "%s,", OGR_F_GetFieldAsString( hFeature, iField) ); }

There are a few more field types than those explicitly handled above, but a reasonable representation of them can be fetched with the OGRFeature::GetFieldAsString() method. In fact we could shorten the above by using OGRFeature::GetFieldAsString() for all the types.

Next we want to extract the geometry from the feature, and write out the point geometry x and y. Geometries are returned as a generic OGRGeometry pointer. We then determine the specific geometry type, and if it is a point, we cast it to point and operate on it. If it is something else we write placeholders.

In C++ :

OGRGeometry *poGeometry; poGeometry = poFeature-> GetGeometryRef(); if( poGeometry != NULL && wkbFlatten(poGeometry-> getGeometryType()) == wkbPoint ) { OGRPoint *poPoint = ( OGRPoint *) poGeometry; printf( "%.3f,%3.f\n", poPoint-> getX(), poPoint-> getY() ); } else { printf( "no point geometry\n" ); }

In C :

OGRGeometryH hGeometry; hGeometry = OGR_F_GetGeometryRef(hFeature); if( hGeometry != NULL && wkbFlatten( OGR_G_GetGeometryType(hGeometry)) == wkbPoint ) { printf( "%.3f,%3.f\n", OGR_G_GetX(hGeometry, 0), OGR_G_GetY(hGeometry, 0) ); } else { printf( "no point geometry\n" ); }

The wkbFlatten() macro is used above to convert the type for a wkbPoint25D (a point with a z coordinate) into the base 2D geometry type code (wkbPoint). For each 2D geometry type there is a corresponding 2.5D type code. The 2D and 2.5D geometry cases are handled by the same C++ class, so our code will handle 2D or 3D cases properly.

Starting with OGR 1.11, several geometry fields can be associated to a feature.

In C++ :

OGRGeometry *poGeometry; int iGeomField; int nGeomFieldCount; nGeomFieldCount = poFeature-> GetGeomFieldCount(); for(iGeomField = 0; iGeomField < nGeomFieldCount; iGeomField ++ ) { poGeometry = poFeature-> GetGeomFieldRef(iGeomField); if( poGeometry != NULL && wkbFlatten(poGeometry-> getGeometryType()) == wkbPoint ) { OGRPoint *poPoint = ( OGRPoint *) poGeometry; printf( "%.3f,%3.f\n", poPoint-> getX(), poPoint-> getY() ); } else { printf( "no point geometry\n" ); } }

In C :

OGRGeometryH hGeometry; int iGeomField; int nGeomFieldCount; nGeomFieldCount = OGR_F_GetGeomFieldCount(hFeature); for(iGeomField = 0; iGeomField < nGeomFieldCount; iGeomField ++ )