This document is archived and information here might be outdated.  Recommended version.


IConstructPoint.ConstructAlong Method (ArcObjects .NET 10.4 SDK)
ArcObjects Library Reference (Geometry)  

IConstructPoint.ConstructAlong Method

Constructs a point distance units along the input curve.

[Visual Basic .NET]
Public Sub ConstructAlong ( _
    ByVal curve As ICurve, _
    ByVal extension As esriSegmentExtension, _
    ByVal distance As Double, _
    ByVal asRatio As Boolean _
)
[C#]
public void ConstructAlong (
    ICurve curve,
    esriSegmentExtension extension,
    double distance,
    bool asRatio
);
[C++]
HRESULT ConstructAlong(
  ICurve* curve,
  esriSegmentExtension extension,
  double distance,
  VARIANT_BOOL asRatio
);
[C++]

Parameters curve
curve is a parameter of type ICurve extension
extension is a parameter of type esriSegmentExtension distance distance is a parameter of type double asRatio asRatio is a parameter of type VARIANT_BOOL

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.

Remarks

If the Distance parameter is less than zero, or greater than the length of the curve (when asRatio is false), or greater than one (when asRatio is true), then the value of the Extension parameter is used to determine the coordinates of the constructed point.  In these cases, the point can be placed somewhere along an embedding geometry, or somewhere along a tangent geometry.

The embedding geometry of a straight line segment is a straight line extending infinitely in both directions.  The embedding geometry of a circular arc is a complete circle.  The embedding geometry of an elliptic arc is a complete ellipse.  A bezier curve has no embedding geometry.

A tangent geometry is always a ray (a straight line extending infinitely in one direction) tangent to the input curve at either its from (start) or to (end) points.

Possible values for the Extension parameter are: 
-------------------------------------------------
esriNoExtension                      The constructed point will always be on the input curve.  A distance < 0 will pin the constructed point to the location of the input curve's from point. A distance > the curve length (or > 1 when asRatio is true) will pin the location to the curve's to point.

esriExtendTangentAtFrom        If the distance parameter is < 0 then the point is constructed along a ray tangent to the start point of the curve, in a direction away from the curve.

esriExtendTangentAtTo            If the distance parameter is greater than the length of the input curve (or > 1 when asRatio is true), then the constructed point is placed along a ray tangent to the end point of the curve, in a direction away from the curve.

esriExtendEmbeddedAtFrom   Similar to the tangent option, but uses the embedding geometry instead of the tangent lines.

esriExtendEmbeddedAtTo        Similar to the tangent option, but uses the embedding geometry instead of the tangent lines.

esriExtendEmbedded               The point is constructed based on either the start or end points of the curve.

esriExtendTangents                  The point is tangential extended from the start or endpoint of the curve.

These values can be combined using the VB Or operator, or the C++ bitwise OR operator.

Example 1:  esriExtendTangentAtFrom Or esriExtendTangentAtTo

Instead of using esriExtendTangents you could use esriExtendTangentAtFrom Or esriExtendTangentAtTo.This would allow the point to be constructed anywhere along infinte straight lines, beginning from either the start or end of the curve, regardless of whether the distance parameter was less than 0, or greater than the length of the input curve (or > 1 when asRatio is true).


ConstructPoint ConstructAlong Example

[C#]

        //Select a polyline in ArcMap and calculate a point along the line
        // at 100 distance units from the start point.
        public void ConstructPointAlongLine(IPolyline pl)
        {
            ICurve polyLine=pl;
            IPoint point1=ConstructPointAlong(100, polyLine, esriSegmentExtension.esriNoExtension, false);
            System.Windows.Forms.MessageBox.Show("x,y=" + point1.X + "," + point1.Y);
            IPoint point2=ConstructPointAlong(0.5, polyLine, esriSegmentExtension.esriNoExtension, true);
            System.Windows.Forms.MessageBox.Show("x,y=" + point2.X + "," + point2.Y);
        }


        public IPoint ConstructPointAlong(double distance, ICurve curve, esriSegmentExtension extension, bool asRatio)
        {
            IConstructPoint contructionPoint=new PointClass();
            contructionPoint.ConstructAlong(curve, extension, distance, asRatio);
            return contructionPoint as IPoint;
        }

[Visual Basic .NET]

    '+++ Calculate a point along a polyline
    '+++ at 100 distance units from the start point.

    Public Sub t_ConstructAlong(ByRef pPolyLine As ESRI.ArcGIS.Geometry.IPolyline)
        On Error GoTo Errorhandler
        Dim pPoint As ESRI.ArcGIS.Geometry.IPoint

        Dim pCrv As ESRI.ArcGIS.Geometry.ICurve
        pCrv=pPolyLine
        pPoint=PtConstructAlong(100, pCrv, ESRI.ArcGIS.Geometry.esriSegmentExtension.esriNoExtension, False)
        MsgBox("x,y=" & pPoint.X & "," & pPoint.Y)

        pPoint=PtConstructAlong(0.5, pPolyLine, ESRI.ArcGIS.Geometry.esriSegmentExtension.esriNoExtension, True) ' Midpoint
        MsgBox("x,y=" & pPoint.X & "," & pPoint.Y)

        Exit Sub

Errorhandler:
        MsgBox(Err.Number & "..." & Err.Description)
        Exit Sub

    End Sub

    Public Function PtConstructAlong(ByVal dDist As Double, ByVal pCurve As ESRI.ArcGIS.Geometry.ICurve, ByVal extension As ESRI.ArcGIS.Geometry.esriSegmentExtension, ByVal asRatio As Boolean) As ESRI.ArcGIS.Geometry.IPoint
        Dim pCPoint As ESRI.ArcGIS.Geometry.IConstructPoint
        pCPoint=New ESRI.ArcGIS.Geometry.Point
        pCPoint.ConstructAlong(pCurve, extension, dDist, asRatio)
        PtConstructAlong=pCPoint
    End Function

See Also

IConstructPoint Interface

.NET Samples

Points along line construction tool (Code Files: PointsAlongLineForm)