Changes between Version 2 and Version 3 of MapGuideRfc17


Ignore:
Timestamp:
02/26/07 09:03:25 (18 years ago)
Author:
chrisclaydon
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • MapGuideRfc17

    v2 v3  
    3535=== Layer Definition Schema Modifications ===
    3636
    37 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 [http://wiki.osgeo.org/index.php/MapGuide_RFC_10_-_Make_Schemas_More_Amenable_to_Interim_Enhancements MapGuide RFC 10] for more details.
     37The schema modifications could be made forward/backward compatible by adding them to the <!ExtendedData1> elements that already exist in the schema. See [wiki:MapGuideRfc10 MapGuide RFC 10] for details on extended data. However, it seems likely that [wiki:MapGuideRfc14 MapGuide RFC 14] will require a schema version update, in which case the modifications from this RFC (and [wiki:MapGuideRfc16 MapGuide RFC 16]) can be rolled into the same update. The schema changes described below assume we are not using extended data.
    3838
    39 The affected section of the original schema looks like this:
     39The element type that specifies the style of polylines and polygon edges in the layer definition schema is <StrokeType>. It would be modified from this:
    4040
    4141{{{
    42   <xs:complexType name="VectorScaleRangeType">
     42<xs:complexType name="StrokeType">
     43    <xs:annotation>
     44      <xs:documentation>Encapsulates the stylization of a line.
     45            </xs:documentation>
     46    </xs:annotation>
    4347    <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>
     48      <xs:element name="LineStyle" type="xs:string"/>
     49      <xs:element name="Thickness" type="xs:string"/>
     50      <xs:element name="Color" type="xs:string"/>
     51      <xs:element name="Unit" type="LengthUnitType">
     52        <xs:annotation>
     53          <xs:documentation>Unit of measurement that the thickness is specified in</xs:documentation>
     54        </xs:annotation>
     55      </xs:element>
    5156      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    5257    </xs:sequence>
    … …  
    5459}}}
    5560
    56 With the proposed changes, it would look like this:
     61to this:
    5762
    5863{{{
    59   <xs:complexType name="VectorScaleRangeType">
     64<xs:complexType name="StrokeType">
     65    <xs:annotation>
     66      <xs:documentation>Encapsulates the stylization of a line.
     67            </xs:documentation>
     68    </xs:annotation>
    6069    <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>
     70      <xs:element name="LineStyle" type="xs:string"/>
     71      <xs:element name="Thickness" type="xs:string"/>
     72      <xs:element name="Color" type="xs:string"/>
     73      <xs:element name="Unit" type="LengthUnitType">
     74        <xs:annotation>
     75          <xs:documentation>Unit of measurement that the thickness is specified in</xs:documentation>
     76        </xs:annotation>
    7577      </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" />
     78      <xs:element name="SizeContext" type="SizeContextType">
     79        <xs:annotation>
     80          <xs:documentation>Whether the sizes are with respect to the earth or the user's display device.</xs:documentation>
     81        </xs:annotation>
     82      </xs:element>
    8383      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    8484    </xs:sequence>
    8585  </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>
    9586}}}
    9687
    97 Descriptions 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 
    103 Additional !ExtendedData elements have been added to allow for future extensions to this part of the schema.
     88The SizeContextType type already exists in the layer definition schema, and is used to specify the size context for symbols and labels.
    10489
    10590==== Example ===
    10691
    107 The following XML snippet is taken from the layer definition used to generate the screenshot above:
     92The following XML snippet represents a polyline line style using the new schema:
    10893{{{
    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>
    12594}}}
    12695
    12796=== MDF Model and Parser Modifications ===
    12897
    129 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'''.
     98The MDF Model uses the '''Stroke''' class to store line style information. This class would require new methods to get and set the size context. These would be identical to the corresponding existing methods in the '''Symbol''' class that serve the same purpose.
    13099
    131 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.
     100The MDF Parser uses the '''IOStroke''' class to read and write the XML stroke definitions. It would be updated to handle reading and writing of the new SizeContext element.
    132101
    133102=== Stylization Modifications ===
    134103
    135 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 <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.
     104The Stylization project would make use of the new accessor method in the MdfModel::Stroke class to determine the required size context, and render any lines with the correct width. The logic to determine line width in pixels based on thickness, units, and size context already exists in the symbol stylization code.
    136105
    137106== Implications ==
    138107
    139 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]]
     108This RFC does not describe any modifications to the GUI tools used to create layer definitions. The line style size context settings would need to be configured by manual modification of the layer definition XML files, until these tools are updated. [[BR]]
    140109There are no changes to the existing public API.
    141110
    142111== Test Plan ==
    143112
    144 Unit tests should include KML generation for layers that contain elevation settings
     113Unit tests should include stylization of lines using map space widths.
    145114
    146115== Funding/Resources ==