Changes between Version 1 and Version 2 of MapGuideRfc17


Ignore:
Timestamp:
02/23/07 10:47:35 (18 years ago)
Author:
chrisclaydon
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideRfc17

    v1 v2  
    1 TBD
     1= !MapGuide RFC 17 - Map Space Line Widths =
     2
     3This page contains a change request (RFC) for the !MapGuide Open Source project. 
     4More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.
     5
     6
     7== Status ==
     8 
     9||RFC Template Version||(1.0)||
     10||Submission Date||(Date/Time submitted)||
     11||Last Modified||Chris Claydon[[Timestamp]]||
     12||Author||Chris Claydon||
     13||RFC Status||draft||
     14||Implementation Status||pending||
     15||Proposed Milestone||1.2||
     16||Assigned PSC guide(s)||||
     17||'''Voting History'''||(vote date)||
     18||+1||||
     19||+0||||
     20||-0||||
     21||-1||||
     22 
     23== Overview ==
     24
     25The purpose of this RFC is to allow line widths in !MapGuide to be specified using Map Space as an alternative to Device Space. Map Space units refer to "real-world" dimensions, and thus the lines become wider or narrower as the user zooms in or out on the map.
     26
     27== Motivation ==
     28
     29There are use cases where it is desirable for a line on a map to be rendered with a thickness that corresponds directly to the real size of the feature it represents. For example, if the polyline representing a pipeline were rendered in a way that accurately represented its real size, it would allow the user to see how it was positioned in relation to adjacent features such as trees or buildings. It is also often desirable, from a cartographic standpoint, to have line widths vary as you zoom in or out on the map. This allows features such as roads to be rendered with a more realistic size relative to other features on the map. !MapGuide currently supports Map Space in the specification of symbol and label sizes, and this RFC proposes extending that support to polylines and the lines that define polygon boundaries.
     30
     31== Proposed Solution ==
     32
     33The proposed solution contains modifications to: the Layer Definition XML schema, the MDF Model, the MDF Parser, and the Stylization project.
     34
     35=== Layer Definition Schema Modifications ===
     36
     37The 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 [http://wiki.osgeo.org/index.php/MapGuide_RFC_10_-_Make_Schemas_More_Amenable_to_Interim_Enhancements MapGuide RFC 10] for more details.
     38
     39The affected section of the original schema looks like this:
     40
     41{{{
     42  <xs:complexType name="VectorScaleRangeType">
     43    <xs:sequence>
     44      <xs:element name="MinScale" type="xs:double" minOccurs="0">...
     45      <xs:element name="MaxScale" type="xs:double" minOccurs="0">...
     46      <xs:choice minOccurs="0" maxOccurs="unbounded">
     47        <xs:element name="AreaTypeStyle" type="AreaTypeStyleType">...
     48        <xs:element name="LineTypeStyle" type="LineTypeStyleType">...
     49        <xs:element name="PointTypeStyle" type="PointTypeStyleType">...
     50      </xs:choice>
     51      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
     52    </xs:sequence>
     53  </xs:complexType>
     54}}}
     55
     56With the proposed changes, it would look like this:
     57
     58{{{
     59  <xs:complexType name="VectorScaleRangeType">
     60    <xs:sequence>
     61      <xs:element name="MinScale" type="xs:double" minOccurs="0">...
     62      <xs:element name="MaxScale" type="xs:double" minOccurs="0">...
     63      <xs:choice minOccurs="0" maxOccurs="unbounded">
     64        <xs:element name="AreaTypeStyle" type="AreaTypeStyleType">...
     65        <xs:element name="LineTypeStyle" type="LineTypeStyleType">...
     66        <xs:element name="PointTypeStyle" type="PointTypeStyleType">...
     67      </xs:choice>
     68      <xs:element name="ExtendedData1" minOccurs="0" >
     69        <xs:complexType>
     70          <xs:sequence>
     71            <xs:element name="ElevationSettings" type="ElevationSettingsType" minOccurs="0" />
     72            <xs:element name="ExtendedData2" type="ExtendedDataType" minOccurs="0" />
     73          </xs:sequence>
     74        </xs:complexType>
     75      </xs:element>
     76    </xs:sequence>
     77  </xs:complexType>
     78  <xs:complexType name="ElevationSettingsType">
     79    <xs:sequence>
     80      <xs:element name="ZOffset" type="xs:string" minOccurs="0" />
     81      <xs:element name="ZExtrusion" type="xs:string" minOccurs="0" />
     82      <xs:element name="ZOffsetType" type="ElevationTypeType" minOccurs="0" />
     83      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
     84    </xs:sequence>
     85  </xs:complexType>
     86  <xs:simpleType name="ElevationTypeType">
     87    <xs:annotation>
     88      <xs:documentation>The possible interpretations of a ZOffset value.</xs:documentation>
     89    </xs:annotation>
     90    <xs:restriction base="xs:string">
     91      <xs:enumeration value="RelativeToGround"/>
     92      <xs:enumeration value="Absolute"/>
     93    </xs:restriction>
     94  </xs:simpleType>
     95}}}
     96
     97Descriptions of the key parameters are given below:
     98
     99||ZOffset||An expression that evaluates to the height of the base of the feature in meters||
     100||ZExtrusion||An expression that evaluates to the desired vertical extrusion (in meters) to be applied to the feature||
     101||ZOffsetType||A string value, either "!RelativeToGround" or "Absolute", that indicates how to interpret the ZOffset value||
     102
     103Additional !ExtendedData elements have been added to allow for future extensions to this part of the schema.
     104
     105==== Example ===
     106
     107The following XML snippet is taken from the layer definition used to generate the screenshot above:
     108{{{
     109<VectorLayerDefinition>
     110  ...
     111  ... 
     112  <VectorScaleRange>
     113    ...
     114    ...
     115    <ExtendedData1>
     116      <ElevationSettings>
     117        <ZOffset>0</ZOffset>
     118        <ZExtrusion>HEIGHT_AGL</ZExtrusion>
     119        <ZOffsetType>RelativeToGround</ZOffsetType>
     120      </ElevationSettings>
     121    </ExtendedData1> 
     122  </VectorScaleRange>
     123</VectorLayerDefinition>
     124</LayerDefinition>
     125}}}
     126
     127=== MDF Model and Parser Modifications ===
     128
     129The 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'''.
     130
     131The 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.
     132
     133=== Stylization Modifications ===
     134
     135The 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 <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.
     136
     137== Implications ==
     138
     139This 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]]
     140There are no changes to the existing public API.
     141
     142== Test Plan ==
     143
     144Unit tests should include KML generation for layers that contain elevation settings
     145
     146== Funding/Resources ==
     147
     148Autodesk to provide resources / funding.