= !MapGuide RFC 17 - Map Space Line Widths =

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 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.

== Motivation ==

There 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.

== 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 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.

The element type that specifies the style of polylines and polygon edges in the layer definition schema is <!StrokeType>. It would be modified from this:

{{{
<xs:complexType name="StrokeType">
    <xs:annotation>
      <xs:documentation>Encapsulates the stylization of a line.
            </xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="LineStyle" type="xs:string"/>
      <xs:element name="Thickness" type="xs:string"/>
      <xs:element name="Color" type="xs:string"/>
      <xs:element name="Unit" type="LengthUnitType">
        <xs:annotation>
          <xs:documentation>Unit of measurement that the thickness is specified in</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
}}}

to this:

{{{
<xs:complexType name="StrokeType">
    <xs:annotation>
      <xs:documentation>Encapsulates the stylization of a line.
            </xs:documentation>
    </xs:annotation>
    <xs:sequence>
      <xs:element name="LineStyle" type="xs:string"/>
      <xs:element name="Thickness" type="xs:string"/>
      <xs:element name="Color" type="xs:string"/>
      <xs:element name="Unit" type="LengthUnitType">
        <xs:annotation>
          <xs:documentation>Unit of measurement that the thickness is specified in</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="SizeContext" type="SizeContextType">
        <xs:annotation>
          <xs:documentation>Whether the sizes are with respect to the earth or the user's display device.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
}}}

The !SizeContextType type already exists in the layer definition schema, and is used to specify the size context for symbols and labels.

==== Example ===

The following XML snippet represents a polyline line style using the new schema:
{{{
<LineTypeStyle>
  <LineRule>
    ...    
    ...
    <LineSymbolization2D>
      <LineStyle>Solid</LineStyle>
      <Thickness>0.5</Thickness>
      <Color>FF808080</Color>
      <Unit>Inches</Unit>
      <SizeContext>MappingUnits</SizeContext>
    </LineSymbolization2D>
  </LineRule>
</LineTypeStyle>
}}}

=== MDF Model and Parser Modifications ===

The 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.

The 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.

=== Stylization Modifications ===

The 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.

== Implications ==

This 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]]
There are no changes to the existing public API. 

== Test Plan ==

Unit tests should include stylization of lines using map space widths.

== Funding/Resources ==

Autodesk to provide resources / funding.