= !MapGuide RFC 59 - Add TIN layer type in Layer Defination Schema =

This page contains an 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||Evan Yan [[Timestamp]]||
||Author||Evan Yan||
||RFC Status||draft||
||Implementation Status||under development||
||Proposed Milestone||(e.g. 1.1, 1.3, 2.1)||
||Assigned PSC guide(s)||(when determined)||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
||no vote|| ||

== Overview ==

The purpose of this RFC is to add a new schema in Layer Definition XML schema for TIN (Triangulated Irregular Networks). TIN layer has many characteristics that are different from Vector and Grid layers, it’s necessary to create a new layer type for TIN.

== Motivation ==
The existing Layer Definition XML schema does not contains a definition for TIN layer. So, currently we cannot show a real TIN surface. 
Adding TIN layer schema will make it easier to support TIN layer and there will be a real TIN surface. We can see points, edges and faces if we zoom into the surface. 

== Proposed Solution ==
The proposed solution contains modifications to: the Layer Definition XML schema, the FDO provider, and the Stylization project.

==Layer Definition Schema Modifications==
TinLayerDefinitionType element was added in Layer Definition XML schema. 
{{{
	<xs:annotation>
		<xs:documentation>******************** Tin layer ********************</xs:documentation>
	</xs:annotation>
	<xs:complexType name="TinLayerDefinitionType">
		<xs:annotation>
			<xs:documentation>A layer for tin data.</xs:documentation>
		</xs:annotation>
		<xs:complexContent>
			<xs:extension base="BaseLayerDefinitionType">
				<xs:sequence>
					<xs:element name="FeatureName" type="xs:string"/>
					<xs:element name="Geometry" type="xs:string">
						<xs:annotation>
							<xs:documentation>Specifies the geometry property that should be used to get the geometries.</xs:documentation>
						</xs:annotation>
					</xs:element>
					<xs:element name="Filter" type="xs:string" minOccurs="0">
						<xs:annotation>
							<xs:documentation>A boolean FDO expression that specifies which features to return.  No filter means pass all features through.</xs:documentation>
						</xs:annotation>
					</xs:element>
					<xs:element name="TinScaleRange" type="TinScaleRangeType" maxOccurs="unbounded"/>
					<xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
				</xs:sequence>
			</xs:extension>
		</xs:complexContent>
	</xs:complexType>
	<xs:complexType name="TinScaleRangeType">
		<xs:annotation>
			<xs:documentation>The stylization for a specified scale range.</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="MinScale" type="xs:double" minOccurs="0">
				<xs:annotation>
					<xs:documentation>The zoomed in part of the scale range.  Defaults to 0 if not specified.  Inclusive.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="MaxScale" type="xs:double" minOccurs="0">
				<xs:annotation>
					<xs:documentation>The zoomed out part of the scale range.  Defaults to the application's maximum value if not specified.  Exclusive.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="Elevation" minOccurs="0">
				<xs:annotation>
					<xs:documentation>The elevation information of tin surface.</xs:documentation>
				</xs:annotation>
				<xs:complexType>
					<xs:sequence>
						<xs:element name="ZeroValue" type="xs:double" minOccurs="0">
							<xs:annotation>
								<xs:documentation>The user defined zero value. Defaults to 0 if not specified. </xs:documentation>
							</xs:annotation>
						</xs:element>
						<xs:element name="ScaleFactor" type="xs:double" minOccurs="0">
							<xs:annotation>
								<xs:documentation>Determines how to scale the  elevation.  Defaults to 1 if not specified.</xs:documentation>
							</xs:annotation>
						</xs:element>
					</xs:sequence>
				</xs:complexType>
			</xs:element>
			<xs:element name="Point" type="CompositeTypeStyle" minOccurs="0">
				<xs:annotation>
					<xs:documentation>All points in tin surface.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="Edge" type="CompositeTypeStyle" minOccurs="0">
				<xs:annotation>
					<xs:documentation>All edges in tin surface.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="Face" type="TinFaceType" minOccurs="0">
				<xs:annotation>
					<xs:documentation>All triangles faces in tin surface.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="TinColorRuleType">
		<xs:annotation>
			<xs:documentation>Encapsulate a style for a tin source.</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="LegendLabel" type="xs:string">
				<xs:annotation>
					<xs:documentation>The label for the Rule to be displayed in the legend.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="Filter" type="xs:string" minOccurs="0">
				<xs:annotation>
					<xs:documentation>A filter for the Rule.  This is a boolean FDO expression.  Any features that pass this filter are styled using this rule's stylization.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="Label" type="TextSymbolType" minOccurs="0">
				<xs:annotation>
					<xs:documentation>A label for the Rule.  Does not apply to tin ColorRule.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="Color" type="xs:string">
				<xs:annotation>
					<xs:documentation>The color to use.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="TinFaceType">
		<xs:annotation>
			<xs:documentation>Style rule for a face type.</xs:documentation>
		</xs:annotation>
		<xs:sequence minOccurs="0">
			<xs:element name="HillShade" type="TinHillShadeType" minOccurs="0"/>
			<xs:element name="ColorRule" type="TinColorRuleType" minOccurs="0" maxOccurs="unbounded"/>
			<xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="TinHillShadeType">
		<xs:annotation>
			<xs:documentation>Specifies how to shade given a band and a light source.</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="Azimuth" type="xs:double">
				<xs:annotation>
					<xs:documentation>Azimuth of the sun in degrees.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="Altitude" type="xs:double">
				<xs:annotation>
					<xs:documentation>Altitude of the sun in degrees.</xs:documentation>
				</xs:annotation>
			</xs:element>
			<xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
		</xs:sequence>
	</xs:complexType>
}}}
==== !Example ===

==! FDO Provider Modifications ==
TIN FDO Provider will be added to connect to TIN files.
== Implications ==
The new TIN layer definition will have an impact on the LayerDefinition XML schema. Backwards compatibility should be maintained and will not break any existing applications. That is to say, applications with later version can completely open files created by applications with former version, while applications with former version should ignore TIN layer when opening file created by applications with later version.  Documentation will need to be updated for the new functionality. 
In future, FDO Provider will be changed to support TIN connection.
== Test Plan ==
Unit tests should include creating TIN layers, stylizing TIN layers and TIN FDO Provider. 
Backward compatibility should be tested. Files created by new application should not break existing applications. 
== Funding/Resources ==
Autodesk to provide resources/funding.