= FDO RFC 59 - Support New FDO Geometry Types =

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.1||
||Submission Date||April 10, 2011||
||Last Modified||Greg Boone, April 10, 2011||
||Author||Greg Boone||
||RFC Status||Proposed||
||Implementation Status||Not Ready For Review||
||Proposed Milestone||3.7.0.0||
||Assigned PSC guide(s)||Greg Boone||
||'''Voting History'''||(vote date)||
||+1||||
||+0||||
||-0||||
||-1||||
 
== Overview ==

Add support to the FDO Geometry API for additional parametric geometry types: Circles, Elliptical Arcs, Cubic Splines and B-Splines.

== Motivation ==

Since the FDO API will continue to be used by new and existing clients as an interchange format, support is required for additional parametric geometry types. Specifically support for elliptical arc, cubic spline, and bspline segments. This will allow more accurate interchange of parametric geometry from client applications without having to tessellate and either lose or create ad-hoc storage for parametric geometry information.

== Proposed Solution ==

The following new Geometry Segment types will be added to the FDO Geometry API to support an enhanced set of parametric geometry types. 

  -  !CircleSegment
  -  !EllipticalArcSegment
  -  !CubicSplineSegment
  -  BSplineSegment

These types work with/derive from existing types that already exist in the FDO Geometry API. Those classes act as base or sibiling classes for the types being added. The existing types include:

  -  !CurveSegmentAbstract
  -  !ArcSegmentAbstract
  -  !CircularArcSegment
  -  !LineStringSegment

Appendix “A” describes these interfaces in their API form. For additional information of the complete set of FDO Geometry API classes, refer to the online FDO API documentation, starting with the following links: 

  -  FdoIGeometry: http://fdo.osgeo.org/files/fdo/docs/FDO_API/da/da2/class_fdo_i_geometry.htm
  -  FdoICurveSegmentAbstract: http://fdo.osgeo.org/files/fdo/docs/FDO_API/df/d3b/class_fdo_i_curve_segment_abstract.htm

=== Enum !GeometryComponentType ===

The !GeometryComponnetType enumeration will be enhanced to include enumerations for the new segment types listed above. The full enumeration is provided below, but the new types being added are as follows:

  -  !FdoGeometryComponentType_EllipticalArcSegment
  -  !FdoGeometryComponentType_CubicSplineSegmen
  -  !FdoGeometryComponentType_BSplineSegment
  -  !FdoGeometryComponentType_CircleSegment


{{{
/// \brief
/// Enumeration for components of Geometry.
/// 
/// \remarks
/// This enumeration applies to certain helper types that 
/// are used to compose other types which derive from FdoIGeometry.
///
enum FdoGeometryComponentType
{
    /// LinearRing type (FdoILinearRing).
    FdoGeometryComponentType_LinearRing = 129,

    /// CircularArcSegment type (FdoICircularArcSegment).
    FdoGeometryComponentType_CircularArcSegment = 130,

    /// LineStringSegment type (FdoILineStringSegment).
    FdoGeometryComponentType_LineStringSegment = 131,

    /// Ring type (FdoIRing).
    FdoGeometryComponentType_Ring = 132,

    /// EllipticalArcSegment type (FdoIEllipticalArcSegment).
    FdoGeometryComponentType_EllipticalArcSegment = 133,

    /// CubicSplineSegment type (FdoICubicSplineSegment).
    FdoGeometryComponentType_CubicSplineSegment = 135,

    /// BSplineSegment type (FdoIBSplineSegment).
    FdoGeometryComponentType_BSplineSegment = 136,	

    /// CircleSegment type (FdoICircleSegment).
    FdoGeometryComponentType_CircleSegment = 137
};
}}} 


=== Class FdoIEllipticalArcSegment  === 

{{{
/// \brief
/// The FdoIEllipticalArcSegment class represets an Elliptical Arc Segment 
/// geometry type. EllipticalArcSegment can describe portions of, or a full 
/// ellipse. If describing a full ellipse, the start and end points are identical
/// and the mid-point is the diametrically opposite point on the ellipse.
///
/// \remarks
/// Two foci were specified as opposed to major/minor axes so that the 
/// API can derive this class from ArcSegmentAbstract and CurveSegmentAbstract, 
/// thus reusing the concepts of start/mid/end points as defined in the base
/// classes. In this manner the API can maintain a common look/feel when defining
/// arc types. The expectation is that a Geometry API utility method will be
/// provided that will allow conversion to major/minor axis.
///
/// The semimajor axis and the semiminor axis are one half of the major and minor 
/// diameters, respectively. These are sometimes called the major and minor semi-axes, 
/// the major and minor semiaxes,or major radius and minor radius.
///
/// The foci of the ellipse are two special points on the ellipse's major 
/// axis and are equidistant from the center point. The sum of the distances from any 
/// point on the ellipse to those two foci is constant and equal to the major 
/// diameter. Each of these two points is called a focus of the ellipse.
///
class FdoIEllipticalArcSegment : public FdoIArcSegmentAbstract
{
public:

    /// \brief
    /// Gets the two focal positions of this Ellipse Geometry.
    /// 
    /// \return
    /// Returns the two focal positions of the Ellipse as a collection 
    /// of two positions.
    /// 
    virtual FdoIDirectPositionCollection const * GetFocalPositions() const = 0;

    /// \brief
    /// Gets the two focal positions of this Ellipse Geometry as an array.
    /// The ordinates are in the order XYZMXYZM, with only those present 
    /// according to the dimensionality.
    /// 
    /// \return
    /// Returns the two focal positions of the Ellipse as a collection 
    /// 
    virtual const double * GetFocalPositionOrdinates() = 0;
};
}}}


=== Class FdoICircleSegment === 

/// \brief
/// The FdoICircleSegment class represents a circle as an arc whose ends 
/// coincide to form a simple closed loop. The three control positions shall be 
/// distinct non-co-linear positions for the circle to be unambiguously defined. 
/// The arc is simply extended past the third control position until the first 
/// control position is encountered.
///
/// \remarks
/// Circle segments cannot be defined as non-closed segments. 
/// If describing a circle where the start and end points are identical
/// the mid-point is the diametrically opposite point on the circle.
///
class FdoICircleSegment : public FdoIArcSegmentAbstract
{
protected:

    /// \brief
    /// Constructs a default instance.
    /// 
    FdoICircleSegment() {};

    /// \brief
    /// Default destructor.
    /// 
    virtual ~FdoICircleSegment() {};
};



== Implications ==

TBD.

== Test Plan ==

TBD.

== !Funding/Resources ==

Autodesk to provide resources / funding