Changes between Version 15 and Version 16 of FDORfc59

Timestamp:

04/10/11 16:20:34 (14 years ago)

Author:

gregboone

Comment:

--

FDORfc59

@@ -842 +842 @@
 
 
+== !GeometryFactory Examples ==
+
+=== Elliptical Arc Segment Example ===
+
+{{{
+FdoICurveString* CreateCurveString()
+{
+    // Create and return a curve string consisting of
+    // one elliptical arc segment
+    // one linear string segment
+
+    // line segment = (0 0 0), (3 0 0), (3 2 0)
+    
+    FdoPtr<FdoFgfGeometryFactory> gf = FdoFgfGeometryFactory::GetInstance();
+
+    FdoPtr<FdoDirectPositionCollection> points = FdoDirectPositionCollection::Create();
+    FdoPtr<FdoIDirectPosition> pt1 = gf->CreatePositionXY(0.0, 0.0);
+    FdoPtr<FdoIDirectPosition> pt2 = gf->CreatePositionXY(3.0, 0.0);
+    FdoPtr<FdoIDirectPosition> pt3 = gf->CreatePositionXY(3.0, 2.0);
+    points->Add(pt1);
+    points->Add(pt2);
+    points->Add(pt3);
+
+    FdoPtr<FdoILineStringSegment> lineSeg = gf->CreateLineStringSegment(points);
+    
+    // elliptical segment = (3 2 0), (-1 1 0), (1 3 0), (2 0 0), (3 0 0)
+
+    FdoPtr<FdoIDirectPosition> startPos =  gf->CreatePositionXY(3.0, 2.0);
+    FdoPtr<FdoIDirectPosition> midPos =    gf->CreatePositionXY(-1.0, 1.0);
+    FdoPtr<FdoIDirectPosition> endPos =    gf->CreatePositionXY(1.0, 3.0);
+    FdoPtr<FdoIDirectPosition> focalPos1 = gf->CreatePositionXY(2.0, 0.0);
+    FdoPtr<FdoIDirectPosition> focalPos2 = gf->CreatePositionXY(3.0, 0.0);
+
+    FdoPtr<FdoIEllipticalArcSegment> arcSeg = gf->CreateEllipticalArcSegment(
+            startPos, 
+            midPos, 
+            endPos, 
+            focalPos1, 
+            focalPos2);
+
+    FdoPtr<FdoCurveSegmentCollection> curveSegs = FdoCurveSegmentCollection::Create();
+    curveSegs->Add(lineSeg);
+    curveSegs->Add(arcSeg);
+
+    FdoPtr<FdoICurveString> curveString = gf->CreateCurveString(curveSegs);
+
+    CheckFGFT(curveString, L"CURVESTRING (0 0 (" 
+                           L"LINESTRINGSEGMENT (3 0, 3 2),"
+                           L"ELLIPTICALARCSEGMENT (-1 1, 1 3, 2 0, 3, 0)"
+                           L"))");
+
+    return FDO_SAFE_ADDREF(curveString.p);
+}
+}}}
+
+=== Circle Segment Example ===
+
+{{{
+FdoICurveString* CreateCurveString()
+{
+    // Create and return a curve string consisting of
+    // one circle segment
+
+    // circle segment = (0 0 0), (-1 1 0), (1 3 0)
+
+    FdoPtr<FdoIDirectPosition> pt1 = gf->CreatePositionXY(0.0, 0.0);
+    FdoPtr<FdoIDirectPosition> pt2 = gf->CreatePositionXY(-1.0, 1.0);
+    FdoPtr<FdoIDirectPosition> pt3 = gf->CreatePositionXY(1.0, 3.0);
+
+    FdoPtr<FdoICircleSegment> circleSeg = gf->CreateCircleSegment(
+            pt1, 
+            pt2, 
+            pt3);
+
+    FdoPtr<FdoCurveSegmentCollection> curveSegs = FdoCurveSegmentCollection::Create();
+    curveSegs->Add(circleSeg);
+
+    FdoPtr<FdoICurveString> curveString = gf->CreateCurveString(curveSegs);
+
+    CheckFGFT(curveString, L"CURVESTRING (0 0 (" 
+                           L"CIRCLESEGMENT (-1 1, 1 3)"
+                           L"))");
+
+    return FDO_SAFE_ADDREF(curveString.p);
+}
+}}}
+
+=== Cubic Spline Segment Example ===
+
+{{{
+FdoICurveString* CreateCurveString()
+{
+    // Create and return a curve string consisting of:
+    // one linear string segment
+    // one circular arc segment
+    // one cubic spline segment
+
+    // line segment = (0 0 0), (7.5 0 0), (11.5 4 0)
+    
+    FdoPtr<FdoFgfGeometryFactory> gf = FdoFgfGeometryFactory::GetInstance();
+
+    FdoPtr<FdoDirectPositionCollection> points = FdoDirectPositionCollection::Create();
+    FdoPtr<FdoIDirectPosition> pt1 = gf->CreatePositionXY(0.0, 0.0);
+    FdoPtr<FdoIDirectPosition> pt2 = gf->CreatePositionXY(7.5, 0.0);
+    FdoPtr<FdoIDirectPosition> pt3 = gf->CreatePositionXY(11.5, 4.0);
+    points->Add(pt1);
+    points->Add(pt2);
+    points->Add(pt3);
+
+    FdoPtr<FdoILineStringSegment> lineSeg = gf->CreateLineStringSegment(points);
+    
+    // circular arc segment = (11.5 4 0), (13 7.5 0), (12.5 12 0)
+
+    FdoPtr<FdoIDirectPosition> startPos = gf->CreatePositionXY(11.5, 4.0);
+    FdoPtr<FdoIDirectPosition> midPos = gf->CreatePositionXY(13.0, 7.5);
+    FdoPtr<FdoIDirectPosition> endPos = gf->CreatePositionXY(12.5, 12.0);
+
+    FdoPtr<FdoICircularArcSegment> arcSeg = gf->CreateCircularArcSegment(
+        startPos, midPos, endPos);
+
+    // cubic spline segment = (8 3 0), (5 15 0), (6 19 0), (0 0 0), (0 0 0)
+
+    FdoPtr<FdoDirectPositionCollection> cntrlptColl = FdoDirectPositionCollection::Create();
+    FdoPtr<FdoIDirectPosition> cntrlpt1 = gf->CreatePositionXY(8.0, 3.0);
+    FdoPtr<FdoIDirectPosition> cntrlpt2 = gf->CreatePositionXY(5.0, 15.0);
+    FdoPtr<FdoIDirectPosition> cntrlpt3 = gf->CreatePositionXY(6.0, 19.0);
+    cntrlptColl-Add(cntrlpt1);
+    cntrlptColl-Add(cntrlpt2);
+    cntrlptColl-Add(cntrlpt3);
+
+    FdoPtr<FdoIDirectPosition> startTan = gf->CreatePositionXY(0.0, 0.0);
+    FdoPtr<FdoIDirectPosition> endTan = gf->CreatePositionXY(0.0, 0.0);
+
+    FdoPtr<FdoICubicSplineSegment> splineSeg = gf->CreateCubicSplineSegment(
+            cntrlptColl, 
+            startTan, 
+            endTan);
+
+    FdoPtr<FdoCurveSegmentCollection> curveSegs = FdoCurveSegmentCollection::Create();
+    curveSegs->Add(lineSeg);
+    curveSegs->Add(arcSeg);
+    curveSegs->Add(splineSeg);
+
+    FdoPtr<FdoICurveString> curveString = gf->CreateCurveString(curveSegs);
+
+    CheckFGFT(curveString,  L"CURVESTRING XYZ (0 0 0 ("
+                            L"LINESTRINGSEGMENT  (7.5 0 0, 11.5 4 0),"
+                            L"CIRCULARARCSEGMENT (13 7.5 0, 12.5 12 0),"
+                            L"CUBICSPLINESEGMENT (2, 5 15 0, 6 19 0, 0 0 0, 0 0 0)"
+                            L"))"
+
+    return FDO_SAFE_ADDREF(curveString.p);
+}
+}}}
+ 
+== Appendix A: Existing FDO API Curve Segment Classes ==
+
+The classes described in the following sections currently exist in the FDO Geometry API (Version 3.6.0) and form base and sibling classes to those proposed in the sections above. They are included here for illustrative and comparative purposes.
+
+=== ICurveSegmentAbstract ===
+
+{{{
+/// \brief
+/// The FdoICurveSegmentAbstract class is an abstract geometric Curve Segment object.  
+/// This class is used strictly as a component of curves 
+/// and, thus, does not inherit from IGeometry.
+class FdoICurveSegmentAbstract : public FdoIDisposable
+{
+public:
+
+    /// \brief
+    /// Gets the envelope for the curve segment.
+    /// 
+    /// \return
+    /// Returns the envelope
+    /// 
+    FDO_GEOM_API virtual FdoIEnvelope* GetEnvelope() const = 0;
+
+    /// \brief
+    /// Gets the starting position of this curve segment.
+    /// 
+    /// \return
+    /// Returns the starting position
+    /// 
+    FDO_GEOM_API virtual FdoIDirectPosition* GetStartPosition() const = 0;
+
+    /// \brief
+    /// Gets the ending position of this curve segment.
+    /// 
+    /// \return
+    /// Returns the ending position
+    /// 
+    FDO_GEOM_API virtual FdoIDirectPosition* GetEndPosition() const = 0;
+
+    /// \brief
+    /// Gets the closure state for the curve segment.
+    /// 
+    /// \remarks
+    /// The meaning behind this method is not guaranteed
+    /// to be uniform between derived types or between implementations
+    /// of this package. It may represent a computed value, an explicit 
+    /// attribute, or be true by definition. As a computed value, the 
+    /// result is typically from simply testing the starting and 
+    /// ending positions for exact equality.  This is only reliable in floating
+    /// point arithmetic if these data have identical origins.
+    /// As an explicit attribute, it would be persisted with the Geometry and 
+    /// typically denoted by a parameter in the relevant factory method.  
+    /// Some Geometry types are closed by definition.
+    /// 
+    /// \return
+    /// Returns 'true' if the curve is closed, and false otherwise
+    /// 
+    FDO_GEOM_API virtual bool GetIsClosed() const = 0;
+
+    /// \brief
+    /// Gets the type of the most-derived interface 
+    /// in the Geometry package for this object
+    /// 
+    /// \return
+    /// Returns the derived type
+    /// 
+    FDO_GEOM_API virtual FdoGeometryComponentType GetDerivedType() const = 0;
+
+    /// \brief
+    /// Gets the dimensionality of ordinates in this object.
+    /// 
+    /// \remarks
+    /// Values are from the FdoDimensionality enumeration.
+    /// A return type of "FdoInt32" is used instead of the enumeration, 
+    /// catering to typical use with bit masking.
+    /// 
+    /// \return
+    /// Returns the ordinate dimensionality
+    /// 
+    FDO_GEOM_API virtual FdoInt32 GetDimensionality() const = 0;
+};
+}}}
+
+=== IArcSegmentAbstract ===
+
+{{{
+/// \brief
+/// The FdoIArcSegmentAbstract class is an arc curve segment (abstract)
+class FdoIArcSegmentAbstract : public FdoICurveSegmentAbstract
+{
+public:
+    /// \brief
+    /// Gets some position along the curve, between the starting and ending positions.
+    /// 
+    /// \remarks
+    /// Depending on the derived type and its implementation, this may be a 
+    /// computed value, or a persisted value used as part
+    /// of the definition of the curve segment.  This position is the only
+    /// means to deduce the curve segment's orientation in some cases, such as
+    /// when it is closed or vertically aligned ('on edge' when looking along 
+    /// the Z axis).
+    /// 
+    /// \return
+    /// Returns a midpoint on the curve
+    /// 
+    FDO_GEOM_API virtual FdoIDirectPosition* GetMidPoint() const = 0;
+};
+}}}
+
+=== ICircularArcSegment ===
+
+{{{
+/// \brief
+/// The FdoICircularArcSegment class is a circular arc curve segment
+class FdoICircularArcSegment : public FdoIArcSegmentAbstract
+{
+protected:
+    /// \brief
+    /// Default destructor.
+    /// 
+    /// \return
+    /// Returns nothing
+    /// 
+    FDO_GEOM_API virtual ~FdoICircularArcSegment() {};
+};
+}}}
+
+=== ILineStringSegment ===
+
+{{{
+/// \brief
+/// The FdoILineStringSegment class is a LineString curve segment type.  
+/// The shape of FdoILineStringSegment is the set of positions defined
+/// by the contained collection, plus linear interpolation between 
+/// consecutive points. This is a helper type for Geometries in the 
+/// Geometry package.
+///
+/// \remarks
+/// It does not derive from IGeometry.
+///
+class FdoILineStringSegment : public FdoICurveSegmentAbstract
+{
+public:
+    /// \brief
+    /// Gets the number of positions in this object.
+    /// 
+    /// \return
+    /// Returns the number of positions
+    /// 
+    FDO_GEOM_API virtual FdoInt32 GetCount() const = 0;
+
+    /// \brief
+    /// Gets the position at the specified (zero-based) index.
+    /// 
+    /// \return
+    /// Returns the position
+    /// 
+    FDO_GEOM_API virtual FdoIDirectPosition* GetItem(FdoInt32 index) const = 0;
+
+    /// \brief
+    /// Gets a collection of all of the positions in this object.
+    /// 
+    /// \return
+    /// Returns the positions
+    /// 
+    FDO_GEOM_API virtual FdoDirectPositionCollection* GetPositions() = 0;
+
+    /// \brief
+    /// Gets the ordinates 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 ordinates
+    /// 
+    FDO_GEOM_API virtual const double * GetOrdinates() = 0;
+};
+}}}
+ 
+== Appendix B: Questions and Answers ==
+
+== ICircleSegment vs. ICircle ==
+
+Question:
+
+What if we change the proposal to derive FdoICircleSegment directly from FdoICurveAbstract, in the process renaming FdoICircleSegment to be FdoICircle.  To me, this has some merit, since as currently described, a circle must be closed and cannot be combined with any other ArcSegment Types to form complex curve strings. They can only stand alone, and wrapping it in a CurveString seems wasteful. If a user wished to define a non-closed circle, they would use ICircularArcSegment.  
+
+Response: 
+
+The FdoICircle may be something of a hard sell. In OGC, Circle extends Arc, which extends ArcString, which extends CurveSegment, which implements GenericCurve.
+
+== Can ICircularArcSegment Describe a Closed Circle ==
+
+Question:
+
+I’m not sure how CircularArcSegment can describe a full circle.  if the start and end points are identical, then you only have two points (start/end and mid-point), which does not define the plane of the arc for XYZ dimensionality.
+
+Response: 
+
+For the rest of this explanation, it’s assumed that the circle is complete (start and end are same position).
+
+Take the line that is formed by the start and mid positions.  The normal to that line in the XY plane forms another line through the circle to orient it.  The circle is treated as if you simply tilted it out of the XY plane by grabbing the mid position.
+
+There is a position of ambiguity:  if the circle is standing perfectly on edge so that the start and mid positions coincide in XY (but have different Z).
+
+This (using an FDO circle in 3D) works for round-tripping and a few special functions such as tessellation.  However, there are several weak points in Map that assume circular arcs to be in the XY plane.  These should be addressed by the time that we add support for more geometry types, assuming that 3D support will be required for all of them.
+
+
 == Implications ==