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 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() {};
};

Class FdoISpiralSegmentAbstract

/// \brief
/// The FdoISpiralSegmentAbstract class represets a Spiral curve segment (abstract)
///
class FdoISpiralSegmentAbstract : public FdoICurveSegmentAbstract
{
public:
    /// \brief
    /// Gets the clockwise state from this spiral segment.
    /// 
    /// \return
    /// Returns true if the spiral is defined clockwise, otherwise false
    /// 
    virtual bool GetIsClockwise() const = 0;
};

Class FdoISplineSegmentAbstract

/// \brief
/// The FdoISplineSegmentAbstract class is the base class for 
/// Spline segments (abstract)
///
class FdoISplineSegmentAbstract : public FdoICurveSegmentAbstract
{
public:
    /// \brief
    /// Gets the algebraic degree of the spline's basis function.
    /// The spline's degree is a positive integer that is the degree 
    /// of the polynomial equations used to calculate the pieces of 
    /// the spline. For Cubic splines, the degree is fixed at 3.
    /// 
    /// \return
    /// Returns an interger specifying the spline's degree value
    /// 
    virtual FdoInt32 GetDegree() const = 0;

    /// \brief
    /// Gets the the interpolation mechanism for a spline Geometry.
    /// Is fixed as Cubic for Cubic splines. Can be polynomial or 
    /// Rational for B-Splines.
    /// 
    /// \return
    /// Returns the interpolation mechanism used to create the spline
    /// 
    virtual FdoGeometricInterpolationType GetInterpolationType() const = 0;

    /// \brief
    /// Gets the collection of control position associated to this Spline Geometry.
    /// 
    /// \return
    /// Returns the collection of control positions associated to the spline
    /// 
    virtual FdoDirectPositionCollection const* GetControlPositions() const = 0;

    /// \brief
    /// Gets the number of control positions associated to this Spline geometry.
    /// 
    /// \return
    /// Returns the control position count
    /// 
    virtual FdoInt32 GetControlPositionCount() const = 0;

    /// \brief
    /// Gets a control position at the specified (zero-based) index.
    /// 
    /// \param index 
    /// Input Zero-based index in the Spline's list of control positions.
    /// 
    /// \return
    /// Returns the control position position at the specified index
    /// 
    virtual FdoIDirectPosition const* GetControlPosition(FdoInt32 index) const = 0;

    /// \brief
    /// Gets the control position at the specified (zero-based) index, 
    /// by values of its member data. 
    /// This is in aid of higher performance for any implementation that
    /// does not internally use FdoIDirectPosition objects for storage, or for
    /// an application seeking to avoid overhead of accessor methods.
    /// 
    /// \param index 
    /// Input Zero-based index in the object's list of control positions.
    /// \param x 
    /// Output X ordinate value.
    /// \param y 
    /// Output Y ordinate value.
    /// \param z 
    /// Output Z ordinate value.
    /// \param m 
    /// Output M ordinate value.
    /// \param dimensionality 
    /// Output Dimensionality of ordinates in this control position.
    /// 
    /// \return
    /// Returns nothing
    /// 
    virtual void GetControlPositionByMembers(
        FdoInt32 index,
        double *x,
        double *y,
        double *z,
        double *m,
        FdoInt32 *dimensionality) const = 0;

    /// \brief
    /// Gets the spline control positions as an array.
    /// 
    /// \remarks
    /// The caller must not free the returned array.
    /// The ordinates are in the order XYZMXYZM..., with only those present 
    /// according to the dimensionality.
    /// 
    /// \return
    /// Returns the spline's control positions ordinates
    /// 
    virtual const double * GetControlPositionOrdinates() = 0;
};

Class FdoICubicSplineSegment

/// \brief
/// The FdoICubicSplineSegment class is a Cubic Spline geometry type.
/// A cubic spline is a spline constructed of piecewise third-order polynomials 
/// which pass through a set of control positions. The second derivative of each 
/// polynomial is commonly set to zero at the end position, since this provides a 
/// boundary condition that completes the system of equations.
/// 
class FdoICubicSplineSegment : public FdoISplineSegmentAbstract
{
public:
    /// \brief
    /// Gets the unit tangent vector at the start position of the spline.
    /// Only the direction of the vectors shall be used to determine 
    /// the shape of the cubic spline, not their length.
    /// 
    /// \return
    /// Returns the tangent vector
    /// 
    virtual FdoIDirectPosition const * GetStartTangent() const = 0;

    /// \brief
    /// Gets the unit tangent vector at the end position of the spline. 
    /// Only the direction of the vectors shall be used to determine 
    /// the shape of the cubic spline, not their length.
    /// 
    /// \return
    /// Returns the tangent vector
    /// 
    virtual FdoIDirectPosition const * GetEndTangent() const = 0;
};

Enum GeometricKnotTypes

