History

Note: This document is still a work in progress.

Introduction

This document describes my plans for the creation of Qgs``Vector``File``Writer, a generic class for writing shapefiles (and other vector formats) using GDAL. Ill keep the name generic becauase gdal allows writing other file types too. Qgs``Vector``File``Writer will provide an abstraction layer for the OGR stuff so we can hopefully use it in two ways:

Example 1: To write a layer with a single call

 QgsVectorFileWriter  * myVectorFileWriter=new QgsVectorFileWriter  
 (QgsVectorFileWriter::SHAPE_FILE, QgsMapLayer  theVectorLayer, QString theOutputFileName);

Example 2: To write arbitary vectors to a file:

 QgsVectorFileWriter myQgsVectorFileWriter = new QgsVectorFileWriter();
 QgsVectorFileWriter->setType(QgsVectorFileWriter::SHAPE_FILE);
 QgsVectorFileWriter->createAttributeFields(QValueVector * theFieldDescriptorVector);
 QgsVectorFileWriter->setFeatureType(QgsVectorFileWriter::POINT);
 QgsVectorFileWriter->writeFeature(QValueVector theAttributeVector, QValueVector

theVertexVector);

Obviously the above is just a quick brain dump and there is stuff not considered here - e.g. mutipart features probably need a vector of vertex vectors - one for each constituant part. But the idea would be that example 1 could be used for file conversion operations (Layer Save As...)and the second could be used for plugins etc for converting generated vector layers to some persistent format.

General Notes on GDAL/OGR useage

Below is a transcript of my initial query to the GDAL list:

 Tim Sutton wrote:
 > -----BEGIN PGP SIGNED MESSAGE-----
 > Hash: SHA1
 > 
 > Hi
 > 
 > Can someone point me to a short code sample on writing a shapefile using ogr. 
 > Currently I have written stuff using Franks shapelib, but am wondering if ogr 
 > is better suited to this purpose in that:
 > 
 > a) qgis already has gdal/ogr deps
 > b) ogr provides a c++ interface

Tim,

It seems there is no OGR API Tutorial. I would encourage you to review the
OGR Architecture document for general information on OGR:

http://www.remotesensing.org/gdal/ogr/ogr_arch.html

The gdal/ogr/ogr2ogr.cpp program is a respectible example of how to use
OGR to write files, though it is a bit complicated since it tries to do alot
of things during translation.

The general idea is you need to following the following steps:

  • Register driver(s) (at least the Shapefile driver).
  • Get the driver - OGRSF``Driver``Registrar::Get``Driver``By``Name().
  • Create the shapefile (OGRSF``Driver::Create``Data``Source()). You can give the name of the shapefile (with .shp extension) to create a single file. Otherwise the shapefile driver will create a directory, and a file set for each layer.
  • Create the desired layer (OGR``Data``Source::Create``Layer() - the layer name should likely match the basename of the shapefile you created before). Set the geometry type to determine the file type you want to create.
  • Create all the fields you want for the layer with OGR``Layer::Create``Field().
  • For each feature to be written, create a feature with OGRFeature::Create``Feature(),passing in the layer definition from the layer.
  • Assign each attribute to the feature in turn.
  • Create a geometry and assign it to the feature. There are various methods for geometry construction depending on what you want.
  • Write the feature to the file with the OGRLayer::Create``Feature() method.
  • Delete your copy of the feature (ie. with OGRFeature::Destroy``Feature()).
  • Make sure you delete the datasource when you are done to ensure it is properly closed and flushed to disk.

If you only ever want to write to shapefiles, using OGR won't give you any substantial advantages, but assuming you are interested in writing other formats too, it should be a useful step.

Best regards,

Frank Warmerdam