ArcObjects Library Reference (Geometry)

IMSegmentation2.CalibrateByDistance Method

Calibrates Ms of existing vertices using new Ms from the input points and the shortest path distances along the polyline between those points. The update method is given as a combination of esriGeometryUpdateMEnum values.

[Visual Basic .NET]
Public Function CalibrateByDistance ( _
    ByVal Points As IEnumVertex, _
    ByVal updateHow As Integer, _
    ByVal ignoreGaps As Boolean, _
    ByVal cutoffDistance As Double _
) As IEnumSplitPoint

[C#]
public IEnumSplitPoint CalibrateByDistance (
    IEnumVertex Points,
    int updateHow,
    bool ignoreGaps,
    double cutoffDistance
);

[C++]
HRESULT CalibrateByDistance(
  IEnumVertex* Points,
  long updateHow,
  VARIANT_BOOL ignoreGaps,
  double cutoffDistance,
  IEnumSplitPoint** splitPoints
);

[C++]

Parameters

Points

Points is a parameter of type IEnumVertex

updateHow updateHow is a parameter of type long ignoreGaps ignoreGaps is a parameter of type VARIANT_BOOL cutoffDistance cutoffDistance is a parameter of type double splitPoints [out, retval]

splitPoints is a parameter of type IEnumSplitPoint

Product Availability

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

Remarks

The updateHow argument is given as a combination of esriGeometryUpdateMEnum values. When combining multiple values, the bitwise Or operator should always be used. This assures an error-free combination of the values (as long as the attempted combination is valid). Do not use the addition operator (+) to combine the values as unexpected results may occur.

For example, to interpolate between the input points and to extrapolate before and after the input points, you would use 7, which equates to: esriGeometryInterpolate OR esriGeometryExtrapolateBefore OR esriGeometryExtrapolateAfter. A value of 0 will only split the input polyline and assign the Ms value to the new created vertex. If an input point has the same X (or projected to the same X) as an existing vertex the Ms value of the existing vertex will be updated.

Note : The "After" and "Before" for the updateHow parameter is define by the order of the points in the multipoints. Ex : If the points are define from left to right the "Before" will be at the left of the first point and the "After" will be at the right of the last point.

The cutoffDistance parameter is an input Double that represents the distance from the polyline from where points are not considered anymore as being valid calibration points.

The following picture demonstrates graphically the method behavior. A updateHow paramater of 7 has been used.

esriGeometryInterpolate = 0001 (1) esriGeometryExtrapolateBefore = 0010 (2) esriGeometryExtrapolateAfter = 0100 (4)

[C#]

[C#]

public void CalibratePolyLineByDistance(IPolyline polyline, IMultipoint multipoint, int updateHow, bool ignoreGaps, double cutOffDistance)
{
  
  /*
  This function will use IMSegmentation2.CalibrateByDistance. This method
  calibrates the Ms using geometric distance. If you want to calibrate using
  some existing M values, then use IMSegmentation2.CalibrateByMs
  updateHow is a bitwise combination of these three values:
       esriGeometryInterpolate = 1
       esriGeometryExtrapolateBefore = 2
       esriGeometryExtrapolateAfter = 4
  Note that CalibrateByDistance does not require that MultiPoint's points
  fall on top of the PolyLine. You might consider adding some logic to make
  sure that the points fall on top of (e.g. ITopologicalOperator.Intersect)
  or are within a tolerance (e.g. IProximityOperator.ReturnDistance)
  If you pass in a PolyLine that is from a data source of unknown quality,
  you may consider calling IGeometryCollection.GeometriesChanged before
  you call IPolyLine.SimplifyNetwork below. This is because SimplifyNetwork
  will not do anything if the geometry is assumed to be simple. Calling
  GeometriesChanged tells the geometry that it is not simple.
  */

  //This operation must be performed on a simple geometry
  polyline.SimplifyNetwork();
   
  //The MultiPoint's points should have Ms
  IMAware mAware = multipoint as IMAware;
  if(!mAware.MAware)
  {
    return;
  } 
  //The PolyLine should be M Aware as well.
  mAware = polyline as IMAware;
  if(!mAware.MAware)
  {
    return;
  } 
  IMSegmentation2 mSegmentation = polyline as IMSegmentation2;
  IPointCollection pointCollection = multipoint as IPointCollection;
  IEnumVertex enumVertex = pointCollection.EnumVertices;
  IEnumSplitPoint enumSplitPoint = mSegmentation.CalibrateByDistance(enumVertex, updateHow, ignoreGaps, cutOffDistance);

  //Note that we do nothing with enumSplitPoint. IEnumSplitPoint specializes
  //IEnumVertex and gives additional information about the locations in a
  //PolyLine where it was split by a set of input points
  
}

[Visual Basic .NET]

Public Sub CalibratePolyLineByDistance(ByVal pPl As ESRI.ArcGIS.Geometry.IPolyline, ByVal pMP As ESRI.ArcGIS.Geometry.IMultipoint, _
ByVal updateHow As Long, ByVal ignoreGaps As Boolean, ByVal dCOffDist As Double)

        '+++ This function will use IMSegmentation2::CalibrateByDistance. This function
        '+++ calibrates the Ms using geometric distance. If you want to calibrate using
        '+++ some existing M values, then use IMSegmentation2::CalibrateByMs

        '+++ updateHow is a bitwise combination of these three values:
        '+++       esriGeometryInterpolate = 1
        '+++       esriGeometryExtrapolateBefore = 2
        '+++       esriGeometryExtrapolateAfter = 4

        '+++ Note that CalibrateByDistance does not require that MultiPoint's points
        '+++ fall on top of the PolyLine. You might consider adding some logic to make
        '+++ sure that the points fall on top of (e.g. ITopologicalOperator::Intersect)
        '+++ or are within a tolerance (e.g. IProximityOperator::ReturnDistance)

        '+++ If you pass in a PolyLine that is from a data source of unknown quality,
        '+++ you may consider calling IGeometryCollection::GeometriesChanged before
        '+++ you call IPolyLine::SimplifyNetwork below. This is because SimplifyNetwork
        '+++ will not do anything if the geometry is assumed to be simple. Calling
        '+++ GeometriesChanged tells the geometry that it is not simple.

'+++ This operation must be performed on a simple geometry
pPl.SimplifyNetwork()

Dim pMA As ESRI.ArcGIS.Geometry.IMAware
Dim pMSeg As ESRI.ArcGIS.Geometry.IMSegmentation2

        '+++ The MultiPoint's points should have Ms
        pMA = pMP
        If Not pMA.MAware Then _
          Err.Raise(vbObjectError + 11282000, "CalibratePolyLineByDistance", "MultiPoint Not M Aware")

        '+++ The PolyLine should be M Aware as well.
        pMA = Nothing
        pMA = pPl
        If Not pMA.MAware Then
            Err.Raise(vbObjectError + 11282000, "CalibratePolyLineByDistance", "PolyLine Not M Aware")
        Else
            Dim pPC As ESRI.ArcGIS.Geometry.IPointCollection
            Dim pEnumV As ESRI.ArcGIS.Geometry.IEnumVertex
            Dim pEnumSp As ESRI.ArcGIS.Geometry.IEnumSplitPoint
            pMSeg = pMA
            pPC = pMP
            pEnumV = pPC.EnumVertices
            pEnumSp = pMSeg.CalibrateByDistance(pEnumV, updateHow, ignoreGaps, dCOffDist)
        End If

        '+++ Note that we do nothing with pEnumSp. IEnumSplitPoint specializes
        '+++ IEnumVertex and gives additional information about the locations in a
        '+++ PolyLine where it was split by a set of input points

End Sub

IMSegmentation2.CalibrateByDistance Method

Product Availability

Remarks

See Also