1.. _rfc-39:
2
3=========================================================================
4RFC 39: OGR Layer Algebra
5=========================================================================
6
7Author: Ari Jolma
8
9Contact: ari dot jolma at aalto dot fi
10
11Status: Adopted, implemented in GDAL 1.10
12
13Summary
14-------
15
16It is proposed that the OGR layer class and the C API contains methods
17for commonly needed overlay analysis methods.
18
19The basic functionality for spatial analysis with GDAL is provided by
20GEOS. However, GEOS operates on geometries and typically people work
21with geospatial data layers. Vector data layers are represented in GDAL
22by OGRLayer objects. Thus, there is a need for spatial analaysis
23operations that work on layers.
24
25Unfortunately there is no standard for spatial analysis operations API,
26but it is possible to create a useful set by using existing software as
27example.
28
29The methods are fundamentally dependent on comparison of all the
30features of two layers. There would possibly be huge performance
31improvements achievable with layer specific spatial indexes. This is
32considered out of the scope of these methods and belonging to the
33general problem of iterating features in a layer and accessing features
34randomly. For these reasons these methods should be only considered
35convenience methods and not replacements for analysis in relational
36databases for example.
37
38Implementation
39--------------
40
41The methods are implemented by new methods in OGRLayer class
42(ogrsf_frmts.h and ogrlayer.cpp) and new calls in the C API (ogr_api.h).
43The Swig bindings (ogr.i) are also extended with these methods.
44
45The patch with the changes to OGR core and to the Swig bindings is
46attached to this page. The patch has been superficially tested but it is
47not written or formatted according to the GDAL tradition.
48
49Backward Compatibility
50----------------------
51
52Proposed additions will have an impact on C binary compatibility because
53they change the API.
54
55C++ binary interface will be broken (due to the addition of a new
56members in OGRLayer class).
57
58The changes are purely extensions and have no impact on existing code.
59
60Impact on drivers
61-----------------
62
63The changes do not have any impacts on drivers.
64
65Timeline
66--------
67
68Ari Jolma is responsible to implement this proposal. New API should be
69available in GDAL 1.11.
70
71There needs to be a discussion on the names of the methods and on the
72internal logic of the methods (this refers especially to the handling of
73attributes and error conditions).
74
75In addition to the methods in the attached patch, there should be some
76discussion on additional methods. For example Append and Buffer methods
77could be easily added to the set. An illustration of what is currently
78available in the common software is for example this page:
79`http://courses.washington.edu/gis250/lessons/Model_Builder/ <http://courses.washington.edu/gis250/lessons/Model_Builder/>`__
80
81Comments on performance
82-----------------------
83
84Profiling Intersection of a layer of 46288 line string features with a
85layer of one polygon feature (~1/3 of features within and many only
86partly within the one feature) showed that when the method layer was a
87Shapefile, most of the time was spent in reading the feature from the
88Shapefile. When the method layer was copied into memory, most of the
89time (83 %) was spent in OGRLineString::getEnvelope. The 6th version of
90the patch contains a test against a pre-computed layer envelope, which
91speeds up the computation in this case ~30% (from 2.44 s to 1.76 in my
92machine). Still the most of the time (82 %) is spent in
93OGRLineString::getEnvelope.
94
95Voting history
96--------------
97
98(June 2012) +1 from Even, Frank, Howard, Tamas, Daniel
99