NAME
ogr_arch - OGR Architecture 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.
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 Open GIS Consortium web
site. Data types, and method names are modelled on those from the
interface specifications.
Class Overview
· Geometry (ogr_geometry.h): The geometry classes (OGRGeometry, 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).
· Spatial Reference (ogr_spatialref.h): An OGRSpatialReference
encapsulates the definition of a projection and datum.
· Feature (ogr_feature.h): The OGRFeature encapsulate the definition of
a whole feature, that is a geometry and a set of attributes.
· Feature Class Definition (ogr_feature.h): The OGRFeatureDefn class
capsures the schema (set of field definitions) for a group of related
features (normally a whole layer).
· Layer (ogrsf_frmts.h): OGRLayer is an abstract base class represent a
layer of features in an OGRDataSource.
· Data Source (ogrsf_frmts.h): An OGRDataSource is an abstract base
class representing a file or database containing one or more OGRLayer
objects.
· Drivers (ogrsf_frmts.h): An OGRSFDriver represents a translator for a
specific format, opening OGRDataSource objects. All available drivers
are managed by the OGRSFDriverRegistrar.
Geometry
The geometry classes are represent various kinds of vector geometry.
All the geometry classes derived from OGRGeometry which defines the
common services of all geometries. Types of geometry include OGRPoint,
OGRLineString, OGRPolygon, OGRGeometryCollection, OGRMultiPolygon,
OGRMultiPoint, and OGRMultiLineString.
Additional intermediate abstract base classes contain functionality
that could eventually be implemented by other geometry types. These
include OGRCurve (base class for OGRLineString) and OGRSurface (base
class for OGRPolygon). 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.
The OGRGeometryFactory 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.
In a manner based on the geometry object in SFCOM, the OGRGeometry
includes a reference to an OGRSpatialReference 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 OGRGeometry objects using it.
Many of the spatial analysis methods (such as computing overlaps and so
forth) are not implemented at this time for OGRGeometry.
While it is theoretically possible to derive other or more specific
geometry classes from the existing OGRGeometry classes, this isn’t as
aspect that has been well thought out. In particular, it would be
possible to create specialized classes using the OGRGeometryFactory
without modifying it.
Spatial Reference
The OGRSpatialReference 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 not supported.
The spatial coordinate system data model is inherited from the OpenGIS
Well Known Text 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 OGRSpatialReference is
built on the features of the Coordinate Transformation specification
but is intended to be compatible with the earlier simple features form.
There is also an associated OGRCoordinateTransformation class that
encapsulates use of PROJ.4 for converting between different coordinate
systems. There is a tutorial available describing how to use the
OGRSpatialReference class.
Feature / Feature Definition
The OGRGeometry captures the geometry of a vector feature ... the
spatial position/region of a feature. The OGRFeature contains this
geometry, and adds feature attributes, feature id, and a feature class
identify.
The set of attributes, their types, names and so forth is represented
via the OGRFeatureDefn class. One OGRFeatureDefn 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).
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.
The feature class also contains an indicator of the types of geometry
allowed for that feature class (returned as an OGRwkbGeometryType from
OGRFeatureDefn::GetGeomType()). 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.
The OGRFeatureDefn also contains a concept of default spatial reference
system for all features of that type and a feature class name (normally
used as a layer name).
Layer
An OGRLayer represents a layer of features within a data source. All
features in an OGRLayer share a common schema and are of the same
OGRFeatureDefn. An OGRLayer class also contains methods for reading
features from the data source. The OGRLayer 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 OGRLayer represents a spatial table.
The OGRLayer includes methods for sequential and random reading and
writing. Read access (via the OGRLayer::GetNextFeature() 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 OGRLayer (via the
OGRLayer::SetSpatialFilter() method).
One flaw in the current OGR architecture is that the spatial filter is
set directly on the OGRLayer 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 introduct an OGRLayerView class or something similar.
Another question that might arise is why the OGRLayer and
OGRFeatureDefn classes are distinct. An OGRLayer always has a one-to-
one relationship to an OGRFeatureDefn, so why not amalgamate the
classes. There are two reasons:
1. As defined now OGRFeature and OGRFeatureDefn don’t depend on
OGRLayer, so they can exist independently in memory without regard
to a particular layer in a data store.
2. 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.
The OGRLayer 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 OGRDataSource, and
aren’t instantiated or destroyed directly.
Data Source
An OGRDataSource represents a set of OGRLayer objects. This usually
represents a single file, set of files, database or gateway. An
OGRDataSource has a list of OGRLayer’s which it owns but can return
references to.
OGRDataSource is an abstract base class. An implementation is expected
to be subclassed for each file format driver implemented. OGRDataSource
objects are not normally instantiated directly but rather with the
assistance of an OGRSFDriver. Deleting an OGRDataSource closes access
to the underlying persistent data source, but does not normally result
in deletion of that file.
An OGRDataSource has a name (usually a filename) that can be used to
reopen the data source with an OGRSFDriver.
The OGRDataSource also has support for executing a datasource specific
command, normally a form of SQL. This is accomplished via the
OGRDataSource::ExecuteSQL() 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.
Drivers
An OGRSFDriver object is instantiated for each file format supported.
The OGRSFDriver objects are registered with the OGRSFDriverRegistrar, a
singleton class that is normally used to open new data sources.
It is intended that a new OGRSFDriver derived class be implemented for
each file format to be supported (along with a file format specific
OGRDataSource, and OGRLayer classes).
On application startup registration functions are normally called for
each desired file format. These functions instantiate the appropriate
OGRSFDriver objects, and register them with the OGRSFDriverRegistrar.
When a data source is to be opened, the registrar will normally try
each OGRSFDriver in turn, until one succeeds, returning an
OGRDataSource object.
It is not intended that the OGRSFDriverRegistrar be derived from.