= !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 [wiki:MapGuideRfcs RFCs] page. == Status == ||RFC Template Version||(1.0)|| ||Submission Date||(Date/Time submitted)|| ||Last Modified||Chris Claydon[[Timestamp]]|| ||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: [[Image(KmlExtrusionScreenshot.jpg, align=center)]] == 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 affected section of the original schema looks like this: {{{ ... ... ... ... ... }}} With the proposed changes, it would look like this: {{{ ... ... ... ... ... The possible interpretations of a ZOffset value. }}} Descriptions of the key parameters are given below: ||ZOffset||An expression that evaluates to the height of the base of the feature in the units specified in the element|| ||ZExtrusion||An expression that evaluates to the desired vertical extrusion (in specified units) to be applied to the feature|| ||ZOffsetType||A string value, either "!RelativeToGround" or "Absolute", that indicates how to interpret the ZOffset value|| ||Unit||A string value corresponding to one of the values in the existing !LengthUnitType type|| Additional !ExtendedData elements have been added to allow for future extensions to this part of the schema. ==== Example === The following XML snippet is taken from the layer definition used to generate the screenshot above: {{{ ... ... ... ... 0 HEIGHT_AGL RelativeToGround Meters }}} === MDF Model and Parser Modifications === The MDF Model would require the addition of the new class: '''!ElevationSettings''', corresponding to the elements. Similarly, the MDF Parser would require the new class: '''IOElevationSettings'''. The parser class would be responsible for reading and writing the elevation settings to and from XML. The model class 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 === The Stylization project would be modified to make the necessary elevation settings available to the !KmlRenderer class that generates KML output for the KML Service. 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 1 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.[[BR]] There are no changes to the existing public API. == Test Plan == Unit tests should include KML generation for layers that contain elevation settings == Funding/Resources == Autodesk to provide resources / funding.