Changes between Version 4 and Version 5 of MapGuideRfc161


Ignore:
Timestamp:
Jun 25, 2017, 7:23:41 AM (7 years ago)
Author:
jng
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideRfc161

    v4 v5  
    5252|| COORDINATESYSTEM || string || Yes || The coordinate system (CS-Map code) of the input geometry ||
    5353|| TRANSFORMTO || string || Optional || The coordinate system (CS-Map code) to transform the buffer geometry into. If not specified, the buffer geometry will be in the input coordinate system  ||
     54|| PRECISION || number || Optional || The decimal precision to use when outputting as GeoJSON. If not specified, it will default to 7 decimal places. Has no effect if output format is not GeoJSON ||
    5455
    5556=== Simplify ===
    … …  
    6970|| COORDINATESYSTEM || string || Optional || The coordinate system (CS-Map code) of the input geometry. Only required in combination with `TRANSFORMTO` if you intend to transform the simplified geometry ||
    7071|| TRANSFORMTO || string || Optional || The coordinate system (CS-Map code) to transform the simplified geometry into. Only required in combination with `COORDINATESYSTEM ` if you intend to transform the simplified geometry  ||
     72|| PRECISION || number || Optional || The decimal precision to use when outputting as GeoJSON. If not specified, it will default to 7 decimal places. Has no effect if output format is not GeoJSON ||
    7173
    7274=== Binary Operation ===
    … …  
    9193|| COORDINATESYSTEM || string || Optional || The coordinate system (CS-Map code) of the input geometries. Only required in combination with `TRANSFORMTO` if you intend to transform the geometry result ||
    9294|| TRANSFORMTO || string || Optional || The coordinate system (CS-Map code) to transform the simplified geometry into. Only required in combination with `COORDINATESYSTEM ` if you intend to transform the geometry result ||
     95|| PRECISION || number || Optional || The decimal precision to use when outputting as GeoJSON. If not specified, it will default to 7 decimal places. Has no effect if output format is not GeoJSON ||
    9396
    9497All operators are invoked in the form of {{{GEOMETRYA OPERATOR GEOMETRYB}}}. Where ordering of input geometries matters (the operator is not commutative), refer to this rule.
    … …  
    131134|| COORDINATESYSTEM || string || Optional || The coordinate system (CS-Map code) of the input geometries. Only required in combination with `TRANSFORMTO` if you intend to transform the geometry result ||
    132135|| TRANSFORMTO || string || Optional || The coordinate system (CS-Map code) to transform the simplified geometry into. Only required in combination with `COORDINATESYSTEM ` if you intend to transform the geometry result ||
     136|| PRECISION || number || Optional || The decimal precision to use when outputting as GeoJSON. If not specified, it will default to 7 decimal places. Has no effect if output format is not GeoJSON ||
     137
     138=== Boundary ===
     139
     140Returns the geometry that represents the input geometry's boundary
     141
     142|| '''Name''' || '''Value'''  || '''Required''' || '''Description''' ||
     143|| OPERATION || GEO.BOUNDARY || Yes || Operation to execute ||
     144|| VERSION || 3.3.0 || Yes || Operation version ||
     145|| CLIENTAGENT || text || Optional || Descriptive text for client ||
     146|| GEOMETRY || string || Yes || The Well-Known Text of the input geometry ||
     147|| FORMAT || WKT/GEOJSON || Yes || Output the operation result as WKT or GeoJSON ||
     148|| COORDINATESYSTEM || string || Optional || The coordinate system (CS-Map code) of the input geometries. Only required in combination with `TRANSFORMTO` if you intend to transform the geometry result ||
     149|| TRANSFORMTO || string || Optional || The coordinate system (CS-Map code) to transform the simplified geometry into. Only required in combination with `COORDINATESYSTEM ` if you intend to transform the geometry result ||
     150|| PRECISION || number || Optional || The decimal precision to use when outputting as GeoJSON. If not specified, it will default to 7 decimal places. Has no effect if output format is not GeoJSON ||
     151
     152=== Tessellate ===
     153
     154Returns the geometry that is a tessellated form of the input geometry. This operation is provided for approximating curve-based geometries to non-curve equivalents and has no effect if the input geometry is not curve-based (the operation will return the input geometry)
     155
     156|| '''Name''' || '''Value'''  || '''Required''' || '''Description''' ||
     157|| OPERATION || GEO.TESSELLATE || Yes || Operation to execute ||
     158|| VERSION || 3.3.0 || Yes || Operation version ||
     159|| CLIENTAGENT || text || Optional || Descriptive text for client ||
     160|| GEOMETRY || string || Yes || The Well-Known Text of the input geometry ||
     161|| FORMAT || WKT/GEOJSON || Yes || Output the operation result as WKT or GeoJSON ||
     162|| COORDINATESYSTEM || string || Optional || The coordinate system (CS-Map code) of the input geometries. Only required in combination with `TRANSFORMTO` if you intend to transform the geometry result ||
     163|| TRANSFORMTO || string || Optional || The coordinate system (CS-Map code) to transform the simplified geometry into. Only required in combination with `COORDINATESYSTEM ` if you intend to transform the geometry result ||
     164|| PRECISION || number || Optional || The decimal precision to use when outputting as GeoJSON. If not specified, it will default to 7 decimal places. Has no effect if output format is not GeoJSON ||
    133165
    134166=== Distance ===
    … …  
    166198}}}
    167199
     200=== Geometry Info ===
     201
     202Returns information about the input geometry
     203
     204|| '''Name''' || '''Value'''  || '''Required''' || '''Description''' ||
     205|| OPERATION || GEO.DISTANCE || Yes || Operation to execute ||
     206|| VERSION || 3.3.0 || Yes || Operation version ||
     207|| CLIENTAGENT || text || Optional || Descriptive text for client ||
     208|| GEOMETRY || string || Yes || The Well-Known Text of the input geometry ||
     209|| FORMAT || string || Yes || {{{text/xml}}} for XML, {{{application/json}}} for JSON ||
     210|| CLEAN || 1/0 || Optional || If requested format is {{{application/json}}}, returns a clean JSON structure per [wiki:MapGuideRfc158] ||
     211
     212The result adheres to the new {{{GeometryInfo-3.3.0.xsd}}} XML schema
     213
     214{{{
     215<?xml version="1.0" encoding="UTF-8"?>
     216<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
     217  <xs:element name="GeometryInfo">
     218    <xs:annotation>
     219      <xs:documentation>Geometry Information</xs:documentation>
     220    </xs:annotation>
     221    <xs:complexType>
     222      <xs:sequence>
     223        <xs:element name="Area" type="xs:double" />
     224        <xs:element name="Dimension" type="xs:int" />
     225        <xs:element name="Length" type="xs:double" />
     226        <xs:element name="IsClosed" type="xs:boolean" />
     227        <xs:element name="IsEmpty" type="xs:boolean" />
     228        <xs:element name="IsSimple" type="xs:boolean" />
     229        <xs:element name="IsValid" type="xs:boolean" />
     230        <xs:element name="Envelope" type="Envelope" />
     231        <xs:element name="Centroid" type="Coordinate" />
     232      </xs:sequence>
     233    </xs:complexType>
     234  </xs:element>
     235  <xs:complexType name="Coordinate">
     236    <xs:annotation>
     237      <xs:documentation>Represents a bounding box</xs:documentation>
     238    </xs:annotation>
     239    <xs:sequence>
     240      <xs:element name="X" type="xs:double">
     241        <xs:annotation>
     242          <xs:documentation>x-coordinate</xs:documentation>
     243        </xs:annotation>
     244      </xs:element>
     245      <xs:element name="Y" type="xs:double">
     246        <xs:annotation>
     247          <xs:documentation>y-coordinate</xs:documentation>
     248        </xs:annotation>
     249      </xs:element>
     250    </xs:sequence>
     251  </xs:complexType>
     252  <xs:complexType name="Envelope">
     253    <xs:annotation>
     254      <xs:documentation>Represents a bounding box defined in terms of a lower left coordinate and an upper right coordinate</xs:documentation>
     255    </xs:annotation>
     256    <xs:sequence>
     257      <xs:element name="LowerLeft" type="Coordinate">
     258        <xs:annotation>
     259          <xs:documentation>Lower-left coordinate</xs:documentation>
     260        </xs:annotation>
     261      </xs:element>
     262      <xs:element name="UpperRight" type="Coordinate">
     263        <xs:annotation>
     264          <xs:documentation>Upper-right coordinate</xs:documentation>
     265        </xs:annotation>
     266      </xs:element>
     267    </xs:sequence>
     268  </xs:complexType>
     269</xs:schema>
     270}}}
     271
     272== GeoJSON improvements ==
     273
     274As GeoJSON is a key output format for a majority of these new operations, this RFC includes some improvements to the GeoJSON support introduced in [wiki:MapGuideRfc158]
     275
     276=== Configurable coordinate precision ===
     277
     278As implied by some of the new mapagent operations, the GeoJSON output support introduced in [wiki:MapGuideRfc158] has been enhanced with support for configurable coordinate precision.
     279
     280Before this RFC, GeoJSON coordinates were output verbatim from their source geometry counterparts. Generally speaking, coordinates beyond 7 decimal places in most coordinate systems are superfluous and adds unnecessary bloat to GeoJSON content when converting feature geometry.
     281
     282As a result, the {{{MgGeoJsonWriter}}} class has been extended to allow a custom decimal precision to be specified
     283
     284{{{
     285
     286class MG_PLATFORMBASE_API MgGeoJsonWriter : public MgGuardDisposable
     287{
     288PUBLISHED_API:
     289    ...
     290
     291    //////////////////////////////////////////////////////////////////
     292    /// \brief
     293    /// Sets the decimal precision to use when writing out coordinates. If you do not call this method, the default precision used is 7 decimal places
     294    ///
     295    /// <!-- Syntax in .Net, Java, and PHP -->
     296    /// \htmlinclude DotNetSyntaxTop.html
     297    /// void SetPrecision(int precision);
     298    /// \htmlinclude SyntaxBottom.html
     299    /// \htmlinclude JavaSyntaxTop.html
     300    /// void SetPrecision(int precision);
     301    /// \htmlinclude SyntaxBottom.html
     302    /// \htmlinclude PHPSyntaxTop.html
     303    /// void SetPrecision(int precision);
     304    /// \htmlinclude SyntaxBottom.html
     305    ///
     306    /// \param precision (int)
     307    /// The decimal precision to write out coordinates
     308    ///
     309    /// \return
     310    /// Returns the GeoJSON output as a string.
     311    ///
     312    void SetPrecision(INT32 precision);
     313
     314    //////////////////////////////////////////////////////////////////
     315    /// \brief
     316    /// Gets the decimal precision to use when writing out coordinates
     317    ///
     318    /// <!-- Syntax in .Net, Java, and PHP -->
     319    /// \htmlinclude DotNetSyntaxTop.html
     320    /// int GetPrecision();
     321    /// \htmlinclude SyntaxBottom.html
     322    /// \htmlinclude JavaSyntaxTop.html
     323    /// int GetPrecision();
     324    /// \htmlinclude SyntaxBottom.html
     325    /// \htmlinclude PHPSyntaxTop.html
     326    /// int GetPrecision();
     327    /// \htmlinclude SyntaxBottom.html
     328    ///
     329    /// \return
     330    /// Returns the current precision
     331    ///
     332    INT32 GetPrecision();
     333};
     334
     335}}}
     336
     337If not specified, 7 decimal places will be default when converting feature data to GeoJSON using {{{MgGeoJsonWriter}}}
     338
     339=== Auto-tessellation of curves ===
     340
     341The GeoJSON spec does not define curve geometries, as a result if one was converting a feature with curve-based geometry to GeoJSON, the {{{geometry}}} component is currently always going to be {{{null}}}
     342
     343For this RFC, curve geometries are automatically tessellated to their non-curve equivalents.
     344
    168345== MgGeometry enhancements ==
    169346
    170 In addition to mapagent enhancements, this RFC enhances the `MgGeometry` class with support for "prepared" geometries.
     347In addition to mapagent enhancements, this RFC enhances the `MgGeometry` API with extra capabilities.
     348
     349=== Tessellation ===
     350
     351The GeoJSON support has demonstrated the need to provide some means for any curve-based `MgGeometry` to return a tessellated version of itself so it can be used in cases where curve-based geometries are not supported (such as converting to GeoJSON).
     352
     353To support such cases, we'll introduce a new API to {{{MgGeometry}}} to support tessellation
     354
     355{{{
     356class MG_GEOMETRY_API MgGeometry : public MgGeometricEntity
     357{
     358PUBLISHED_API:
     359    ...
     360    ///////////////////////////////////////////////////////////////////////
     361    /// \brief
     362    /// Returns a tessellated version of this geometry. A tessellated version of this
     363    /// geometry will have all arc/curve geometry components approximated with line
     364    /// strings. Thus, this method is only applicable for curve geometries and has
     365    /// no effect on non-curve geometries.
     366    ///
     367    /// <!-- Syntax in .Net, Java, and PHP -->
     368    /// \htmlinclude DotNetSyntaxTop.html
     369    /// virtual MgGeometry Prepare();
     370    /// \htmlinclude SyntaxBottom.html
     371    /// \htmlinclude JavaSyntaxTop.html
     372    /// virtual MgGeometry Prepare();
     373    /// \htmlinclude SyntaxBottom.html
     374    /// \htmlinclude PHPSyntaxTop.html
     375    /// virtual MgGeometry Prepare();
     376    /// \htmlinclude SyntaxBottom.html
     377    ///
     378    /// \since 3.3
     379    ///
     380    /// \return
     381    /// A tesellated version of this geometry. If this geometry is not curve-based, the operation does nothing and this method returns itself.
     382    ///
     383    MgGeometry* Tessellate();
     384};
     385}}}
     386
     387Implementation-wise, this method merely delegates to the existing {{{MgSpatialUtility::TessellateCurve(MgGeometry*)}}} method already in the MgGeometry project.
     388
     389=== Prepared geometries ===
    171390
    172391Prepared geometries is a performance optimization that improves the performance of operations between a single target geometry and a batch of test geometries. By preparing the target geometry, various internal data structures of the prepared geometry can be pre-computed, which then allows subsequent geometric operations to be evaluated with maximum efficiency.
    … …  
    461680It is important to note that the use-case of `MgPreparedGeometry` is primarily for fast/repeated evaluation of spatial predicates. As such, `MgPreparedGeometry` does not follow the geometry class hierarchy like its `MgGeometry` counterpart. If one wants to know the actual geometric information about the `MgPreparedGeometry`, they should retain a reference to the original `MgGeometry` that they `Prepare()`'d from.
    462681
     682Also, this is not a substitute for equivalent spatial filtering criteria on a Feature Source if its provider capabilities allow for it. Data-store level evaluation of these spatial predicates will generally always be faster than doing it at the application level through this new API.
     683
    463684Implementation-wise, `MgPreparedGeometry` wraps the underlying `PreparedGeometry` class provided by GEOS. We use the pimpl pattern to avoid leaking out the `PreparedGeometry` dependency (and consequently any geos headers) in the public header of `MgPreparedGeometry`.
    464685