MapGuide RFC 16 - Elevation and Extrusion Support for KML

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	(Date/Time submitted)
Last Modified	Chris ClaydonTimestamp
Author	Chris Claydon
RFC Status	draft
Implementation Status	pending
Proposed Milestone	1.2
Assigned PSC guide(s)
Voting History	(vote date)
+1
+0
-0
-1

Overview

The purpose of this RFC is to allow MapGuide users to configure elevation and extrusion parameters in a layer definition, and to use those settings to extrude features vertically in the KML generated for consumption by Google Earth. This provides a highly compelling way to visualize spatial data that contains a vertical component.

Motivation

MapGuide currently supports 2D representation of spatial data. However, many spatial data sets contain height information for the features they contain, giving the potential for 2.5D representation. This RFC describes how the MapGuide Layer Definition schema can be extended to specify expressions to be used to calculate a base elevation and extrusion size. Support for 2.5D would initially be implemented by the KML service, allowing visualization of solid objects in Google Earth, though it could be extended to other viewers at a later date. An example of the potential output is shown below:

Proposed Solution

The proposed solution contains modifications to: the Layer Definition XML schema, the MDF Model, the MDF Parser, and the Stylization project.

Layer Definition Schema Modifications

The layer definition schema contains numerous <!ExtendedData1> elements that allow the schema to be extended without breaking forward or backward compatibility. The changes proposed in this RFC would initially be added into one of these elements, and would eventually be moved to the main part of the schema whenever the next schema version update is carried out. See MapGuide RFC 10 for more details.

The affected section of the original schema looks like this:

  <xs:complexType name="VectorScaleRangeType">
    <xs:sequence>
      <xs:element name="MinScale" type="xs:double" minOccurs="0">...
      <xs:element name="MaxScale" type="xs:double" minOccurs="0">...
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="AreaTypeStyle" type="AreaTypeStyleType">...
        <xs:element name="LineTypeStyle" type="LineTypeStyleType">...
        <xs:element name="PointTypeStyle" type="PointTypeStyleType">...
      </xs:choice>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>

With the proposed changes, it would look like this:

  <xs:complexType name="VectorScaleRangeType">
    <xs:sequence>
      <xs:element name="MinScale" type="xs:double" minOccurs="0">...
      <xs:element name="MaxScale" type="xs:double" minOccurs="0">...
      <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="AreaTypeStyle" type="AreaTypeStyleType">...
        <xs:element name="LineTypeStyle" type="LineTypeStyleType">...
        <xs:element name="PointTypeStyle" type="PointTypeStyleType">...
      </xs:choice>
      <xs:element name="ExtendedData1" minOccurs="0" >
        <xs:complexType>
          <xs:sequence>
            <xs:element name="ElevationSettings" type="ElevationSettingsType" minOccurs="0" />
            <xs:element name="ExtendedData2" type="ExtendedDataType" minOccurs="0" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ElevationSettingsType">
    <xs:sequence>
      <xs:element name="ZOffset" type="xs:string" minOccurs="0" />
      <xs:element name="ZExtrusion" type="xs:string" minOccurs="0" />
      <xs:element name="ZOffsetType" type="ElevationTypeType" minOccurs="0" />
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="ElevationTypeType">
    <xs:annotation>
      <xs:documentation>The possible interpretations of a ZOffset value.</xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:string">
      <xs:enumeration value="RelativeToGround"/>
      <xs:enumeration value="Absolute"/>
    </xs:restriction>
  </xs:simpleType>

Descriptions of the key parameters are given below:

ZOffset	An expression that evaluates to the height of the base of the feature in meters
ZExtrusion	An expression that evaluates to the desired vertical extrusion (in meters) to be applied to the feature
ZOffsetType	A string value, either "RelativeToGround" or "Absolute", that indicates how to interpret the ZOffset value

Additional ExtendedData elements have been added to allow for future extensions to this part of the schema.

MDF Model and Parser Modifications

The MDF Model would require the addition of two new classes: ElevationSettings and !VectorScaleRangeExtendedData1, corresponding to the <ElevationSettings> and custom <!ExtendedData1> elements respectively. Similarly, the MDF Parser would require two new classes: IOElevationSettings and IOVectorScaleRangeExtendedData1.

The parser classes would be responsible for reading and writing the elevation settings to and from XML. The model classes would be used to store and access those settings. The methods implemented by each class would be very simple get/set or read/write functions.

Stylization Modifications

A few changes would be required to the internal stylization interfaces in order to pass the elevation settings through the framework to the Stylize() methods of the affected GeometryAdapters. Inside these methods, the offset and extrusion expressions would be evaluated for the current feature, and the resulting floating point values would be passed as additional parameters into the Renderer::StartFeature() command. The method signature chages are as follows:

GeometryAdapter::Stylize() would be modified from this:

    virtual void Stylize(Renderer*                      /*renderer*/,
                         RS_FeatureReader*              /*features*/,
                         RS_FilterExecutor*             /*exec*/,
                         LineBuffer*                    /*lb*/,
                         MdfModel::FeatureTypeStyle*    /*style*/,
                         const MdfModel::MdfString*     /*tooltip = NULL*/,
                         const MdfModel::MdfString*     /*url = NULL*/)                         

to this:

    virtual void Stylize(Renderer*                      /*renderer*/,
                         RS_FeatureReader*              /*features*/,
                         RS_FilterExecutor*             /*exec*/,
                         LineBuffer*                    /*lb*/,
                         MdfModel::FeatureTypeStyle*    /*style*/,
                         const MdfModel::MdfString*     /*tooltip = NULL*/,
                         const MdfModel::MdfString*     /*url = NULL*/,
                         RS_ElevationSettings*          /*elevSettings = NULL*/)

where RS_ElevationSettings is a simple struct-like class that contains the elevation settings.

Renderer::StartFeature() would be modified from this:

    virtual void StartFeature (RS_FeatureReader* feature,
                               const RS_String*  tooltip = NULL,
                               const RS_String*  url = NULL, 
                               const RS_String* theme = NULL) = 0;

to this:

    virtual void StartFeature (RS_FeatureReader* feature,
                               const RS_String*  tooltip = NULL,
                               const RS_String*  url = NULL, 
                               const RS_String* theme = NULL,
                               double zOffset = 0,
                               double zExtrusion = 0,
                               RS_ElevationType zOffsetType = RS_ElevationType_RelativeToGround) = 0;

All concrete classes that inherit from GeometryAdapter would need to be updated to use the new Stylize() method signature.

All concrete classes that implement the Renderer interface would need to be updated to reflect the changes, though only KmlRenderer would currently make use of the new parameters.

KmlRenderer Modifications

The KML Service generates KML using the KmlRenderer class - a concrete implementation of the Renderer interface. This class would be updated to set the Z coordinate of the generated geometries to be equal to (zOffset + zExtrusion). Also, if zExtrusion > 0, we would write out the KML element <extrude>1</extrude> to indicate that the features should be extruded down to the ground. If zOffset > 0, we will stil extrude the features down to the ground level, since Google Earth does not currently provide a means for rendering floating extruded objects.

Implications

This RFC does not describe any modifications to the GUI tools used to create layer definitions. The elevation settings would need to be configured by manual modification of the layer definition XML files.

Test Plan

Unit tests should include KML generation for layers that contain elevation settings

Funding/Resources

Autodesk to provide resources / funding.