= !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||7 Apr 2017||
||Author||Jackie Ng||
||RFC Status||Implemented||
||Implementation Status||Completed||
||Proposed Milestone||4.0||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||Jackie,Gordon||
||+0||Haris||
||-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 (or representations of it) to client applications at reduced fidelity)

== Proposed Solution ==

We'll add a new MgGeometrySimplifier class

{{{
/// \defgroup MgGeometrySimplifier MgGeometrySimplifier
/// \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 simplification failed or resulted 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