Changes between Version 19 and Version 20 of rfc61_support_for_measured_geometries

Timestamp:

Jan 28, 2016, 11:17:21 PM (8 years ago)

Author:

Ari Jolma

Comment:

--

rfc61_support_for_measured_geometries

@@ -23 +23 @@
 === Common API ===
 
-New OGRwkbGeometryType values are needed - that is a rather complex system due to history. SFSQL 1.2 and ISO SQL/MM Part 3 will be used, i.e., 2D type + 2000 for M and  2D type + 3000 for ZM. (Also types such as Tin and !PolyhedralSurface types can be added for completeness, even if unimplemented currently)
+New OGRwkbGeometryType values are needed. SFSQL 1.2 and ISO SQL/MM Part 3 will be used, i.e., 2D type + 2000 for M and  2D type + 3000 for ZM. (Also types such as Tin and !PolyhedralSurface types can be added for completeness, even if unimplemented currently)
+
+On a more general note, there could be a path to using a clean set of values and have legacy support as an exception. I'm proposing to define aliases for legacy *25D values to have a uniform set of values. Are there any problems with that?
+
+Abstract types are defined and not part of the enum.
 
 {{{
@@ -67 +71 @@
 ...
 
-// define new abstract types (why? what's the difference to the enum values? - they do not need to be handled in switches)
+// define new abstract types (why? what's the difference to the enum values? - at least they do not need to be handled in switches)
 #define wkbCurveZ           ((OGRwkbGeometryType)1013)      /**< ISO SQL/MM Part 3. GDAL &gt;= 2.1 */
 #define wkbSurfaceZ         ((OGRwkbGeometryType)1014)      /**< ISO SQL/MM Part 3. GDAL &gt;= 2.1 */
@@ -86 +90 @@
 }}}
 
-Currently hacks such as nCoordDimension == -2 are used to denote empty geometries. This implies many changes to drivers etc. which get or set nCoordinateDimension.
-
-!IsEmpty = !(flags & OGR_G_NOT_EMPTY), Is3D = flags & OGR_G_3D, !IsMeasured = flags & OGR_G_MEASURED.
-
-The !IsEmpty method is needed only in the base class but the emptiness needs to be managed in all classes through the flags.
-
-Keep (with original semantics, i.e., coordinate dimension is 2 or 3), but deprecate. In documentation it says that this may return zero for empty points while in ogrpoint.cpp it says that negative nCoordDimension values are used for empty points and getCoordinateDimension of point returns absolute value of nCoordDimension - thus not zero.
-{{{
-getCoordinateDimension();
-setCoordinateDimension();
-}}}
+Currently a hack to set nCoordDimension negative is used to denote an empty point. This implies many changes to drivers etc. which get or set nCoordinateDimension.
+
+The tests are
+
+{{{
+!IsEmpty = !(flags & OGR_G_NOT_EMPTY)
+Is3D = flags & OGR_G_3D
+!IsMeasured = flags & OGR_G_MEASURED
+}}}
+
+The setters and getters are implemented with |= and &=.
+
+The !IsEmpty method is needed only in the base class but the emptiness needs to be managed in all classes. It needs to be decided but when any of these flags is set, the corresponding data becomes invalid and may be discarded.
+
+Keep the following methods with original semantics, i.e., coordinate dimension is 2 or 3, but deprecate. There is some discrepancy in documentation. Their documentation says that they may return zero for empty points while in ogrpoint.cpp it says that negative nCoordDimension values are used for empty points and the getCoordinateDimension method of point returns absolute value of nCoordDimension - thus not zero.
+{{{
+int getCoordinateDimension();
+void setCoordinateDimension(int nDimension);
+void flattenTo2D()
+}}}
+
+It is proposed to possibly add a new method to replace getCoordinateDimension. set3D and setMeasured would replace setCoordinateDimension and flattenTo2D. See below.
 
 class OGRGeometry:
 {{{
 //Possibly add methods (SF Common Architecture):
-int Dimension(); // -1 for empty geometries, 0 for points, 1 for curves, 2 for surfaces, max of components for collections
+int Dimension(); // -1 for empty geometries (to denote undefined), 0 for points, 1 for curves, 2 for surfaces, max of components for collections
+char *GeometryType(); // calls OGRToOGCGeomType (which needs to be enhanced)
+
+//Add methods (SF Common Architecture) see above for implementation:
 int CoordinateDimension(); // 2 if not 3D and not measured, 3 if 3D or measured, 4 if 3D and measured
-int SpatialDimension(); // ?? 
-char *GeometryType(); // calls OGRToOGCGeomType (which needs to be enhanced)
-
-//Add methods (SF Common Architecture):
 OGRBoolean Is3D();
 OGRBoolean IsMeasured();
 
-//Add methods (non-standard, may cause internal changes, e.g., allocate memory for Z or M values):
+//Add methods (non-standard, may cause internal changes, e.g., allocate memory for Z or M values; note the use of one method instead of second unset* method):
 virtual void set3D(OGRBoolean bIs3D);
 virtual void setMeasured(OGRBoolean bIsMeasured);
@@ -121 +135 @@
 int !CoordinateDimension() should have the new semantics. The method name  in simple features documents actually is without prefix get.
 
-Whether set3D and setMeasured should affect the children geometries in a collection is an issue. Currently doc for setCoordinateDimension says "Setting
-the dimension of a geometry collection will not necessarily affect the children geometries.", which is not very clear.
-[ Note from E. Rouault --> the comment was wrong and has been fixed in r33184. I strongly believe that set3D and setMeasured should affect all sub-geometries, otherwise inconsistant WKB / WKT can be produced, leading to issues such as #6332 ]
+Whether set3D and setMeasured should affect the children geometries in a collection is an issue. Currently doc for setCoordinateDimension says "Setting the dimension of a geometry collection will affect the children geometries.", thus we have already committed to maintaining dimensions of children in collections. It is proposed that set3D and setMeasured either add or strip Z or M values to or from the geometry (including possible children).
 
 Add property double m to class OGRPoint. Add constructor, getters, and setters for it.
 
-Add property double *padfM to class OGRSimpleCurve. Add constructor, getters, and setters for it. The getters and setters can take advantage of the flags to determine whether Z or M is to be set in some of them. For backwards compatibility Z is preferred.
+Add property double *padfM to class OGRSimpleCurve. Add constructor, getters, and setters for it. The getters and setters can take advantage of the flags to determine whether Z or M is to be set in some of them - this is needed for prototypes like set(double, double, double). For backwards compatibility Z is preferred.
 
 Override methods set3D and setMeasured in those classes where setCoordinateDimension is overridden.
@@ -189 +201 @@
 }}}
 
+=== GEOS, filters, and other issues ===
+
+When a geometry with measures is sent to GEOS or used as a filter the M coordinate is ignored.
+
+LocateAlong and LocateBetween are the only standard methods, which use M but there could be others, which for example get the extent of M. Such are not intended to be added now but they can be added later.
 
 == SWIG bindings (Python / Java / C# / Perl) changes ==
@@ -198 +215 @@
 Drivers that are probably affected by the C++ changes are at least (these use the !CoordinateDimension API) pg, mssqlspatial, sqlite, db2, mysql, gml, pgdump, geojson, libkml, gpkg, wasp, gpx, filegdb, vfk, bna, dxf.
 
+The now deprecated !CoordinateDimension API is proposed to be replaced with calls to *3D and *Measured.
+
+Once the support for M coordinates is in place the driver will advertise the support.
+
+Within the work of this RFC the support is built into shape and pg. Support for other drivers are left for further work.
 
 == Utilities ==