EVOLUTION-MANAGER
Edit File: ogr_arch.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> <meta http-equiv="X-UA-Compatible" content="IE=9"/> <meta name="generator" content="Doxygen 1.8.5"/> <title>OGR: OGR Architecture</title> <link href="tabs.css" rel="stylesheet" type="text/css"/> <script type="text/javascript" src="jquery.js"></script> <script type="text/javascript" src="dynsections.js"></script> <link href="doxygen.css" rel="stylesheet" type="text/css" /> </head> <body> <div id="top"><!-- do not remove this div, it is closed by doxygen! --> <div id="titlearea"> <table cellspacing="0" cellpadding="0"> <tbody> <tr style="height: 56px;"> <td style="padding-left: 0.5em;"> <div id="projectname">OGR </div> </td> </tr> </tbody> </table> </div> <!-- end header part --> <!-- Generated by Doxygen 1.8.5 --> <div id="navrow1" class="tabs"> <ul class="tablist"> <li><a href="index.html"><span>Main Page</span></a></li> <li class="current"><a href="pages.html"><span>Related Pages</span></a></li> <li><a href="annotated.html"><span>Classes</span></a></li> <li><a href="files.html"><span>Files</span></a></li> </ul> </div> </div><!-- top --> <div class="header"> <div class="headertitle"> <div class="title">OGR Architecture </div> </div> </div><!--header--> <div class="contents"> <div class="textblock"><p>This document is intended to document the OGR classes. The OGR classes are intended to be generic (not specific to OLE DB or COM or Windows) but are used as a foundation for implementing OLE DB Provider support, as well as client side support for SFCOM. It is intended that these same OGR classes could be used by an implementation of SFCORBA for instance or used directly by C++ programs wanting to use an OpenGIS simple features inspired API.</p> <p>Because OGR is modelled on the OpenGIS simple features data model, it is very helpful to review the SFCOM, or other simple features interface specifications which can be retrieved from the <a href="http://www.opengeospatial.org">Open Geospatial Consortium</a> web site. Data types, and method names are modelled on those from the interface specifications.</p> <h1><a class="anchor" id="ogr_arch_overview"></a> Class Overview</h1> <ul> <li> <p class="startli"><b>Geometry</b> (<a href="ogr__geometry_8h-source.html">ogr_geometry.h</a>): The geometry classes (<a class="el" href="classOGRGeometry.html">OGRGeometry</a>, etc) encapsulate the OpenGIS model vector data as well as providing some geometry operations, and translation to/from well known binary and text format. A geometry includes a spatial reference system (projection).</p> <p></p> <p class="endli"></p> </li> <li> <p class="startli"><b>Spatial Reference</b> (<a href="ogr__spatialref_8h-source.html">ogr_spatialref.h</a>): An <a class="el" href="classOGRSpatialReference.html">OGRSpatialReference</a> encapsulates the definition of a projection and datum.</p> <p></p> <p class="endli"></p> </li> <li> <p class="startli"><b>Feature</b> (<a href="ogr__feature_8h-source.html">ogr_feature.h</a>): The <a class="el" href="classOGRFeature.html">OGRFeature</a> encapsulates the definition of a whole feature, that is a geometry and a set of attributes.</p> <p></p> <p class="endli"></p> </li> <li> <p class="startli"><b>Feature Class Definition</b> (<a href="ogr__feature_8h-source.html">ogr_feature.h</a>): The <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a> class captures the schema (set of field definitions) for a group of related features (normally a whole layer).</p> <p></p> <p class="endli"></p> </li> <li> <p class="startli"><b>Layer</b> (<a href="ogrsf__frmts_8h-source.html">ogrsf_frmts.h</a>): <a class="el" href="classOGRLayer.html">OGRLayer</a> is an abstract base class represent a layer of features in an <a class="el" href="classOGRDataSource.html">OGRDataSource</a>.</p> <p></p> <p class="endli"></p> </li> <li> <p class="startli"><b>Data Source</b> (<a href="ogrsf__frmts_8h-source.html">ogrsf_frmts.h</a>): An <a class="el" href="classOGRDataSource.html">OGRDataSource</a> is an abstract base class representing a file or database containing one or more <a class="el" href="classOGRLayer.html">OGRLayer</a> objects.</p> <p></p> <p class="endli"></p> </li> <li> <p class="startli"><b>Drivers</b> (<a href="ogrsf__frmts_8h-source.html">ogrsf_frmts.h</a>): An <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a> represents a translator for a specific format, opening <a class="el" href="classOGRDataSource.html">OGRDataSource</a> objects. All available drivers are managed by the <a class="el" href="classOGRSFDriverRegistrar.html">OGRSFDriverRegistrar</a>.</p> <p></p> <p class="endli"></p> </li> </ul> <h1><a class="anchor" id="ogr_arch_geometry"></a> Geometry</h1> <p>The geometry classes are represent various kinds of vector geometry. All the geometry classes derived from <a class="el" href="classOGRGeometry.html">OGRGeometry</a> which defines the common services of all geometries. Types of geometry include <a class="el" href="classOGRPoint.html">OGRPoint</a>, <a class="el" href="classOGRLineString.html">OGRLineString</a>, <a class="el" href="classOGRPolygon.html">OGRPolygon</a>, <a class="el" href="classOGRGeometryCollection.html">OGRGeometryCollection</a>, <a class="el" href="classOGRMultiPolygon.html">OGRMultiPolygon</a>, <a class="el" href="classOGRMultiPoint.html">OGRMultiPoint</a>, and <a class="el" href="classOGRMultiLineString.html">OGRMultiLineString</a>.</p> <p>Additional intermediate abstract base classes contain functionality that could eventually be implemented by other geometry types. These include <a class="el" href="classOGRCurve.html">OGRCurve</a> (base class for <a class="el" href="classOGRLineString.html">OGRLineString</a>) and <a class="el" href="classOGRSurface.html">OGRSurface</a> (base class for <a class="el" href="classOGRPolygon.html">OGRPolygon</a>). Some intermediate interfaces modelled in the simple features abstract model and SFCOM are not modelled in OGR at this time. In most cases the methods are aggregated into other classes. This may change.</p> <p>The <a class="el" href="classOGRGeometryFactory.html">OGRGeometryFactory</a> is used to convert well known text, and well known binary format data into geometries. These are predefined ASCII and binary formats for representing all the types of simple features geometries.</p> <p>In a manner based on the geometry object in SFCOM, the <a class="el" href="classOGRGeometry.html">OGRGeometry</a> includes a reference to an <a class="el" href="classOGRSpatialReference.html">OGRSpatialReference</a> object, defining the spatial reference system of that geometry. This is normally a reference to a shared spatial reference object with reference counting for each of the <a class="el" href="classOGRGeometry.html">OGRGeometry</a> objects using it.</p> <p>Many of the spatial analysis methods (such as computing overlaps and so forth) are not implemented at this time for <a class="el" href="classOGRGeometry.html">OGRGeometry</a>.</p> <p>While it is theoretically possible to derive other or more specific geometry classes from the existing <a class="el" href="classOGRGeometry.html">OGRGeometry</a> classes, this isn't an aspect that has been well thought out. In particular, it would be possible to create specialized classes using the <a class="el" href="classOGRGeometryFactory.html">OGRGeometryFactory</a> without modifying it.</p> <h1><a class="anchor" id="ogr_arch_srs"></a> Spatial Reference</h1> <p>The <a class="el" href="classOGRSpatialReference.html">OGRSpatialReference</a> class is intended to store an OpenGIS Spatial Reference System definition. Currently local, geographic and projected coordinate systems are supported. Vertical coordinate systems, geocentric coordinate systems, and compound (horizontal + vertical) coordinate systems are as well supported in recent GDAL versions.</p> <p>The spatial coordinate system data model is inherited from the OpenGIS <b>Well Known Text</b> format. A simple form of this is defined in the Simple Features specifications. A more sophisticated form is found in the Coordinate Transformation specification. The <a class="el" href="classOGRSpatialReference.html">OGRSpatialReference</a> is built on the features of the Coordinate Transformation specification but is intended to be compatible with the earlier simple features form.</p> <p>There is also an associated <a class="el" href="classOGRCoordinateTransformation.html">OGRCoordinateTransformation</a> class that encapsulates use of PROJ.4 for converting between different coordinate systems. There is a <a href="osr_tutorial.html">tutorial</a> available describing how to use the <a class="el" href="classOGRSpatialReference.html">OGRSpatialReference</a> class.</p> <h1><a class="anchor" id="ogr_arch_feature"></a> Feature / Feature Definition</h1> <p>The <a class="el" href="classOGRGeometry.html">OGRGeometry</a> captures the geometry of a vector feature ... the spatial position/region of a feature. The <a class="el" href="classOGRFeature.html">OGRFeature</a> contains this geometry, and adds feature attributes, feature id, and a feature class identifier. Starting with OGR 1.11, <a href="http://trac.osgeo.org/gdal/wiki/rfc41_multiple_geometry_fields">several geometries</a> can be associated to a <a class="el" href="classOGRFeature.html">OGRFeature</a>.</p> <p>The set of attributes, their types, names and so forth is represented via the <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a> class. One <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a> normally exists for a layer of features. The same definition is shared in a reference counted manner by the feature of that type (or feature class).</p> <p>The feature id (FID) of a feature is intended to be a unique identifier for the feature within the layer it is a member of. Freestanding features, or features not yet written to a layer may have a null (OGRNullFID) feature id. The feature ids are modelled in OGR as a long integer; however, this is not sufficiently expressive to model the natural feature ids in some formats. For instance, the GML feature id is a string, and the row id in Oracle is larger than 4 bytes.</p> <p>The feature class also contains an indicator of the types of geometry allowed for that feature class (returned as an OGRwkbGeometryType from <a class="el" href="classOGRFeatureDefn.html#a81a7dc7ed24fe9f2634bf447d1799e84" title="Fetch the geometry base type. ">OGRFeatureDefn::GetGeomType()</a>). If this is wkbUnknown then any type of geometry is allowed. This implies that features in a given layer can potentially be of different geometry types though they will always share a common attribute schema. </p> <p>Starting with OGR 1.11, several geometry fields can be associated to a feature class. Each geometry field has its own indicator of geometry type allowed, returned by <a class="el" href="classOGRGeomFieldDefn.html#a1b628044cd6d2142a1732f5c5ef41bd6" title="Fetch geometry type of this field. ">OGRGeomFieldDefn::GetType()</a>, and its spatial reference system, returned by <a class="el" href="classOGRGeomFieldDefn.html#ae043691f36413950ea2ec0c3495ac959" title="Fetch spatial reference system of this field. ">OGRGeomFieldDefn::GetSpatialRef()</a>.</p> <p>The <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a> also contains a feature class name (normally used as a layer name).</p> <h1><a class="anchor" id="ogr_arch_layer"></a> Layer</h1> <p>An <a class="el" href="classOGRLayer.html">OGRLayer</a> represents a layer of features within a data source. All features in an <a class="el" href="classOGRLayer.html">OGRLayer</a> share a common schema and are of the same <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a>. An <a class="el" href="classOGRLayer.html">OGRLayer</a> class also contains methods for reading features from the data source. The <a class="el" href="classOGRLayer.html">OGRLayer</a> can be thought of as a gateway for reading and writing features from an underlying data source, normally a file format. In SFCOM and other table based simple features implementation an <a class="el" href="classOGRLayer.html">OGRLayer</a> represents a spatial table.</p> <p>The <a class="el" href="classOGRLayer.html">OGRLayer</a> includes methods for sequential and random reading and writing. Read access (via the <a class="el" href="classOGRLayer.html#a47d21ff33b32d14fa4e9885b9edecad6" title="Fetch the next available feature from this layer. ">OGRLayer::GetNextFeature()</a> method) normally reads all features, one at a time sequentially; however, it can be limited to return features intersecting a particular geographic region by installing a spatial filter on the <a class="el" href="classOGRLayer.html">OGRLayer</a> (via the <a class="el" href="classOGRLayer.html#a0b4ab45cf97cbc470f0d60474d3e4169" title="Set a new spatial filter. ">OGRLayer::SetSpatialFilter()</a> method).</p> <p>One flaw in the current OGR architecture is that the spatial filter is set directly on the <a class="el" href="classOGRLayer.html">OGRLayer</a> which is intended to be the only representative of a given layer in a data source. This means it isn't possible to have multiple read operations active at one time with different spatial filters on each. This aspect may be revised in the future to introduce an OGRLayerView class or something similar.</p> <p>Another question that might arise is why the <a class="el" href="classOGRLayer.html">OGRLayer</a> and <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a> classes are distinct. An <a class="el" href="classOGRLayer.html">OGRLayer</a> always has a one-to-one relationship to an <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a>, so why not amalgamate the classes. There are two reasons:</p> <ol> <li> <p class="startli">As defined now <a class="el" href="classOGRFeature.html">OGRFeature</a> and <a class="el" href="classOGRFeatureDefn.html">OGRFeatureDefn</a> don't depend on <a class="el" href="classOGRLayer.html">OGRLayer</a>, so they can exist independently in memory without regard to a particular layer in a data store. </p> <p></p> <p class="endli"></p> </li> <li> <p class="startli">The SF CORBA model does not have a concept of a layer with a single fixed schema the way that the SFCOM and SFSQL models do. The fact that features belong to a feature collection that is potentially not directly related to their current feature grouping may be important to implementing SFCORBA support using OGR.</p> <p class="endli"></p> </li> </ol> <p>The <a class="el" href="classOGRLayer.html">OGRLayer</a> class is an abstract base class. An implementation is expected to be subclassed for each file format driver implemented. OGRLayers are normally owned directly by their <a class="el" href="classOGRDataSource.html">OGRDataSource</a>, and aren't instantiated or destroyed directly.</p> <h1><a class="anchor" id="ogr_arch_data_source"></a> Data Source</h1> <p>An <a class="el" href="classOGRDataSource.html">OGRDataSource</a> represents a set of <a class="el" href="classOGRLayer.html">OGRLayer</a> objects. This usually represents a single file, set of files, database or gateway. An <a class="el" href="classOGRDataSource.html">OGRDataSource</a> has a list of OGRLayers which it owns but can return references to.</p> <p><a class="el" href="classOGRDataSource.html">OGRDataSource</a> is an abstract base class. An implementation is expected to be subclassed for each file format driver implemented. <a class="el" href="classOGRDataSource.html">OGRDataSource</a> objects are not normally instantiated directly but rather with the assistance of an <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a>. Deleting an <a class="el" href="classOGRDataSource.html">OGRDataSource</a> closes access to the underlying persistent data source, but does not normally result in deletion of that file.</p> <p>An <a class="el" href="classOGRDataSource.html">OGRDataSource</a> has a name (usually a filename) that can be used to reopen the data source with an <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a>.</p> <p>The <a class="el" href="classOGRDataSource.html">OGRDataSource</a> also has support for executing a datasource specific command, normally a form of SQL. This is accomplished via the <a class="el" href="classOGRDataSource.html#aa6acc228db6513784a56ce12334a8c33" title="Execute an SQL statement against the data store. ">OGRDataSource::ExecuteSQL()</a> method. While some datasources (such as PostGIS and Oracle) pass the SQL through to an underlying database, OGR also includes support for evaluating a subset of the SQL SELECT statement against any datasource. </p> <h1><a class="anchor" id="ogr_arch_drivers"></a> Drivers</h1> <p>An <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a> object is instantiated for each file format supported. The <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a> objects are registered with the <a class="el" href="classOGRSFDriverRegistrar.html">OGRSFDriverRegistrar</a>, a singleton class that is normally used to open new data sources.</p> <p>It is intended that a new <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a> derived class be implemented for each file format to be supported (along with a file format specific <a class="el" href="classOGRDataSource.html">OGRDataSource</a>, and <a class="el" href="classOGRLayer.html">OGRLayer</a> classes).</p> <p>On application startup registration functions are normally called for each desired file format. These functions instantiate the appropriate <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a> objects, and register them with the <a class="el" href="classOGRSFDriverRegistrar.html">OGRSFDriverRegistrar</a>. When a data source is to be opened, the registrar will normally try each <a class="el" href="classOGRSFDriver.html">OGRSFDriver</a> in turn, until one succeeds, returning an <a class="el" href="classOGRDataSource.html">OGRDataSource</a> object.</p> <p>It is not intended that the <a class="el" href="classOGRSFDriverRegistrar.html">OGRSFDriverRegistrar</a> be derived from.</p> </div></div><!-- contents --> <hr> Generated for GDAL by <a href="http://www.doxygen.org/index.html"><img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.8.5. </body> </html>