= FDO RFC 11 -  Adding Geometric Expression Functions =

This page contains a request for comments document (RFC) for the FDO Open Source project.  
More FDO RFCs can be found on the [wiki:FDORfcs RFCs] page.

== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date||Aug 03, 2007||
||Last Modified||Dan Stoica[[Timestamp]]||
||Author||Thomas Knoell||
||RFC Status||Adopted||
||Implementation Status ||Implemented||
||Proposed Milestone||3.3.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||  ||
||+1||Greg, Frank, Jason, Orest, Harris||
||+0||||
||-0||||
||-1||||
 
== Overview ==

This RFC follows from RFC 8 by adding two geometric functions. RFC 8 laid the foundation for a common set of functions that providers could support. That RFC left out two commonly used geometric functions, ''Area()'' and ''Length()''. This RFC adds those two functions. A reason for adding these functions in a separate RFC is that there are coordinate system considerations that need to be defined and discussed that do not apply to the list of functions in RFC8. Many providers do not include a coordinate system library internally (e.g. MySql, SHP, SDF) while other providers (e.g. Oracle) do include a coordinate system library. ''Area()'' and ''Length()'' calculations on geometry with geodetic coordinate systems require a coordinate system library to do the spheroid-based calculations to provide correct results. 

It is the proposal of this RFC that providers that do not use coordinate system libraries to use instead calculations based on general accepted formulae to compute the geodetic distance for ''Length()'' and use Euclidian calculation based on geodetic distance for ''Area()''. This will also be the case when a provider native ''Length()'' or ''Area()'' implementations are found not reliable or defective.


== Signatures ==
This RFC proposes the following signatures for the geometric functions Area and Length:

'''!FdoDouble Area (<geometry property>);'''

'''!FdoDouble Length (<geometry property>);'''


Both functions accept a geometry property only. The result of the functions depend on the provided geometry:

''AREA()'':
 * if the provided geometry is a line or point geometry, the result is 0.
 * if the provided geometry is a polygon, area is the result of the area of the exterior loops minus the area of the interior loops.

''LENGTH()'':
 * if the provided geometry is a point geometry, the result is 0
 * if the provided geometry is a line, the result is the length of the object
 * if the provided geometry is a polygon, the result is the length of the perimeter which includes all exterior and interior loops.

For projected systems or for unknown coordinate systems the function ''Length()'' will return values in implicit length units while ''Area()'' will use the square of the length units. 

For geodetic systems, the length will be expressed in meters and the area in square meters.

The functions will execute 2D calculations only. Therefore, the Z value will be ignored.


Like the standard functions listed in RFC 8, the user can get access to the geometric function definitions via the FDO interface ''!GetWellKnownFunctions''. The new functions will be categorized as geometry functions (''!FdoFunctionCategoryType_Geometry'').


=== Example ===

Assuming that a class ''Road'' has a geometry property named ''geom'', a call to ''Length(geom)'' will return the length of a road object.


== Affected Providers ==

This enhancement will affect the following providers: ArcSDE, MySQL, SDF and SHP.


== Required FDO Enhancements ==

No FDO enhancements are required.


== Implications ==

This change will not cause any side-effects. No existing provider needs to change unless the provider wants to expose the new capability.

== Test Plan ==

Existing unit tests will be enhanced to test those changes.

== Funding/Resources ==

Autodesk to provide resource / funding to implement the feature for the affected providers.