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 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 (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