IMSegmentation2 Interface

Provides access to additional linear referencing operations on polylines.

Members

	Name	Description
	CalculateNonSimpleMs	Redefines the non-simple Ms to be values obtained from interpolation of surrounding defined Ms, or extrapolation of Ms.
	CalibrateByDistance	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.
	CalibrateByMs	Calibrates Ms of existing vertices using new Ms from the input points and existing Ms along shortest paths between those points. The update method is given as a combination of esriGeometryUpdateMEnum values.
	ExtrapolateMs	Extrapolates the Ms at one or both ends of the geometry based on the M interval between the fromIndex and the toIndex.
	GetDistancesAtM	Returns an array of distances along the polyline at which is located the specified M. If the geometry's M's are monotonic along the geometry then the array will only have one element.
	GetMsAtDistance	Returns M values at the distance along the geometry. An array of one or two Ms is returned. Two Ms can be returned if the given distance is exactly at the beginning or ending of a part.
	GetPointsAtM	Returns a multipoint geometry corresponding to the locations along the geometry where the specified M occurs.
	GetSubcurveBetweenMs	Returns a polyline geometry corresponding to the subcurve(s) between the fromM and the toM.
	GetSubcurveBetweenMsEx	Returns a polyline geometry corresponding to the subcurve(s) between the fromM and the toM values. The 'details' arguments are composed of esriMCurveRelationEnum values.
	InsertMAtDistance	Sets the M value at the given distance along the geometry; creates a point at that distance if no point exists there.
	InterpolateMsBetween	Generates Ms by linear interpolation of segment distances for all vertices in the range [start+1, end-1].
	MMax	The maximum M value.
	MMin	The minimum M value.
	MMonotonic	A value indicating whether Ms are monotonic, and if so, whether they are ascending or descending.
	MultiplyMs	Multiplies all the M values by a factor.
	OffsetMs	Offsets all the M values by an offset value.
	ReverseMsOrder	Reverses the order of the Ms along the geometry.
	SetAndInterpolateMsBetween	Sets the Ms at the beginning and the end of the geometry and interpolates the M values between these values.
	SetMsAsDistance	Sets the M values to the cumulative length from the origin of the geometry.
	SetMsAsDistance2	Sets Ms on vertices as scaled and offset distances from the input origin as measured along the polyline. Shortest path distances from the origin are used. Optionally ignores distances between parts of the polyline.
	UpdateMsByDistance	Updates Ms along the shortest path between the specified endpoints. The interpolation ratio is determined by the input ms and euclidean distance along that path. The update method is given as a combination of esriGeometryUpdateMEnum values.
	UpdateMsByMs	Updates Ms along the shortest path between the specified endpoints. The interpolation ratio is determined by the existing ms along that path and the input ms. The update method is given as a combination of esriGeometryUpdateMEnum values.

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.

Public Function CalibrateByDistance ( _
    ByVal Points As IEnumVertex, _
    ByVal updateHow As Integer, _
    ByVal ignoreGaps As Boolean, _
    ByVal cutoffDistance As Double _
) As IEnumSplitPoint

public IEnumSplitPoint CalibrateByDistance (
    IEnumVertex Points,
    int updateHow,
    bool ignoreGaps,
    double cutoffDistance
);

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)




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

}

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.CalibrateByMs Method

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

Public Function CalibrateByMs ( _
    ByVal Points As IEnumVertex, _
    ByVal updateHow As Integer, _
    ByVal cutoffDistance As Double _
) As IEnumSplitPoint

public IEnumSplitPoint CalibrateByMs (
    IEnumVertex Points,
    int updateHow,
    double cutoffDistance
);

Remarks

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.

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

public void CalibratePolyLineByMs(IPolyline polyline, IMultipoint multipoint, int updateHow, double cutOffDistance)

{

  /*

   This function will use IMSegmentation2.CalibrateByMs. This function

   calibrates the Ms using measure distance. If you want to calibrate using

   some existing geometric distance, then use IMSegmentation2.CalibrateByDistance

  

   updateHow is a bitwise combination of these three values:

         esriGeometryInterpolate = 1

         esriGeometryExtrapolateBefore = 2

         esriGeometryExtrapolateAfter = 4

  

   Note that CalibrateByMs does not require that the 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

  */

  //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.CalibrateByMs(enumVertex, updateHow, 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

  

}

