Interface IMSegmentation2

Namespace
ESRI.ArcGIS.Geometry
Assembly
ESRI.Server.Geometry.dll

Provides access to additional linear referencing operations on polylines.

[Guid("B80D4790-F452-11D3-9F69-00C04F6BDD7F")]
[InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
public interface IMSegmentation2 : IMSegmentation, IMCollection

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.

Properties

MMax

double MMax { get; }

Property Value

double

MMin

double MMin { get; }

Property Value

double

MMonotonic

esriMMonotonicEnum MMonotonic { get; }

Property Value

esriMMonotonicEnum

Methods

CalculateNonSimpleMs()

void CalculateNonSimpleMs()

CalibrateByDistance(IEnumVertex, int, bool, double)

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.

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

Parameters

Points IEnumVertex
updateHow int
ignoreGaps bool
cutoffDistance double

Returns

IEnumSplitPoint

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)

0001
0010
0100
----
0111
[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

CalibrateByMs(IEnumVertex, int, double)

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.

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

Parameters

Points IEnumVertex
updateHow int
cutoffDistance double

Returns

IEnumSplitPoint

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.

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.

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

esriGeometryInterpolate = 0001 (1)
esriGeometryExtrapolateBefore = 0010 (2)
esriGeometryExtrapolateAfter = 0100 (4)
	0001
	0010
	0100
	----
	0111
[C#]

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
 
}




[Visual Basic .NET]

    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

















ExtrapolateMs(esriExtrapolationEnum, int, int, int, int)

void ExtrapolateMs(esriExtrapolationEnum extrapolationStyle, int fromPart, int FromPoint, int toPart, int ToPoint)

Parameters

extrapolationStyle esriExtrapolationEnum
fromPart int
FromPoint int
toPart int
ToPoint int

GetDistancesAtM(bool, double)

object GetDistancesAtM(bool asRatio, double M)

Parameters

asRatio bool
M double

Returns

object

GetMsAtDistance(double, bool)

object GetMsAtDistance(double distance, bool asRatio)

Parameters

distance double
asRatio bool

Returns

object

GetPointsAtM(double, double)

IGeometryCollection GetPointsAtM(double M, double lateralOffset)

Parameters

M double
lateralOffset double

Returns

IGeometryCollection

GetSubcurveBetweenMs(double, double)

IGeometryCollection GetSubcurveBetweenMs(double fromM, double toM)

Parameters

fromM double
toM double

Returns

IGeometryCollection

GetSubcurveBetweenMsEx(double, double, ref int, ref int)

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

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

Parameters

fromM double
toM double
fromMDetails int
toMDetails int

Returns

IGeometryCollection

InsertMAtDistance(double, double, bool, bool, out bool, out int, out int)

void InsertMAtDistance(double M, double distance, bool asRatio, bool createPart, out bool SplitHappened, out int newPartIndex, out int newSegmentIndex)

Parameters

M double
distance double
asRatio bool
createPart bool
SplitHappened bool
newPartIndex int
newSegmentIndex int

InterpolateMsBetween(int, int, int, int)

void InterpolateMsBetween(int fromPart, int FromPoint, int toPart, int ToPoint)

Parameters

fromPart int
FromPoint int
toPart int
ToPoint int

MultiplyMs(double)

void MultiplyMs(double factor)

Parameters

factor double

OffsetMs(double)

void OffsetMs(double Offset)

Parameters

Offset double

ReverseMsOrder()

void ReverseMsOrder()

SetAndInterpolateMsBetween(double, double)

void SetAndInterpolateMsBetween(double fromM, double toM)

Parameters

fromM double
toM double

SetMsAsDistance(bool)

void SetMsAsDistance(bool asRatio)

Parameters

asRatio bool

SetMsAsDistance2(IPoint, double, double, bool)

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.

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

Parameters

Origin IPoint
Scale double
Offset double
ignoreGaps bool

UpdateMsByDistance(int, int, int, int, double, double, int, bool)

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.

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

Parameters

fromPart int
FromPoint int
toPart int
ToPoint int
fromM double
toM double
updateHow int
ignoreGaps bool

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

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

UpdateMsByMs(int, int, int, int, double, double, int)

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.

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

Parameters

fromPart int
FromPoint int
toPart int
ToPoint int
fromM double
toM double
updateHow int

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

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

0001 0010 0100

0111