Changes between Initial Version and Version 1 of MapGuideRfc153

Timestamp:

Nov 18, 2015, 7:05:22 AM (8 years ago)

Author:

jng

Comment:

--

MapGuideRfc153

@@ +1 @@
+
+= !MapGuide RFC 153 - Geometry simplification APIs =
+
+This page contains a change request (RFC) for the !MapGuide Open Source project.
+More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.
+
+== Status ==
+
+||RFC Template Version||(1.0)||
+||Submission Date||19 Nov 2015||
+||Last Modified||19 Nov 2015||
+||Author||Jackie Ng||
+||RFC Status||draft||
+||Implementation Status||sandbox experimental||
+||Proposed Milestone||3.1||
+||Assigned PSC guide(s)||(when determined)||
+||'''Voting History'''||(vote date)||
+||+1||||
+||+0||||
+||-0||||
+||-1||||
+||no vote|| ||
+
+== Overview ==
+
+This RFC proposes to add geometry simplfication APIs to MapGuide
+
+== Motivation ==
+
+MapGuide's geometry APIs are wrappers around equivalent APIs in GEOS
+
+One set of APIs in GEOS that is not exposed in MapGuide's geometry APIs is geometry simplification
+
+There is value in having such functionality available in the MapGuide API (eg. A MapGuide application that wants to return geometry data to clients at reduced fidelity)
+
+== Proposed Solution ==
+
+We'll add a new MgGeometrySimplifier class
+
+{{{
+/// \defgroup MgAgfReaderWriter MgAgfReaderWriter
+/// \ingroup Geometry_Module_classes
+/// \{
+
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/// \brief
+/// The MgGeometrySimplifier class provides the ability to simplify MgGeometry instances.
+///
+/// <!-- Example (PHP) -->
+/// \htmlinclude PHPExampleTop.html
+/// \code
+/// $wktRw = new MgWktReaderWriter();
+/// $geom = $wktRw->Read("LINESTRING (0 5, 1 5, 2 5, 5 5)");
+/// $simp = new MgGeometrySimplifier();
+/// $simplified = $simp->Simplify($geom, 10.0, MgGeometrySimplificationAlgorithmType::DouglasPeucker);
+/// \endcode
+/// \htmlinclude ExampleBottom.html
+///
+/// <!-- Example (C#) -->
+/// \htmlinclude CSharpExampleTop.html
+/// \code
+/// using OSGeo.MapGuide;
+/// ...
+/// MgWktReaderWriter wktRw = new MgWktReaderWriter();
+/// MgGeometry geom = wktRw.Read("LINESTRING (0 5, 1 5, 2 5, 5 5)");
+/// MgGeometrySimplifier simp = new MgGeometrySimplifier();
+/// MgGeometry simplified = simp.Simplify(geom, 10.0, MgGeometrySimplificationAlgorithmType.DouglasPeucker);
+/// \endcode
+/// \htmlinclude ExampleBottom.html
+///
+/// <!-- Example (Java) -->
+/// \htmlinclude JavaExampleTop.html
+/// \code
+/// import org.osgeo.mapguide;
+/// ...
+/// MgWktReaderWriter wktRw = new MgWktReaderWriter();
+/// MgGeometry geom = wktRw.Read("LINESTRING (0 5, 1 5, 2 5, 5 5)");
+/// MgGeometrySimplifier simp = new MgGeometrySimplifier();
+/// MgGeometry simplified = simp.Simplify(geom, 10.0, MgGeometrySimplificationAlgorithmType.DouglasPeucker);
+/// \endcode
+/// \htmlinclude ExampleBottom.html
+///
+class MG_GEOMETRY_API MgGeometrySimplifier : public MgGuardDisposable
+{
+    DECLARE_CLASSNAME(MgGeometrySimplifier)
+
+PUBLISHED_API:
+    ///////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Creates an MgGeometrySimplifier object
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// MgGeometrySimplifier();
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// MgGeometrySimplifier();
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// MgGeometrySimplifier();
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    MgGeometrySimplifier();
+
+    ///////////////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Simplifies the given geometry using the specified algorithm and tolerance
+    ///
+    /// <!-- Syntax in .Net, Java, and PHP -->
+    /// \htmlinclude DotNetSyntaxTop.html
+    /// virtual MgGeometry Simplify(MgGeometry geom, double tolerance, int algorithm);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude JavaSyntaxTop.html
+    /// virtual MgGeometry Simplify(MgGeometry geom, double tolerance, int algorithm);
+    /// \htmlinclude SyntaxBottom.html
+    /// \htmlinclude PHPSyntaxTop.html
+    /// virtual MgGeometry Simplify(MgGeometry geom, double tolerance, int algorithm);
+    /// \htmlinclude SyntaxBottom.html
+    ///
+    /// \param geom (MgGeometry)
+    /// The geometry instance to be simplified
+    ///
+    /// \param tolerance (double)
+    /// The tolerance factor to simplify by
+    ///
+    /// \param algorithm (int)
+    /// The simplification algorithm to use. Use any value from MgGeometrySimplificationAlgorithmType
+    ///
+    /// \return
+    /// A simplified MgGeometry instance or null if simpification results in an empty geometry
+    ///
+    MgGeometry* Simplify(MgGeometry* geom, double tolerance, INT32 algorithm);
+
+INTERNAL_API:
+
+    //////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Get the unique identifier for the class
+    ///
+    /// \return
+    /// Class Identifider.
+    ///
+    virtual INT32 GetClassId();
+
+protected:
+
+    //////////////////////////////////////////////
+    /// \brief
+    /// Dispose this object.
+    ///
+    virtual void Dispose();
+
+CLASS_ID:
+    static const INT32 m_cls_id = Geometry_GeometrySimplifier;
+};
+/// \}
+}}}
+
+The {{{algorithm}}} parameter can be any value of {{{MgGeometrySimplificationAlgorithmType}}}
+
+{{{
+////////////////////////////////////////////////////////////
+/// \brief
+/// MgGeometrySimplificationAlgorithmType defines constants indicating
+/// the various simplification algorithms available for simplifying
+/// geometry instances
+///
+class MgGeometrySimplificationAlgorithmType
+{
+PUBLISHED_API:
+    /////////////////////////////////////////////////////////////////
+    /// \brief
+    /// Specifies that the Douglas-Peucker algorithm be used for simplification.
+    ///
+    static const INT32 DouglasPeucker = 0;
+
+    ///////////////////////////////////////////////////////
+    /// \brief
+    /// Specifies that the Topology Preserving algorithm be used for simplification
+    ///
+    static const INT32 TopologyPreserving = 1;
+};
+}}}
+
+Implementation-wise, depending on the choice of algorithm the MgGeometry is converted to its GEOS counterpart (like every other MapGuide geometry API) and forwarded to the matching GEOS simplifier ({{{geos::simplify::DouglasPeuckerSimplifier}}} or {{{geos::simplify::TopologyPreservingSimplifier}}})
+
+The simplified result is then converted back to its MgGeometry form.
+
+== Implications ==
+
+This is a new API addition
+
+== Test Plan ==
+
+Exercise the MgGeometrySimplifier against the same set of sample geometries as the geos simplifier tests.
+
+== Funding / Resources ==
+
+Community