Public Sub CalibratePolyLineByMs(ByVal pPl As ESRI.ArcGIS.Geometry.IPolyline, ByVal pMP As ESRI.ArcGIS.Geometry.IMultipoint, ByVal updateHow As Long, ByVal dCutOffDist As Double)

        '+++ This function will use IMSegmentation2::CalibrateByMs. This function  

        '+++ calibrates the Ms using measure distance. If you want to calibrate using  

        '+++ some existing geometric distance, then use IMSegmentation2::CalibrateByDistance    

        '+++ updateHow is a bitwise combination of these three values:  

        '+++       esriGeometryInterpolate = 1  

        '+++       esriGeometryExtrapolateBefore = 2  

        '+++       esriGeometryExtrapolateAfter = 4    

        '+++ Note that CalibrateByMs does not require that the 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, "CalibratePolyLineByMs", "MultiPoint Not M Aware")

        End If

        '+++ The PolyLine should be M Aware as well.  

        pMA = Nothing

        pMA = pPl

        If Not pMA.MAware Then

            Err.Raise(vbObjectError + 11282000, "CalibratePolyLineByMs", "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.CalibrateByMs(pEnumV, updateHow, dCutOffDist)

        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.GetSubcurveBetweenMsEx Method

Returns a polyline geometry corresponding to the subcurve(s) between the fromM and the toM values. The 'details' arguments are composed of esriMCurveRelationEnum values.

Public Function GetSubcurveBetweenMsEx ( _
    ByVal fromM As Double, _
    ByVal toM As Double, _
    ByRef fromMDetails As Integer, _
    ByRef toMDetails As Integer _
) As IGeometryCollection

public IGeometryCollection GetSubcurveBetweenMsEx (
    double fromM,
    double toM,
    ref int fromMDetails,
    ref int toMDetails
);

IMSegmentation2.SetMsAsDistance2 Method

Sets Ms on vertices as scaled and offset distances from the input origin as measured along the polyline. Shortest path distances from the origin are used. Optionally ignores distances between parts of the polyline.

Public Sub SetMsAsDistance2 ( _
    ByVal Origin As IPoint, _
    ByVal Scale As Double, _
    ByVal Offset As Double, _
    ByVal ignoreGaps As Boolean _
)

public void SetMsAsDistance2 (
    IPoint Origin,
    double Scale,
    double Offset,
    bool ignoreGaps
);

IMSegmentation2.UpdateMsByDistance Method

Updates Ms along the shortest path between the specified endpoints. The interpolation ratio is determined by the input ms and euclidean distance along that path. The update method is given as a combination of esriGeometryUpdateMEnum values.

Public Sub UpdateMsByDistance ( _
    ByVal fromPart As Integer, _
    ByVal FromPoint As Integer, _
    ByVal toPart As Integer, _
    ByVal ToPoint As Integer, _
    ByVal fromM As Double, _
    ByVal toM As Double, _
    ByVal updateHow As Integer, _
    ByVal ignoreGaps As Boolean _
)

public void UpdateMsByDistance (
    int fromPart,
    int FromPoint,
    int toPart,
    int ToPoint,
    double fromM,
    double toM,
    int updateHow,
    bool ignoreGaps
);

Remarks

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

IMSegmentation2.UpdateMsByMs Method

Updates Ms along the shortest path between the specified endpoints. The interpolation ratio is determined by the existing ms along that path and the input ms. The update method is given as a combination of esriGeometryUpdateMEnum values.

Public Sub UpdateMsByMs ( _
    ByVal fromPart As Integer, _
    ByVal FromPoint As Integer, _
    ByVal toPart As Integer, _
    ByVal ToPoint As Integer, _
    ByVal fromM As Double, _
    ByVal toM As Double, _
    ByVal updateHow As Integer _
)

public void UpdateMsByMs (
    int fromPart,
    int FromPoint,
    int toPart,
    int ToPoint,
    double fromM,
    double toM,
    int updateHow
);

Remarks

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

Inherited Interfaces

Interfaces	Description
IMSegmentation	Provides access to members for defining an M-based linear coordinate system on a polyline or polygon.
IMCollection	Provides access to members that control operations on M-aware multipoints, polylines, polygons and multipatches.

Classes that implement IMSegmentation2

Classes	Description
Polyline	An ordered collection of paths; optionally has measure, height and ID attributes.

Remarks

The IMSegmentation2 interface (like the IMSegmenation interface) also provides methods designed to work with the dynamic segmentation functionality in ArcObjects. These methods offer extended ways to interpolate and update the m attributes on a PolyLine, by cumulative distance and also by existing m values.