/// \brief
/// Enumeration used to identify the B-spline knot type used to 
/// ineterpolate a B-Spline.  
///
/// \remarks
/// A B-spline is uniform if and only if all knots are
/// of multiplicity 1 and they differ by a positive constant
/// from the preceding knot. 
///
/// A B-spline is quasi-uniform if and 
/// only if the knots are of multiplicity (degree+1) at the ends, 
/// of multiplicity 1 elsewhere, and they differ by a positive constant 
/// from the preceding knot. 
/// 
/// In general, in a piecewise Bezier knot vector, the first k knots are 
/// the same, then each subsequent group of k-1 knots is the same, 
/// until you get to the end. Note that a piecewise Bézier curve must 
/// have nk–1 control positions, where n is the number of segments 
/// (i.e., the number of control positions is one less than an even 
/// multiple of the order).
/// 
enum FdoGeometricKnotType
{
    /// The knots are appropriate for a uniform B-spline. 
    /// e.g. [0 1 2 3 4 5].
    ///
    FdoGeometricKnotType_Uniform = 500,

    /// The knots are appropriate for a quasi-uniform B-spline. 
    /// e.g. [0 0 0 0 1 2 3 3 3 3]
    /// 
    FdoGeometricKnotType_QuasiUniform = 501,

    /// The knots are appropriate for a piecewise Bezier curve. 
    /// e.g. [0 0 0 1 1 2 2 3 3 3]
    ///
    FdoGeometricKnotType_PiecewiseBezier = 502,
};

Class FdoIBSplineKnot

/// \brief
/// Controls the constructive parameter space for spline curves. 
/// Each knot sequence is used for a dimension of the spline's 
/// parameter space. 
/// 
class FdoIBSplineKnot : public FdoIDisposable
{
public:

    /// \brief
    /// Gets the value of the parameter at the knot of the spline.
    /// The sequence of knots shall be a nondecreasing sequence. 
    /// That is, each knot's value in the sequence shall be equal 
    /// to or greater than the previous knot's value. The use of 
    /// equal consecutive knots is normally handled using the 
    /// multiplicity. 
    /// 
    /// \return
    /// Returns the knot parameter
    /// 
    virtual double GetValue() const = 0;

    /// \brief
    /// Gets The value of the averaging weight used for this
    /// knot of the spline
    /// 
    /// \return
    /// Returns the knot weight
    /// 
    virtual double GetWeight() const = 0;

    /// \brief
    /// Gets the multiplicity of this knot used in the definition of 
    /// the spline (with the same weight).
    /// 
    /// \return
    /// Returns the knot multiplicity
    /// 
    virtual FdoInt32 GetMultiplicity() const = 0;
};

Class FdoBSplineKnotCollection

/// \brief
///  The FdoBSplineKnotCollection class is a collection of FdoIBSplineKnot objects.
///
class FdoBSplineKnotCollection : public FdoCollection<FdoIBSplineKnot, FdoException>
{
public:
    /// \brief
    /// Creates an instance of FdoBSplineKnotCollection with no contained elements.
    /// 
    /// \return
    /// Returns an empty collection
    /// 
    static FdoBSplineKnotCollection* Create()
    {
        FdoBSplineKnotCollection* value = new FdoBSplineKnotCollection();
        if (NULL == value)
            throw FdoException::Create(
                FdoException::NLSGetMessage(FDO_NLSID(FDO_1_BADALLOC)));
        return value;
    }
};

Class !FdoIBSplineSegment

/// \brief
/// The FdoIBSplineSegment class is a B-Spline geometry type.
/// A B-Spline is a piecewise parametric polynomial or rational 
/// curve described in terms of control positions and basis functions.
/// The interpolation method may be either "polynomial" or "rational" 
/// depending on the interpolation type; default is "polynomial".
/// 
class FdoIBSplineSegment : public FdoISplineSegmentAbstract
{
public:

    /// \brief
    /// Determines in the B-Spline is a polynomial spline
    /// 
    /// \return
    /// Returns true if the Spline is polynomial, otherwise false
    /// 
    virtual bool GetIsPolynomial() const = 0;

    /// \brief
    /// Gets the knot type of the B-Spline
    /// 
    /// \return
    /// Returns the knot type as an FdoGeometricKnotType enumeration
    /// 
    virtual FdoGeometricKnotType GetKnotType() const = 0;
   
    /// \brief
    /// Gets the collection of knots associated to this Spline Geometry.
    /// 
    /// \return
    /// Returns the collection of knots associated to the spline
    /// 
    virtual FdoBSplineKnotCollection const* GetKnots() const = 0;

    /// \brief
    /// Gets the number of knots associated to this Spline geometry.
    /// 
    /// \return
    /// Returns the knot count
    /// 
    virtual FdoInt32 GetKnotCount() const = 0;

    /// \brief
    /// Gets a knot at the specified (zero-based) index.
    /// 
    /// \param index 
    /// Input Zero-based index in the Spline's list of knots.
    /// 
    /// \return
    /// Returns the knot at the specified index
    /// 
    virtual FdoIBSplineKnot const* GetKnot(FdoInt32 index) const = 0;

    /// \brief
    /// Gets the knot at the specified (zero-based) index, by values of
    /// its member data. This is in aid of higher performance for any 
    /// implementation that does not internally use knot objects for storage, 
    /// or for an application seeking to avoid overhead of accessor methods.
    /// 
    /// \param index 
    /// Input Zero-based index in the object's list of control positions.
    /// \param value 
    /// Output knot value.
    /// \param weight 
    /// Output knot weight.
    /// \param multiplicity 
    /// Output the mutiplicity of the knot.
    /// 
    /// \return
    /// Returns nothing
    /// 
    virtual void GetKnotByMembers(
        FdoInt32 index,
        double *value,
        double *weight,
        FdoInt32 *multiplicity) const = 0;
};

Geometry Factory

/// \brief
///  
/// The FdoGeometryFactoryAbstract class is a factory (abstract, non-pure) 
/// for Geometry objects and Geometry helper objects.
///
class FdoGeometryFactoryAbstract : public FdoIDisposable
{
public:
…
…

    /// EllipticalArcSegment

    /// \brief
    /// Creates a EllipticalArcSegment object by specifying three 
    /// points on the arc, and the two focal positions.
    /// 
    /// \param startPosition 
    /// Input starting position of the ellipse
    /// \param midPosition 
    /// Input a position on the ellipse, and not equal to the starting 
    /// or ending positions
    /// \param endPosition 
    /// Input ending position of the ellipse
    /// \param focalPoisition1 
    /// Input the first focal position of the ellipse
    /// \param focalPoisition2 
    /// Input the second focal position of the ellipse
    /// 
    /// \return
    /// Returns an EllipticalArc Segment
    /// 
    virtual FdoIEllipticalArcSegment* CreateEllipticalArcSegment(
        FdoIDirectPosition* startPosition,
        FdoIDirectPosition* midPosition,
        FdoIDirectPosition* endPosition,
        FdoIDirectPosition* focalPoisition1,
        FdoIDirectPosition* focalPoisition2) = 0;

    /// CircleSegment

    /// \brief
    ///  Creates a CircleSegment object using three points on the circle.
    /// 
    /// \param firstPosition 
    /// Input first position of the circle
    /// \param secondPosition 
    /// Input a position on the circle, and not equal to the first or third positions
    /// \param thirdPosition 
    /// Input third position of the circle
    /// 
    /// \return
    /// Returns a CircleSegment
    /// 
    FDO_GEOM_API virtual FdoICircleSegment* CreateCircleSegment(
        FdoIDirectPosition* firstPosition,
        FdoIDirectPosition* secondPosition,
        FdoIDirectPosition* thirdPosition) = 0;

    /// SplineSegments

    /// \brief
    /// Creates a Cubic Spline segment from the start and end tangents, 
    /// and a set of control positions
    /// 
    /// \param startTangent 
    /// Input the start tanget of the spline
    /// \param endTangent 
    /// Input the end tanget of the spline
    /// \param controlPositions 
    /// Input the collection of control positions that define the spline
    /// \return
    /// Returns a Cubic Spline Segment
    /// 
    virtual FdoICubicSplineSegment* CreateCubicSplineSegment(
        FdoIDirectPosition* startTangent,
        FdoIDirectPosition* endTangent,
        FdoDirectPositionCollection* controlPositions) = 0;

    /// \brief
    /// Creates a B-Spline segment from collections of 
    /// control positions and knots, 
    /// 
    /// \param degree 
    /// Input the algebraic degree of the basis function. 
    /// \param controlPositions 
    /// Input the control positions that will be used to contruct the spline 
    /// \param knots 
    /// Input the knots that will be used to contruct the spline 
    /// \param weights 
    /// \param knotType 
    /// Input the knotType to be used to contruct the spline 
    /// 
    /// \return
    /// Returns a B-Spline Segment
    /// 
    virtual FdoIBSplineSegment* CreateBSplineSegment(
        FdoInt32 degree,
        FdoDirectPositionCollection* controlPositions,
        FdoBSplineKnotCollection* knots,
        FdoGeometricKnotType knotType) = 0; /// KnotType: TDB
};

FGF Text Definitions

The following FGF Text definitions will be supported by the FDO API for the new types specified above.

EllipticalArc Segment

ELLIPTICALARCSEGMENT (
    [Mid Position], 
    [End Position],
    [Focal Point 1], 
    [Focal Point 2]
)

Example

CURVESTRING XYZ (0 0 0 (
    CIRCULARARCSEGMENT (0 1 0, 1 2 0), 
    LINESTRINGSEGMENT  (3 0 0, 3 2 0),
    ELLIPTICALARCSEGMENT (-1 1 0, 1 3 0, 2 0 0, 3 0 0)
))

Implications

TBD.

Test Plan

TBD.

Funding/Resources

Autodesk to provide resources / funding